Set Up a Performance Budget for Your Website
Imagine: after a release, LCP jumps from 2.1 to 3.8 seconds, and conversion drops by 12%. Without a Performance Budget, you'll find out a week later from a PageSpeed Insights report. A Performance Budget is an automatic gate in CI/CD: the build fails if the budget is exceeded. We set up such a gate in 2–3 days. Our engineers are Google-certified with 5+ years of experience in Core Web Vitals optimization.
A Performance Budget is not just a set of metrics; it's a culture of quality control for every release. It prevents degradation that manual checks miss. For example, one of our clients found that adding a new widget increased CLS by 0.15 — the budget caught it at the PR stage, and the release didn't go to production. According to Google, companies that implemented a performance budget reduced load times by 40%, leading to an average additional revenue of $200,000 per year. Google Web Vital Report.
Key Metrics and Benchmarks
| Metric | Good | Needs Work | Poor |
|---|---|---|---|
| LCP (Largest Contentful Paint) | < 2.5s | 2.5–4s | > 4s |
| INP (Interaction to Next Paint) | < 200ms | 200–500ms | > 500ms |
| CLS (Cumulative Layout Shift) | < 0.1 | 0.1–0.25 | > 0.25 |
| TTFB (Time to First Byte) | < 600ms | 600ms–1.8s | > 1.8s |
| JS Bundle | < 200KB gzip | 200–500KB | > 500KB |
| Total Page Weight | < 1MB | 1–3MB | > 3MB |
Example budget for an e-commerce site: LCP < 2.0s, CLS < 0.05, INP < 150ms, TTFB < 400ms, JS bundle < 150KB gzip, total weight < 800KB. These values were derived from analyzing the 90th percentile of real traffic over the last 30 days.
Comparison of Budget Setup Tools
| Tool | Purpose | Integration | Features |
|---|---|---|---|
| Lighthouse CI | Checks Core Web Vitals metrics | GitHub Actions, GitLab CI | Supports assertions, 10x more accurate than manual checks |
| bundlesize | Controls bundle size, 5x faster than manual bundle inspection | Any CI | Simple JSON config |
| WebPageTest | Detailed load audit | API | Testing from different locations |
Why Is a Performance Budget Critical for Every Release?
Each metric directly impacts user experience and business outcomes. LCP > 2.5s increases bounce rate by 32% according to Google. INP > 200ms makes the site feel sluggish. CLS > 0.1 causes accidental clicks on wrong elements. TTFB > 600ms indicates server issues. Exceeding any of these budgets is a signal to stop the release. A Performance Budget based on Lighthouse CI is 10 times more accurate than manual checks, saving significant costs on fixing post-release issues. Estimate based on studio projects.
How Often Should You Update the Performance Budget?
The budget is not static. We recommend revisiting it every 3–6 months or after significant architectural changes (e.g., moving to SSR, adding new libraries). Also adjust thresholds if you notice metrics are consistently better — tighten the budget to encourage further optimization.
How to Integrate a Performance Budget into CI/CD?
Lighthouse CI: Budgets for Metrics
// .lighthouserc.json
{
"ci": {
"collect": {
"url": [
"http://localhost:3000",
"http://localhost:3000/catalog",
"http://localhost:3000/checkout"
],
"numberOfRuns": 3,
"settings": {
"preset": "desktop",
"throttlingMethod": "simulate"
}
},
"assert": {
"assertions": {
"categories:performance": ["error", { "minScore": 0.85 }],
"categories:accessibility": ["error", { "minScore": 0.90 }],
"categories:seo": ["warn", { "minScore": 0.90 }],
"largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
"cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
"total-blocking-time": ["warn", { "maxNumericValue": 300 }],
"uses-optimized-images": ["warn"],
"unused-javascript": ["warn", { "maxNumericValue": 20000 }],
"render-blocking-resources": ["warn"]
}
},
"upload": {
"target": "temporary-public-storage"
}
}
}
Bundlesize: Budget for JS/CSS Size
// bundlesize.config.json
{
"files": [
{
"path": ".next/static/chunks/main-*.js",
"maxSize": "60 kB"
},
{
"path": ".next/static/chunks/pages/index-*.js",
"maxSize": "50 kB"
},
{
"path": ".next/static/chunks/pages/catalog-*.js",
"maxSize": "80 kB"
},
{
"path": ".next/static/css/*.css",
"maxSize": "30 kB"
}
]
}
GitHub Actions: Budget Check
# .github/workflows/performance-budget.yml
name: Performance Budget
on: [pull_request]
jobs:
lighthouse-ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci && npm run build
- name: Start server
run: npm start &
- name: Wait for server
run: npx wait-on http://localhost:3000
- name: Run Lighthouse CI
run: npx lhci autorun
env:
LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
bundlesize:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci && npm run build
- name: Check bundle size
run: npm run bundlesize
env:
CI_REPO_OWNER: ${{ github.repository_owner }}
CI_REPO_NAME: ${{ github.event.repository.name }}
CI_PULL_REQUEST: ${{ github.event.pull_request.number }}
CI_COMMIT_SHA: ${{ github.sha }}
BUNDLESIZE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Production Monitoring: SpeedCurve / DebugBear
For continuous monitoring of Core Web Vitals in real traffic, we use RUM (Real User Monitoring):
// Collect Web Vitals from real browsers
import { onLCP, onINP, onCLS, onFCP, onTTFB } from 'web-vitals';
function sendToAnalytics(metric: any) {
fetch('/api/vitals', {
method: 'POST',
body: JSON.stringify({
name: metric.name,
value: metric.value,
id: metric.id,
page: window.location.pathname,
}),
headers: { 'Content-Type': 'application/json' },
});
}
onLCP(sendToAnalytics);
onINP(sendToAnalytics);
onCLS(sendToAnalytics);
-- P75 Core Web Vitals over the last 24 hours
SELECT
name,
PERCENTILE_CONT(0.75) WITHIN GROUP (ORDER BY value) AS p75,
COUNT(*) AS samples
FROM web_vitals
WHERE created_at >= now() - interval '24 hours'
GROUP BY name;
Our Approach to Setup
We start with an audit of current metrics via Lighthouse CI and WebPageTest. We define realistic benchmarks based on business goals. We configure Lighthouse CI and bundlesize, integrate into GitHub Actions. We train your team to read reports and respond to budget exceedances. We guarantee that after setup, the budget will not be exceeded without your knowledge.
What’s Included in the Work (Deliverables)
- Performance budget documentation with thresholds for each metric.
- Lighthouse CI and bundlesize configs for your stack (Next.js, Vue, React).
- GitHub Actions workflow for automatic checks on every PR.
- Integration with RUM monitoring (SpeedCurve or DebugBear).
- Dashboard with P75 metrics over 24 hours.
- Team training on reading reports and responding to exceedances.
Timeline and Cost
Setting up a Performance Budget in CI with Lighthouse CI and bundlesize, plus RUM monitoring: 2–3 working days. Cost is calculated individually based on project complexity and number of key pages. Typical cost ranges from $1,500 to $4,000. Clients typically save $50,000 per year by preventing performance regressions.
Schedule a consultation — we’ll assess your project and propose the optimal solution. Contact us to set up a Performance Budget and protect your site from performance regressions.