How to Set Up a Performance Budget

A performance budget is a set of hard limits on metrics that affect user experience. Without budgets, websites get slower by 5-10% per quarter as features and scripts accumulate.

Why You Need Performance Budgets

The Performance Decay Problem

Every team decision adds weight:

• New feature → more JavaScript
• Marketing request → new tracking script
• Design update → larger images
• Dependency update → bigger bundle

Without budgets, nobody notices until the site is critically slow.

Budgets Create Accountability

When a budget says "max 200KB JavaScript" and a PR adds 50KB, the team must decide:

• Is this feature worth 50KB?
• Can we optimize it to 20KB?
• What can we remove to stay within budget?

Types of Performance Budgets

1. Quantity-Based Budgets

Set limits on measurable quantities:

Metric	Budget	Why
Total JavaScript	≤200KB (compressed)	Reduces TBT and INP
Total CSS	≤80KB (compressed)	Reduces render blocking
Total page weight	≤1.5MB	Mobile data and speed
Total images	≤800KB	Usually the heaviest assets
HTTP requests	≤40	Reduces network overhead
Custom fonts	≤3 files	Font loading impacts LCP
Third-party scripts	≤5	Each adds latency

2. Timing-Based Budgets

Set limits on speed metrics:

Metric	Budget	Rationale
LCP	≤2.5s	Google's "Good" threshold
INP	≤200ms	Google's "Good" threshold
CLS	≤0.1	Google's "Good" threshold
TTFB	≤500ms	Server responsiveness
TBT	≤300ms	Main thread availability

3. Score-Based Budgets

Set minimum Lighthouse scores:

Category	Budget
Performance (mobile)	≥70
Performance (desktop)	≥85
Accessibility	≥90
Best Practices	≥90

Setting Your Budgets

Step 1: Measure Current State

Run Lighthouse on your top pages and record all metrics.

Step 2: Research Competitors

Check competitor performance. Your budget should target better than the competition.

Step 3: Set Realistic Targets

• If current JS is 500KB, don't set budget to 100KB immediately
• Start with 400KB, then tighten to 300KB, then 200KB over 3-6 months
• Some budgets are absolute (CWV thresholds from Google)

Step 4: Get Team Agreement

Performance budgets only work if the team agrees to them. Present the data and get buy-in.

Implementing Budgets

Lighthouse CI (Automated)

// lighthouserc.json
{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.7 }],
        "total-byte-weight": ["error", { "maxNumericValue": 1500000 }],
        "unminified-javascript": "error",
        "uses-responsive-images": "warn",
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
      }
    }
  }
}

Webpack/Vite Bundle Budget

// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        // Warn if any chunk exceeds 100KB
        chunkSizeWarningLimit: 100,
      },
    },
  },
};

GitHub Actions Integration

name: Performance Budget Check
on: [pull_request]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm run build
      - name: Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_TOKEN }}

bundlesize (Simple Bundle Check)

// package.json
{
  "bundlesize": [
    { "path": "dist/js/*.js", "maxSize": "200 kB" },
    { "path": "dist/css/*.css", "maxSize": "80 kB" }
  ]
}

Enforcing Budgets

Soft Enforcement (Warnings)

• Display warnings in PR comments
• Send Slack notifications
• Show in CI output but don't block

Hard Enforcement (Block Deploys)

• Fail CI pipeline if budgets are exceeded
• Require performance review for exceptions
• Auto-notify performance champion

Exception Process

Sometimes budgets need to be exceeded:

1. Developer requests exception with justification
2. Performance champion reviews
3. If approved, set temporary budget increase with expiration date
4. Plan to bring back within budget in next sprint

Monitor Your Budgets

BadPageSpeed tracks your scores over time, making it easy to spot budget violations and trends.

Track your performance →