Enforcing Performance Budgets in CI/CD

Performance Budgets in CI/CD

A performance budget is only useful if it is enforced. Without automation, budgets are ignored under deadline pressure. Integrating budget checks into your CI/CD pipeline makes performance regressions as visible as failing tests.

CI/CD Integration Options

Tool	What It Checks	Integration
size-limit	JS bundle sizes	npm script, GitHub Actions
bundlesize	Any file size	npm script, GitHub Status API
Lighthouse CI	Full page metrics	GitHub Actions, Jenkins
webpack-bundle-analyzer	Bundle composition	Visual, manual review
Custom scripts	Any metric	Flexible

Setting Up size-limit

// package.json
{
  "size-limit": [
    { "path": "dist/js/*.js", "limit": "200 KB" },
    { "path": "dist/css/*.css", "limit": "50 KB" }
  ],
  "scripts": {
    "size": "size-limit",
    "size:check": "size-limit --check"
  }
}

In your CI pipeline (GitHub Actions):

- name: Check bundle size
  run: npm run size:check

If any file exceeds its limit, the build fails with a clear error message showing which file is over budget.

Setting Up Lighthouse CI

# .github/workflows/lighthouse.yml
- name: Lighthouse CI
  uses: treosh/lighthouse-ci-action@v11
  with:
    configPath: './lighthouserc.json'
    uploadArtifacts: true

# lighthouserc.json
{
  "ci": {
    "assert": {
      "assertions": {
        "total-byte-weight": ["error", { "maxNumericValue": 600000 }],
        "resource-summary:script:size": ["warn", { "maxNumericValue": 200000 }],
        "first-contentful-paint": ["error", { "maxNumericValue": 2000 }]
      }
    }
  }
}

PR Comments with Size Diffs

Tools like size-limit can post size diff comments directly on pull requests:

Bundle size changes:
  main.js: 185 KB → 192 KB (+7 KB, +3.8%) ⚠️
  vendor.js: 95 KB → 94 KB (-1 KB, -1.1%) ✅
  styles.css: 32 KB → 32 KB (no change) ✅

This gives reviewers immediate visibility into the performance impact of every code change.

Budget Thresholds

Set two levels:

• Warning — Size increased but still under budget (notify, do not block)
• Error — Size exceeds budget (block merge until resolved)

Making It Stick

• Start with warnings only; upgrade to errors after the team adjusts
• Include bundle size checks in the definition of "done" for every feature
• Celebrate wins — track and share when the team reduces bundle size
• Assign a performance champion who reviews size-limit reports weekly