Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

lighthouse-perf

/lighthouse-perf

Sprawdza Core Web Vitals na każdym PR i szkicuje budżety wydajności dla tras: LCP, INP, CLS, rozmiary zasobów i komentarze w PR.

Repozytorium
qa-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
10
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Sprawdza Core Web Vitals na każdym PR i szkicuje budżety wydajności dla tras: LCP, INP, CLS, rozmiary zasobów i komentarze w PR.

Oryginalny opis (EN)

Use when a web frontend needs Core Web Vitals (LCP, INP, CLS) checked on every PR, or its first performance budgets drafted. Sets up Lighthouse CI with Google's thresholds at the 75th percentile, per-route budgets by page type, resource-size budgets, report artifacts and PR comments.

Jak działa

  1. Overview
  2. When to use
  3. Install
  4. Configure
  5. Running
  6. CI integration
  7. Authoring budgets
  8. Mobile vs desktop budgets
  9. Anti-patterns
  10. Lab vs field
Sekcje z nagłówków SKILL.md, w oryginale · 264 linii, 1 296 słów
Podgląd SKILL.md
---
name: lighthouse-perf
description: "Use when a web frontend needs Core Web Vitals (LCP, INP, CLS) checked on every PR, or its first performance budgets drafted. Sets up Lighthouse CI with Google's thresholds at the 75th percentile, per-route budgets by page type, resource-size budgets, report artifacts and PR comments."
---

# lighthouse-perf

## Overview

The **Core Web Vitals** are Google's three canonical user-experience
metrics ([web-vitals][webvitals]):

[webvitals]: https://web.dev/articles/vitals
[inp]: https://web.dev/articles/inp
[lh-inp]: https://github.com/GoogleChrome/lighthouse/blob/main/core/audits/metrics/interaction-to-next-paint.js
[lh-tbt]: https://developer.chrome.com/docs/lighthouse/performance/lighthouse-total-blocking-time

| Metric | Measures              | "Good" threshold        |
|--------|-----------------------|--------------------------|
| **LCP** (Largest Contentful Paint) | Loading performance    | ≤ **2.5 seconds**           |
| **INP** (Interaction to Next Paint) | Interactivity         | ≤ **200 milliseconds**      |
| **CLS** (Cumulative Layout Shift) | Visual stability       | ≤ **0.1**                   |

INP became a stable Core Web Vital in 2024, replacing FID
([web-vitals][webvitals]). The canonical measurement standard is
**the 75th percentile** of page loads, segmented across mobile and
desktop ([web-vitals][webvitals]).

INP needs a real user interaction, so a Lighthouse navigation run (what
`lhci autorun` does) cannot report it: the `interaction-to-next-paint`
audit only runs in timespan mode ([lh-inp][lh-inp]). In the lab, gate on
Total Blocking Time (TBT), which web.dev calls "a reasonable proxy metric
for INP, but it's not a substitute for INP" ([inp][inp]), and track INP
itself from field data (see "Lab vs field" below).

[lhci]: https://github.com/GoogleChrome/lighthouse-ci

This skill covers **Lighthouse CI** (`@lhci/cli`) - the official
Google Chrome team tool for running Lighthouse on every PR and
asserting against budgets ([lhci][lhci]).

## When to use

- The project ships a web frontend (Next.js, Vite, Remix, plain
  static, etc.).
- The team has documented Web Vitals NFRs (per `non-functional-requirement-extractor`)
  and needs CI enforcement.
- A PR's perf delta vs. main needs to be visible (regression-block
  or just-warn).
- The team uses Lighthouse for accessibility / SEO / best-practices
  audits beyond perf.

If the project is a backend API or a CLI tool, this skill doesn't
apply - use `k6-load-testing` or a
sibling load runner for backend perf.

## Install

```bash
npm install --save-dev @lhci/cli
```

(Per [lhci][lhci]; the docs reference `@lhci/cli@0.15.x` as the
current major.) Pin to a specific minor in CI for determinism.

## Configure

Create `.lighthouserc.js` (or `.lighthouserc.json`) at the project
root. The canonical shape per [lhci][lhci]:

