Performance Budgets with Lighthouse
Define and enforce performance budgets so size and metric limits are checked automatically, preventing regressions before they reach production.
Performance Budgets with Lighthouse is a free Web Performance Optimization & Lighthouse lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Web Performance Optimization & Lighthouse learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What Is a Performance Budget?
A performance budget is a set of agreed limits, such as max JavaScript size or a minimum LCP, that the team commits not to exceed. It turns vague goals into enforceable thresholds.
Why Budgets Matter
Without budgets, performance erodes silently as features pile on. A budget makes regressions visible and blocking, shifting performance left into development.
Two Kinds of Budgets
- Resource budgets: byte size and request counts per type (script, image, total).
- Timing budgets: metric thresholds like LCP, TBT, CLS.
The budget.json File
Lighthouse reads a budget.json describing resource and timing limits. It then flags any audited page that exceeds them.
[{
"resourceSizes": [
{ "resourceType": "script", "budget": 170 },
{ "resourceType": "total", "budget": 500 }
]
}]Adding Timing Budgets
Timings are listed alongside sizes. Values are in milliseconds for time metrics.
[{
"timings": [
{ "metric": "largest-contentful-paint", "budget": 2500 },
{ "metric": "interactive", "budget": 3800 }
]
}]Running with a Budget
Pass the budget file to the Lighthouse CLI. Exceeded items appear in the report's Budgets section.
lighthouse https://example.com --budget-path=./budget.json --output=json --output-path=./report.jsonEnforcing in CI with LHCI
Lighthouse CI (lhci) can assert budgets and fail the build when limits are breached, so regressions never merge.
// lighthouserc.json
{
"ci": {
"assert": {
"assertions": {
"resource-summary:script:size": ["error", { "maxNumericValue": 174080 }]
}
}
}
}Warn vs Error Levels
Assertions support warn and error levels. Start new budgets as warnings to gather data, then promote to errors once the team is confident.
Setting Realistic Limits
Base budgets on current measurements plus a small margin, or on competitor benchmarks. Budgets that are impossible to meet get ignored; budgets that are too loose never fire.
Tracking Over Time
The LHCI server stores historical results so you can chart metric and size trends and tighten budgets gradually as performance improves.
Workflow Summary
- Define resource and timing budgets.
- Run them locally via CLI.
- Assert them in CI with LHCI.
- Start as warnings, then enforce as errors.
Quick Check
You want a pull request to fail automatically when the script bundle grows beyond a set size. What achieves this?
Recap
You learned to set resource and timing budgets in budget.json, run them with the Lighthouse CLI, and enforce them in CI via Lighthouse CI assertions. Start with warnings, promote to errors, and track trends to keep performance from regressing.
Frequently asked questions
Is the “Performance Budgets with Lighthouse” lesson free?
Yes — the full text of “Performance Budgets with Lighthouse” is free to read here on the web, and the Web Performance Optimization & Lighthouse course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Web Performance Optimization & Lighthouse course, upgrade to CoddyKit PRO.
What will I learn in “Performance Budgets with Lighthouse”?
Define and enforce performance budgets so size and metric limits are checked automatically, preventing regressions before they reach production. You practise Web Performance Optimization & Lighthouse with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Web Performance Optimization & Lighthouse?
No prior experience is required. Web Performance Optimization & Lighthouse on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Performance Budgets with Lighthouse” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Web Performance Optimization & Lighthouse lesson?
Yes. Every Web Performance Optimization & Lighthouse lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- CLI and Programmatic Lighthouse
- Custom Audits and Assertions
- Integrating Lighthouse into CI/CD
- Performance Budgets with Lighthouse