nimajafari/lighthouse-skill

Lighthouse

Ejecuta Google Lighthouse para medir la calidad web y verificar que las correcciones realmente movieron los números. Lighthouse audita una URL en las categorías de Rendimiento, Accesibilidad, SEO y Buenas Prácticas, y devuelve una puntuación de 0–100 por categoría, además de una lista de auditorías fallidas con orientación específica.

Cuándo usar esta habilidad

Esta habilidad mide. Las habilidades hermanas de calidad corrigen. El flujo de trabajo es un bucle:

medir (esta habilidad)  →  corregir (rendimiento / accesibilidad / seo / buenas prácticas)  →  volver a medir

Recurre a esta habilidad para: obtener una puntuación base, encontrar las auditorías fallidas específicas, establecer un presupuesto de rendimiento, bloquear una compilación en CI, o demostrar que un cambio mejoró (o empeoró) una métrica. No adivines las mejoras: mide, cambia una cosa, vuelve a medir.

Cómo funciona

1. Elige una URL objetivo — una URL desplegada, o un servidor local de desarrollo/previsualización (http://localhost:3000).
2. Ejecuta Lighthouse — prefiere scripts/run-lighthouse.sh <url>; ejecuta varias veces, toma la mediana y emite JSON compacto (los informes completos son enormes y desperdician contexto).
3. Lee las puntuaciones de categoría + auditorías fallidas del JSON.
4. Asigna cada auditoría fallida a una corrección usando la habilidad de calidad relevante.
5. Vuelve a ejecutar e informa el delta antes/después.

Instalación y ejecución (CLI)

El readme de Lighthouse lo instala de forma global (requiere Node 22 LTS+), y necesita un Chrome/Chromium local que debes tener instalado:

npm install -g lighthouse
# o: yarn global add lighthouse

lighthouse https://example.com --view    # ejecución básica; --view abre el informe HTML

Lighthouse detecta automáticamente un Chrome instalado; apúntalo a un binario específico con la variable de entorno CHROME_PATH.

Para una ejecución rápida sin instalación global, npx lighthouse <url> también funciona; el binario CLI publicado lo soporta, aunque la documentación oficial solo cubre la instalación global.

Ejecución legible por máquina para un agente (JSON a un archivo, silencioso, headless):

npx lighthouse https://example.com \
  --quiet \
  --chrome-flags="--headless=new" \
  --only-categories=performance,accessibility,seo,best-practices \
  --output=json --output-path=./lh.json

El script envolvente (recomendado)

scripts/run-lighthouse.sh envuelve la CLI, ejecuta N veces, elige la ejecución mediana (recomendación de Lighthouse para reducir la varianza) e imprime JSON compacto en stdout — solo las puntuaciones de categoría y las auditorías fallidas. Los logs humanos van a stderr.

# Uso: run-lighthouse.sh <url> [ejecuciones] [categorías]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility

Ejemplo de salida:

{
  "success": true,
  "url": "https://example.com",
  "runs": 3,
  "lighthouseVersion": "13.x",
  "scores": { "performance": 78, "accessibility": 95, "seo": 92, "best-practices": 96 },
  "failingAudits": [
    { "id": "largest-contentful-paint", "score": 0.4, "displayValue": "4.2 s" },
    { "id": "unused-javascript", "score": 0.3, "displayValue": "Potential savings of 180 KiB" }
  ]
}

Banderas clave

Bandera	Propósito
--output=json|html|csv	Formato del informe (repetir para varios)
--output-path=<ruta>	Dónde escribir el informe
--only-categories=…	Limitar a performance,accessibility,seo,best-practices
--preset=desktop	Configuración de escritorio (por defecto es móvil: emulación de teléfono de gama media + 4G lento)
--chrome-flags="--headless=new"	Ejecutar sin interfaz (CI/servidores)
--budget-path=budget.json	Aplicar un presupuesto de rendimiento (LightWallet)
--throttling-method=simulate|devtools|provided	Cómo limitar (simulate es la limitación de laboratorio por defecto)
--quiet	Suprimir el registro de progreso
--view	Abrir el informe HTML al terminar

Leyendo el JSON

Las puntuaciones son flotantes 0–1 bajo categories; los detalles de auditoría están bajo audits.

# Puntuaciones de categoría (0–1) → multiplicar por 100 para la puntuación familiar
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json

# Valores de laboratorio de Core Web Vitals
jq '.audits | {
  LCP: .["largest-contentful-paint"].displayValue,
  CLS: .["cumulative-layout-shift"].displayValue,
  TBT: .["total-blocking-time"].displayValue
}' lh.json