```js
module.exports = {
  ci: {
    collect: {
      // What to audit
      url: [
        'http://localhost:3000/',
        'http://localhost:3000/dashboard',
        'http://localhost:3000/pricing',
      ],
      // How many runs per URL - median report wins; 3 is canonical for stability
      numberOfRuns: 3,
      // Lighthouse settings
      settings: {
        preset: 'desktop',                       // or 'mobile' (default)
        chromeFlags: '--no-sandbox',              // CI-runner-friendly
      },
      // Use a static-server when running headless in CI
      startServerCommand: 'npm run start',
      startServerReadyPattern: 'ready on',
    },
    assert: {
      // Canonical Web Vitals budgets per web.dev/articles/vitals
      assertions: {
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],   // 2.5s
        // INP is timespan-only in Lighthouse; TBT is its lab proxy.
        // 200 ms = Lighthouse's mobile "fast" band; use 150 with preset: 'desktop'.
        'total-blocking-time':       ['error', { maxNumericValue: 200 }],
        'cumulative-layout-shift':   ['error', { maxNumericValue: 0.1 }],    // 0.1
        // Lighthouse category scores (0-1)
        'categories:performance':    ['warn',  { minScore: 0.9 }],
        'categories:accessibility':  ['error', { minScore: 0.95 }],
        'categories:best-practices': ['warn',  { minScore: 0.9 }],
      },
    },
    upload: {
      // Where to upload the .json reports for trend analysis
      target: 'temporary-public-storage',   // or 'lhci' for self-hosted server
    },
  },
};
```

Assertion levels per [lhci][lhci]:

- `'error'` - fails the CI run (exits non-zero).
- `'warn'` - surfaces in the report but doesn't fail.
- `'off'` - disabled (useful for opt-out per-page).

## Running

The canonical invocation per [lhci][lhci]:

```bash
lhci autorun
```

`autorun` runs three phases in sequence:

1. **collect** - start the server (if `startServerCommand` set), run
   Lighthouse N times per URL.
2. **assert** - compare results against the assertion config; exit
   non-zero on `error`-level failures.
3. **upload** - upload reports to the configured target for trend
   tracking.

For finer control, the phases can run independently: `lhci collect`,
`lhci assert`, `lhci upload`.

### Running specific URLs

For a single PR-relevant audit:

```bash
lhci collect --url=http://localhost:3000/dashboard --numberOfRuns=3
lhci assert
```

## CI integration

```yaml
# .github/workflows/lighthouse.yml
name: lighthouse

on:
  pull_request:
    paths:
      - 'src/**'
      - 'package.json'
      - 'package-lock.json'

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Build
        run: npm run build

      - name: Lighthouse CI
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}   # optional, for PR comments
        run: npx lhci autorun

      - name: Upload Lighthouse reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: lighthouse-reports
          path: .lighthouseci/
          retention-days: 14
```

The optional `LHCI_GITHUB_APP_TOKEN` (set up via the Lighthouse CI
GitHub App) enables PR comments showing the per-metric delta vs. the
main branch's last green run.

## Authoring budgets

Budget authoring is part of Lighthouse CI configuration: picking per-route
LCP / INP / CLS thresholds by traffic class, resource-size caps in
`budget.json`, the `assertMatrix` config shape, and how to validate a new
budget against production before committing it, are all in
[references/budgets.md](references/budgets.md). Start there when the project
has no budgets yet or the existing ones need a redesign.

## Mobile vs desktop budgets

LCP / INP thresholds are the same across mobile and desktop, but
**mobile is consistently slower** in practice - the same JS bundle
runs on a less-powerful CPU over a less-stable network.

Common pattern: separate `.lighthouserc.mobile.js` and
`.lighthouserc.desktop.js`, run both in CI. The mobile run uses
`preset: 'mobile'` (default) which applies CPU + network throttling
to simulate a mid-range Android device.

```bash
# Run both
LHCI_BUILD_CONTEXT__GITHUB_BASE_URL=https://github.com/... \
  npx lhci autorun --config=.lighthouserc.mobile.js
npx lhci autorun --config=.lighthouserc.desktop.js
```

## Anti-patterns

