nimajafari/lighthouse-skill

Lighthouse

Exécutez Google Lighthouse pour mesurer la qualité Web et vérifier que les correctifs ont réellement fait bouger les chiffres. Lighthouse audite une URL sur les Performances, l'Accessibilité, le SEO et les Bonnes pratiques et retourne un score de 0 à 100 par catégorie ainsi qu'une liste d'audits en échec avec des conseils précis.

Quand utiliser cette compétence

Cette compétence mesure. Les compétences qualité associées corrigent. Le flux de travail est une boucle :

mesurer (cette compétence) → corriger (performances / accessibilité / SEO / bonnes pratiques) → remesurer

Utilisez cette compétence pour : obtenir un score de référence, trouver les audits en échec spécifiques, définir un budget de performance, verrouiller un build en CI, ou prouver qu'un changement a amélioré (ou régressé) une métrique. Ne devinez pas les améliorations — mesurez, modifiez une chose, mesurez à nouveau.

Comment ça fonctionne

1. Choisissez une URL cible — une URL déployée, ou un serveur local de développement/prévisualisation (http://localhost:3000).
2. Exécutez Lighthouse — privilégiez scripts/run-lighthouse.sh <url> ; il exécute plusieurs passages, prend la médiane, et émet un JSON compact (les rapports complets sont trop volumineux et gaspillent du contexte).
3. Lisez les scores des catégories et les audits en échec à partir du JSON.
4. Mappez chaque audit en échec à un correctif en utilisant la compétence qualité correspondante.
5. Réexécutez et rapportez le delta avant/après.

Installation et exécution (CLI)

Le fichier README de Lighthouse l'installe globalement (nécessite Node 22 LTS+), et il nécessite un Chrome/Chromium local que vous devez avoir installé :

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

lighthouse https://example.com --view    # exécution de base ; --view ouvre le rapport HTML

Lighthouse détecte automatiquement un Chrome installé ; pointez-le vers un binaire spécifique avec la variable d'environnement CHROME_PATH.

Pour une exécution rapide sans installation globale, npx lighthouse <url> fonctionne aussi — le binaire CLI publié le prend en charge, bien que la documentation officielle ne couvre que l'installation globale.

Exécution lisible par machine pour un agent (JSON dans un fichier, silencieux, sans tête) :

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

Le script d'encapsulation (recommandé)

scripts/run-lighthouse.sh encapsule la CLI, exécute N passages, choisit le passage médian (recommandation de Lighthouse elle-même pour réduire la variance), et affiche le JSON compact sur la sortie standard — scores des catégories plus les audits en échec uniquement. Les logs humains vont sur la sortie d'erreur standard.

# Utilisation : run-lighthouse.sh <url> [passages] [catégories]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility

Exemple de sortie :

{
  "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": "Économies potentielles de 180 Ko" }
  ]
}

Principaux drapeaux

Drapeau	Objectif
`--output=json	html
--output-path=<chemin>	Où écrire le rapport
--only-categories=…	Limiter à performance,accessibility,seo,best-practices
--preset=desktop	Configuration de bureau (par défaut mobile : téléphone milieu de gamme émulé + 4G lente)
--chrome-flags="--headless=new"	Exécution sans tête (CI/serveurs)
--budget-path=budget.json	Appliquer un budget de performance (LightWallet)
`--throttling-method=simulate	devtools
--quiet	Supprimer les logs de progression
--view	Ouvrir le rapport HTML une fois terminé

Lecture du JSON

Les scores sont des flottants 0–1 sous categories ; les détails des audits sont sous audits.

# Scores des catégories (0–1) → multiplier par 100 pour le score familier
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json

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

# Audits en échec / d'opportunité qui méritent d'être traités
jq '[.audits[] | select(.score != null and .score < 0.9)
     | {id, score, displayValue}]' lh.json

Budgets de performance (LightWallet)

Faire échouer l'exécution lorsque les ressources ou les timings dépassent un seuil. Un fichier prêt à modifier examples/budget.json est fourni avec cette compétence ; la structure est :

[
  {
    "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

Les tailles sont en Ko, les timings en ms. Les résultats du budget atterrissent sous les audits performance-budget et timing-budget dans le JSON.

Laboratoire vs. terrain — lisez ceci avant de faire confiance à un chiffre

Lighthouse est un outil de laboratoire : une charge synthétique unique, sur du matériel émulé, avec une limitation simulée. Il est reproductible et excellent pour détecter les régressions, mais il ne correspond pas à ce que les utilisateurs réels vivent.

• La variance est réelle. Une seule exécution peut varier de ±5 à 10 points. Exécutez au moins 3 passages et prenez la médiane (le script d'encapsulation le fait).
• Pour les données utilisateur réelles, utilisez plutôt des sources terrain : CrUX, PageSpeed Insights (qui montre à la fois les données lab + terrain), le rapport Core Web Vitals de Search Console, ou la bibliothèque web-vitals rapportant à vos analytics.
• L'INP ne peut pas être mesurée en une seule charge Lighthouse — elle nécessite des interactions réelles. Lighthouse rapporte le Total Blocking Time (TBT) comme son proxy de laboratoire ; traitez l'INP terrain comme source de vérité.

Note sur Lighthouse v13 (Insight Audits)

Depuis v13 (octobre 2025+), Lighthouse a migré les Performances vers les Insight Audits. Plusieurs identifiants d'audits hérités par opportunité ont été fusionnés ou supprimés (par exemple, les audits liés au CLS → cls-culprits-insight, les audits d'images → image-delivery-insight). Les conseils restent inchangés ; seuls les identifiants d'audits et le regroupement des rapports ont changé. Lors de l'analyse de rapports plus anciens, traitez-les comme un sur-ensemble, pas une contradiction. Épinglez une version de Lighthouse en CI pour que les identifiants d'audits sur lesquels vous vous basez restent stables.

Comment le score de performance est construit

Le score de performance est un mélange pondéré de métriques de laboratoire (les poids changent entre les versions). Dans les versions récentes, les plus importants sont approximativement :

Métrique	Poids approximatif
Total Blocking Time (TBT)	~30 %
Largest Contentful Paint (LCP)	~25 %
Cumulative Layout Shift (CLS)	~25 %
First Contentful Paint (FCP)	~10 %
Speed Index	~10 %

Puisque TBT/LCP/CLS dominent, les corriger fait le plus bouger le score. Utilisez le Calculateur de score Lighthouse pour voir exactement comment un changement de métrique se traduit en points.

CI et API programmatique

Conservés dans des références pour rester concentrés :

• Intégration continue — @lhci/cli, assertions lighthouserc.js, et un workflow GitHub Actions : references/CI.md
• API (Node) programmatique — piloter Lighthouse avec chrome-launcher pour des flux personnalisés, des flux utilisateur, et des exécutions en masse : references/PROGRAMMATIC-API.md

Mappage des audits aux correctifs

Catégorie Lighthouse	Corriger avec
Performances / Core Web Vitals	une compétence performances ou Core Web Vitals
Accessibilité	une compétence accessibilité / WCAG
SEO	une compétence SEO
Bonnes pratiques	une compétence sécurité / bonnes pratiques

Associez cette compétence à addyosmani/web-quality-skills pour la partie correction de la boucle.

Références

• Dépôt Lighthouse
• Options CLI de Lighthouse
• Budgets de performance / LightWallet
• Lighthouse CI
• Scoring
• Configuration CI · API programmatique