lighthouse-budget-author

Overview

lighthouse-perf is the runner - it takes a .lighthouserc.js and runs Lighthouse against it. This skill writes the config, picking thresholds per route at design time so the runner has something meaningful to assert against.

The two artifacts this skill produces:

1. Lighthouse CI assertion config in .lighthouserc.js - per-route LCP / INP / CLS thresholds.
2. Resource-size budget in budget.json (the Lighthouse "performance budgets" feature) - per-resource-type byte caps.

Without this skill, teams either (a) set every threshold to the "good" default and ignore route-specific reality, or (b) pick thresholds via guesswork. Either ends with a gate the team disables.

When to use

• The project just installed @lhci/cli and needs an initial config.
• An NFR review (per nfr-extractor) produced perf NFRs that need to translate into Lighthouse syntax.
• Existing budgets are uniform across routes (same threshold for every URL); the team wants per-route tightening.
• The team wants resource-size budgets (JS bundle ≤ 300kb, etc.) in addition to Web Vitals.

Step 1 - Inventory the routes

For each route to be audited:

The URL set should cover the team's high-traffic routes plus any known-slow long-tail page. Don't audit every URL - pick representatives.

Step 2 - Pick LCP / INP / CLS thresholds per route

Start from the canonical Web Vitals "good" thresholds (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1) and adjust per traffic class:

For a team's first pass, start lenient (Web Vitals defaults across the board) and tighten one route at a time as evidence accumulates that the route is consistently faster than the default.

Step 3 - Pick resource-size budgets

A resource-size budget caps the total bytes per resource type. The canonical Lighthouse "good" defaults for a non-media-heavy public page:

For Single-Page Apps where the JS bundle is the load-bearing cost, the JS budget is the most important. Subpaths (route chunks) keep this tractable as the app grows.

Step 4 - Emit lighthouserc.js

A representative config that lives at the project root:

// .lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: [
        'http://localhost:3000/',                      // marketing home (cached)
        'http://localhost:3000/pricing',               // marketing pricing (cached)
        'http://localhost:3000/dashboard',             // logged-in dynamic
        'http://localhost:3000/orders/new',            // form-heavy
      ],
      numberOfRuns: 3,
      settings: {
        preset: 'desktop',
        chromeFlags: '--no-sandbox',
        budgetPath: './budget.json',                  // resource-size budget
      },
      startServerCommand: 'npm run start',
      startServerReadyPattern: 'ready on',
    },
    assert: {
      assertMatrix: [
        // Cached marketing pages — strict
        {
          matchingUrlPattern: '^http://[^/]+/(pricing)?$',
          assertions: {
            'largest-contentful-paint': ['error', { maxNumericValue: 1500 }],
            'interaction-to-next-paint': ['error', { maxNumericValue: 100 }],
            'cumulative-layout-shift':   ['error', { maxNumericValue: 0.1 }],
          },
        },
        // Dynamic logged-in pages — defaults
        {
          matchingUrlPattern: '/dashboard',
          assertions: {
            'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
            'interaction-to-next-paint': ['error', { maxNumericValue: 200 }],
            'cumulative-layout-shift':   ['error', { maxNumericValue: 0.1 }],
          },
        },
        // Form-heavy pages — strict CLS
        {
          matchingUrlPattern: '/orders/new',
          assertions: {
            'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
            'interaction-to-next-paint': ['error', { maxNumericValue: 100 }],
            'cumulative-layout-shift':   ['error', { maxNumericValue: 0.05 }],
          },
        },
      ],
    },
    upload: { target: 'temporary-public-storage' },
  },
};

assertMatrix lets per-route assertions live in one config - easier to review than separate config files.

Step 5 - Emit budget.json

Lighthouse's resource-size budget format:

[
  {
    "path": "/*",
    "resourceSizes": [
      { "resourceType": "script",     "budget": 300 },
      { "resourceType": "stylesheet", "budget": 100 },
      { "resourceType": "image",      "budget": 500 },
      { "resourceType": "font",       "budget": 100 },
      { "resourceType": "total",      "budget": 1500 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 10 }
    ]
  },
  {
    "path": "/marketing/*",
    "resourceSizes": [
      { "resourceType": "script",     "budget": 150 },
      { "resourceType": "stylesheet", "budget": 50 },
      { "resourceType": "total",      "budget": 800 }
    ]
  }
]

Per-path budgets allow stricter targets for marketing pages (where load time directly impacts conversion) than for logged-in app routes.

Step 6 - Validate the budget realistically

Before committing, run Lighthouse against current production with the new config:

LHCI_BUILD_CONTEXT__GITHUB_BASE_URL=... npx lhci collect --url=https://prod.example.com/
npx lhci assert

Expect some failures - that's the point. The budget surfaces what needs work. Categorize the failures:

Never set a budget that always passes today - it'll never catch a regression.

Anti-patterns

References

• lighthouse-perf - the runner that consumes this skill's output.
• nfr-extractor - upstream skill that produces threshold-bound NFRs translated by this skill into Lighthouse syntax.
• perf-budget-gate - downstream unified gate that consumes Lighthouse + load-runner verdicts.
• web.dev/articles/vitals - canonical LCP / INP / CLS thresholds at the 75th percentile.
• Lighthouse performance budgets - https://web.dev/articles/use-lighthouse-for-performance-budgets