| Anti-pattern                                                  | Why it fails                                                       | Fix |
|---------------------------------------------------------------|---------------------------------------------------------------------|-----|
| `numberOfRuns: 1`                                              | Single-run measurements are noisy; flaky alerts.                  | Use 3 (canonical) or 5 for high-stakes pages; LHCI uses the median. |
| Asserting on `first-input-delay` (FID)                          | FID was retired in 2024 ([web-vitals][webvitals]).                 | Gate on `total-blocking-time` in the lab and track INP in field data. |
| Asserting on `interaction-to-next-paint` in `lhci autorun`      | The INP audit runs only in timespan mode ([lh-inp][lh-inp]), so a navigation run has no INP to check. | Gate on `total-blocking-time` (lab proxy, [inp][inp]); track INP with the `web-vitals` library in production. |
| Hard error on every metric out of the box                       | Existing pages may not meet thresholds; team learns to ignore the gate. | Start with `warn` for everything; promote to `error` once green for 2 weeks. |
| Auditing only the homepage                                     | The homepage is usually the most-optimized page; misses regressions on long-tail routes. | Audit a representative URL set: home + 1 logged-in dashboard + 1 long-form content + 1 form-heavy. |
| Lighthouse score as the sole metric                             | Lighthouse score conflates multiple subscores; doesn't isolate which Web Vital regressed. | Assert on the individual metrics (`largest-contentful-paint`, `total-blocking-time` as the INP proxy, `cumulative-layout-shift`); category score is supplementary. |
| Running against production                                       | Lighthouse fires real network requests and triggers analytics; pollutes prod metrics. | Always against staging or a local build. |

## Lab vs field

Lighthouse CI measures **lab data** (synthetic; deterministic
runner). Field data (real-user metrics, RUM) is measured by Web Vitals
JS in production. Both matter:

| Source         | Tool                                | Use for                                |
|----------------|-------------------------------------|----------------------------------------|
| Lab (synthetic)| Lighthouse CI                        | Per-PR regression gate.                 |
| Field (RUM)    | `web-vitals` library + analytics     | Real-user 75th-percentile tracking.    |

Lighthouse CI catches per-PR regressions; field data tracks the
75th-percentile threshold per [web-vitals][webvitals]. Don't substitute
one for the other.

## References

- [web-vitals][webvitals] - canonical Core Web Vitals definitions and
  thresholds (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1; 75th-percentile
  measurement; INP-replaces-FID in 2024).
- [lh-inp][lh-inp] - Lighthouse's `interaction-to-next-paint` audit
  source (`supportedModes: ['timespan']`).
- [inp][inp] - web.dev on INP: lab tools that only observe page load
  can't report it; TBT is a proxy, not a substitute.
- [lh-tbt][lh-tbt] - Lighthouse TBT scoring bands (mobile 0-200 ms fast,
  desktop 0-150 ms fast).
- [lhci][lhci] - Lighthouse CI canonical install, `lhci autorun`,
  configuration shape, assertion levels.
- [references/budgets.md](references/budgets.md) - drafting per-route
  budgets and `budget.json` resource-size caps at design time.
- `perf-budget-gate` - downstream
  unified gate aggregating Lighthouse + load-runner verdicts.
- `non-functional-requirement-extractor` - upstream skill that surfaces Web Vitals NFRs from PRDs.
Pliki w paczce (2)
  • SKILL.md 11 KB
  • references/budgets.md 9 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · testland/qa-skills100MIT
testland/qa100MIT

Migawka bazy z 13.11.2026 · wersja paczki 335d1c6c43b5 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100core-web-vitals
    Optymalizuje Core Web Vitals (LCP, INP, CLS) pod lepsze doświadczenie na stronie i pozycje w wyszukiwarce, w tym naprawę przesunięć układu.
  • 90web-quality
    Optymalizuje jakość webową według wytycznych Google Lighthouse i Core Web Vitals: audyt, wydajność, dostępność, SEO, dobre praktyki oraz LCP, INP i CLS.
  • 100page-audit
    Mierzy każdą stronę Lighthouse (dostępność, SEO, dobre praktyki) i śladem Core Web Vitals (LCP, CLS, INP), zapisuje wyniki w docs/lighthouse/ i naprawia znalezione problemy.
  • 100lighthouse
    Uruchamia lokalne audyty wydajności Lighthouse na serwerze deweloperskim PixelDen (localhost:3002), by sprawdzić LCP, CLS, INP i potwierdzić poprawkę przed wydaniem.
  • 100core-web-vitals-fixer
    Diagnozuje Core Web Vitals według szablonów stron przez PageSpeed Insights i Lighthouse, a potem przygotowuje uszeregowane plany poprawek LCP, INP i CLS.
  • 95web-performance
    Diagnozuje i poprawia Core Web Vitals (LCP, INP, CLS) na podstawie danych z terenu i z testów laboratoryjnych.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.