--- name: "lighthouse-pagespeed-stinger" license: AGPL-3.0-or-later description: "Runs Lighthouse and PageSpeed Insights for React/Next.js: CI setup (LHCI), audit categories, performance budgets, lab-vs-CrUX gap. Use when setting up or debugging Lighthouse CI." --- # lighthouse-pagespeed-stinger Opinionated playbook for running Lighthouse and PageSpeed Insights correctly: in CI, locally, and as part of a long-term performance tracking strategy. Synthesized from the Lighthouse 12.6.1 + LHCI 0.15.x canon, the web.dev lab-vs-field framework, and 2025-2026 practitioner patterns. **Read first:** `guides/00-runner-selection.md`: the decision tree for which tool to use before you touch any config. --- ## When to use this skill Load this skill when `lighthouse-pagespeed-wasp-drone` is invoked. Trigger phrases: - "Set up Lighthouse CI / LHCI" - "Add a performance budget to our CI pipeline" - "My Lighthouse score is 90 but CrUX says I'm failing LCP" - "Configure Lighthouse for GitHub Actions" - "What's the difference between TBT and INP?" - "Compare Treo vs SpeedCurve for monitoring" - "Write a custom Lighthouse plugin" - "Audit this URL with Lighthouse" - "Set a performance budget" Do NOT load for: - SEO content strategy, keyword research, or metadata optimization (route to `seo-aeo-wasp-drone`) - Core Web Vitals implementation fixes like image optimization or JS bundle reduction (route to `react-wasp-drone` or `performance-optimizer`) - Accessibility design decisions beyond Lighthouse-flagged technical issues - CI/CD pipeline topology beyond the Lighthouse-specific configuration step (route to `devops-wasp-drone`) --- ## Critical directives These are non-negotiables. They protect reproducibility, team trust, and the lab-vs-field mental model. - **Always specify throttling and form-factor explicitly.** A mobile simulation at 4x CPU / 1.6 Mbps and a desktop no-throttle run produce completely different scores; mixing them corrupts trend data. See `guides/00-runner-selection.md`. - **Run at least three passes; report the median.** LHCI defaults to three runs for this reason (`numberOfRuns: 3`). A single Lighthouse run has high variance due to non-deterministic CPU and network simulation. See `guides/01-lhci-configuration.md`. - **Always present both lab scores and CrUX field data when PSI API data is available.** Lab data reflects ideal conditions; field data (p75) reflects real users. The gap between them is often the most actionable signal. See `guides/02-lab-vs-field.md`. - **Never set a score budget below the current production baseline without a remediation plan.** Measure first (`lhci autorun` without assertions), document baselines, then add a 10-20% buffer. A budget that gates CI on day one with no remediation plan blocks deploys without unblocking the team. See `guides/01-lhci-configuration.md`. - **TBT is an imperfect proxy for INP. A good TBT does not guarantee a good INP.** INP measures full interaction latency (delay + processing + presentation). TBT only captures blocking tasks during load. A page can have TBT < 200ms and INP > 500ms. Always check field INP separately. See `guides/02-lab-vs-field.md`. - **Scope custom plugins to audits that existing Lighthouse audits cannot cover.** Plugins cannot access custom Gatherers; they can only read existing artifacts (`ImageElements`, `ScriptElements`, `devtoolsLogs`, etc.). If you need custom page data, you need a full custom config. See `guides/05-custom-plugins.md`. --- ## Lighthouse 12 / LHCI 0.15.x facts (encoded from research) > Source: `research/external/2026-05-20-lighthouse-performance-scoring.md` **Current version:** Lighthouse 12.6.1 (LHCI 0.15.x). Node 18+ required. **Four categories (not five: PWA removed in LH12, May 2024):** - Performance - Accessibility - Best Practices - SEO **Performance score weights (unchanged from LH10):** | Metric | Weight | |--------|--------| | Total Blocking Time (TBT) | 30% | | Largest Contentful Paint (LCP) | 25% | | Cumulative Layout Shift (CLS) | 25% | | First Contentful Paint (FCP) | 10% | | Speed Index (SI) | 10% | **INP is NOT in the Lighthouse Performance score.** INP replaced FID as a Core Web Vital (March 12, 2024), but INP is a field-only metric. TBT is its lab proxy. TTI was removed from the score in Lighthouse 10. **Score color bands:** 0-49 red (Poor), 50-89 orange (Needs Improvement), 90-100 green (Good). Reaching 90+ means being in the top 8% of HTTP Archive sites for that metric. --- ## Guide map Each guide is a self-contained instruction set. Read in order on first use; jump directly to the relevant guide for targeted tasks. | Guide | When to read | |-------|-------------| | `guides/00-runner-selection.md` | First: before choosing any tool | | `guides/01-lhci-configuration.md` | Setting up `lighthouserc.json`/yaml, `collect`/`assert`/`upload` | | `guides/02-lab-vs-field.md` | Reconciling Lighthouse scores vs CrUX / PSI field data | | `guides/03-ci-integration.md` | GitHub Actions workflow, LHCI setup, score gating | | `guides/04-performance-tracking.md` | Treo, SpeedCurve, self-hosted LHCI server | | `guides/05-custom-plugins.md` | Authoring custom Lighthouse audit plugins | | `guides/06-audit-category-glossary.md` | Understanding individual audits and their score weights | --- ## Templates - `templates/lighthouserc-starter.yaml`: Annotated production-ready LHCI config - `templates/custom-plugin-starter.js`: Scaffold for a custom Lighthouse plugin ## Examples - `examples/happy-path-lhci-setup.md`: End-to-end LHCI setup from zero to CI-gating a Next.js app - `examples/lab-field-reconciliation.md`: Walking through a case where Lighthouse scores 90 but CrUX INP fails ## Reports - `reports/README.md`: Report template and location convention for audit reports --- *Command Brief: `ai-tools/command-briefs/lighthouse-pagespeed-wasp-drone-command-brief.md`* *Research: `research/research-summary.md` (normal depth, 9 sources, May 2026)* *Forged by `stinger-forge` as part of The Wasp Nest by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama)*