# Auditorías fallidas/de oportunidad que vale la pena abordar
jq '[.audits[] | select(.score != null and .score < 0.9)
     | {id, score, displayValue}]' lh.json

Presupuestos de rendimiento (LightWallet)

Fallar la ejecución cuando los activos o los tiempos superan un umbral. Un examples/budget.json listo para editar se incluye con esta habilidad; la forma es:

[
  {
    "path": "/*",
    "timings": [
      { "metric": "largest-contentful-paint", "budget": 2500 },
      { "metric": "interactive", "budget": 3800 }
    ],
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "stylesheet", "budget": 100 },
      { "resourceType": "image", "budget": 500 },
      { "resourceType": "total", "budget": 1500 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 10 }
    ]
  }
]

lighthouse https://example.com --budget-path=budget.json --output=json --output-path=./lh.json

Los tamaños están en KB, los tiempos en ms. Los resultados del presupuesto aparecen bajo las auditorías performance-budget y timing-budget en el JSON.

Laboratorio vs. campo — lee esto antes de confiar en un número

Lighthouse es una herramienta de laboratorio: una carga sintética, en hardware emulado, con limitación simulada. Es reproducible y excelente para detectar regresiones, pero no es lo que experimentan los usuarios reales.

• La varianza es real. Una sola ejecución puede variar ±5–10 puntos. Ejecuta al menos 3 veces y toma la mediana (el script envolvente hace esto).
• Para datos de usuarios reales, usa fuentes de campo en su lugar: CrUX, PageSpeed Insights (que muestra tanto laboratorio como campo), el informe de Core Web Vitals de Search Console, o la librería web-vitals que reporta a tu analítica.
• INP no se puede medir en una sola carga de Lighthouse — necesita interacciones reales. Lighthouse reporta el Total Blocking Time (TBT) como su proxy de laboratorio; trata el INP de campo como fuente de verdad.

Nota sobre Lighthouse v13 (auditorías de Insights)

Desde v13 (octubre de 2025+), Lighthouse migró Rendimiento a Auditorías de Insights. Varios ID de auditorías de oportunidad heredadas se fusionaron o eliminaron (por ejemplo, auditorías relacionadas con CLS → cls-culprits-insight, auditorías de imágenes → image-delivery-insight). El consejo no cambió; solo se movieron los ID de auditoría y la agrupación del informe. Al analizar informes antiguos, trátalos como un superconjunto, no como una contradicción. Fija una versión de Lighthouse en CI para que los ID de auditoría que afirmes se mantengan estables.

Cómo se construye la puntuación de Rendimiento

La puntuación de Rendimiento es una combinación ponderada de métricas de laboratorio (los pesos cambian entre versiones). A partir de versiones recientes, los más influyentes son aproximadamente:

Métrica	Peso aprox.
Total Blocking Time (TBT)	~30%
Largest Contentful Paint (LCP)	~25%
Cumulative Layout Shift (CLS)	~25%
First Contentful Paint (FCP)	~10%
Speed Index	~10%

Dado que TBT/LCP/CLS dominan, corregirlos mueve más la puntuación. Usa la Calculadora de Puntuación de Lighthouse para ver exactamente cómo un cambio en una métrica se traduce en puntos.

CI y la API programática

Se mantienen en referencias para mantener el enfoque:

• Integración continua — @lhci/cli, aserciones de lighthouserc.js y un flujo de trabajo de GitHub Actions: references/CI.md
• API programática (Node.js) — manejar Lighthouse con chrome-launcher para flujos personalizados, flujos de usuario y ejecuciones masivas: references/PROGRAMMATIC-API.md

Asignación de auditorías a correcciones

Categoría de Lighthouse	Corregir con
Rendimiento / Core Web Vitals	una habilidad de rendimiento o Core Web Vitals
Accesibilidad	una habilidad de accesibilidad / WCAG
SEO	una habilidad de SEO
Buenas Prácticas	una habilidad de seguridad / buenas prácticas

Combina esta habilidad con addyosmani/web-quality-skills para la parte de corrección del bucle.

Referencias

• Repositorio de Lighthouse
• Opciones de CLI de Lighthouse
• Presupuestos de rendimiento / LightWallet
• Lighthouse CI
• Puntuación
• Configuración de CI · API programática