Performance Budget Enforcer

A CI plugin that scans React/Next.js builds, detects bundle size regressions, and fails CI if performance budgets are exceeded.

Features

• 🔍 Analyzes bundle sizes from Webpack, Vite, and Next.js builds
• 📊 Identifies which dependencies caused bloat
• 🚫 Fails CI when budgets are exceeded
• 📈 Compares against baseline for regression detection
• 💬 Posts PR comments with detailed reports
• 📢 Sends Slack notifications on budget failures

Installation

npm install performance-budget-enforcer --save-dev

Usage

Initialize config

npx perf-budget init

This creates a perf-budget.json config file.

Analyze bundles

npx perf-budget analyze --dir .next

Check budget

npx perf-budget check --dir .next

Regression detection with baseline

# First run: save baseline
npx perf-budget analyze --dir .next -o baseline.json

# Later runs: compare against baseline
npx perf-budget check --dir .next --baseline baseline.json

Configuration

Edit perf-budget.json:

{
  "maxTotalSize": 500000,
  "maxGzippedSize": 150000,
  "maxChunkSize": 250000,
  "maxDependencySize": 100000,
  "thresholds": {
    "warning": 10,
    "error": 20
  }
}

• All sizes are in bytes
• maxTotalSize: Maximum total bundle size
• maxGzippedSize: Maximum gzipped size
• maxChunkSize: Maximum size for any single chunk
• maxDependencySize: Maximum size for any dependency
• thresholds.error: % growth vs baseline that triggers CI failure (default: 20%)

GitHub Integration

The tool automatically posts PR comments when budgets fail.

Set these environment variables in your CI:

- name: Performance Budget Check
  run: npx perf-budget check --dir .next
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
    GITHUB_REPOSITORY: ${{ github.repository }}

Slack Integration

Get a webhook URL: https://api.slack.com/messaging/webhooks

Add environment variable:

- name: Performance Budget Check
  run: npx perf-budget check --dir .next
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
    SLACK_CHANNEL: #performance  # optional

Optional env vars:

• SLACK_WEBHOOK_URL - Required webhook URL
• SLACK_CHANNEL - Override default channel
• SLACK_USERNAME - Custom username
• SLACK_ICON_EMOJI - Custom emoji (default: :package:)

GitHub Actions Integration

name: Performance Budget

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  perf-budget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Download baseline
        if: github.event_name == 'pull_request'
        uses: actions/download-artifact@v4
        with:
          name: bundle-baseline
          path: .
        continue-on-error: true

      - name: Performance Budget Check
        run: npx perf-budget check --dir .next
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

      - name: Upload baseline
        if: github.ref == 'refs/heads/main'
        uses: actions/upload-artifact@v4
        with:
          name: bundle-baseline
          path: baseline.json

Commands

• perf-budget analyze [options] - Analyze bundle sizes
• perf-budget check [options] - Check against budget
• perf-budget init - Create config file

Options

• -d, --dir <path> - Build directory (default: ./build)
• -c, --config <path> - Config file (default: ./perf-budget.json)
• -b, --baseline <path> - Baseline file for regression detection
• -o, --output <path> - Output JSON file
• --fail - Exit with code 1 if budget exceeded (default: true)