How to Enforce Lighthouse CI Performance Budgets

Lighthouse CI asserts front-end budgets (performance score, LCP, total byte weight) and fails the run when a page regresses.

Run lhci autorun with an assert config. Assertions on categories and audits decide the exit code, so a page that drops below the budget fails CI.

Steps

• Install @lhci/cli and add a lighthouserc with an assert block.
• Set assertions on categories:performance and key audits.
• Run lhci autorun; a failed assertion fails the step.

lighthouserc config

module.exports = {
  ci: {
    collect: { url: ['https://staging.example.com/'], numberOfRuns: 3 },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'total-byte-weight': ['warn', { maxNumericValue: 1600000 }],
      },
    },
  },
};

Workflow

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @lhci/cli && lhci autorun

Gotchas

• Lighthouse scores vary run to run; use numberOfRuns and median to reduce flakiness.
• Use warn for soft budgets and error only for the metrics you truly want to block on.

Related guides