Performance Budget Enforcer

Implement automated performance monitoring and budget enforcement to prevent performance regressions in worldbuilding applications.

Overview

To enforce performance budgets:

1. Define performance budgets for key metrics (bundle size, Lighthouse scores, Web Vitals)
2. Set up automated monitoring in CI/CD pipeline
3. Configure alerts for threshold violations
4. Generate performance reports and trends
5. Block deployments that exceed budgets

Performance Metrics

JavaScript Bundle Size

To monitor bundle sizes:

• Initial Bundle: First-load JS (target: <200KB)
• Route Bundles: Per-page JS (target: <50KB per route)
• Total Bundle: All JS combined (target: <500KB)
• Vendor Bundle: Third-party libraries (target: <150KB)

Lighthouse Scores

To track Lighthouse metrics:

• Performance: Overall performance score (target: >90)
• Accessibility: A11y compliance (target: >90)
• Best Practices: Web standards compliance (target: >90)
• SEO: Search engine optimization (target: >90)

Core Web Vitals

To measure user experience:

• LCP (Largest Contentful Paint): <2.5s
• FID (First Input Delay): <100ms
• CLS (Cumulative Layout Shift): <0.1
• TTFB (Time to First Byte): <600ms
• FCP (First Contentful Paint): <1.8s

Consult references/performance-targets.md for detailed target definitions and industry benchmarks.

Budget Configuration

Define Budgets

Create performance-budget.json:

{
  "bundles": {
    "maxInitialBundle": 204800,
    "maxRouteBundle": 51200,
    "maxTotalBundle": 512000,
    "maxVendorBundle": 153600
  },
  "lighthouse": {
    "performance": 90,
    "accessibility": 90,
    "bestPractices": 90,
    "seo": 90
  },
  "webVitals": {
    "lcp": 2500,
    "fid": 100,
    "cls": 0.1,
    "ttfb": 600,
    "fcp": 1800
  },
  "assets": {
    "maxImageSize": 102400,
    "maxFontSize": 51200,
    "maxCssSize": 51200
  }
}

Use scripts/generate_budget.py to create initial budget configuration based on current metrics.

Budget Levels

Define severity levels:

• Error: Block deployment (>20% over budget)
• Warning: Alert but allow (10-20% over budget)
• Info: Track but continue (<10% over budget)

CI/CD Integration

GitHub Actions Setup

To add performance checks to CI:

name: Performance Budget

on:
  pull_request:
    branches: [main, master]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Analyze bundle size
        run: npx @next/bundle-analyzer

      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun

      - name: Check performance budgets
        run: python scripts/check_budgets.py

      - name: Comment results on PR
        uses: actions/github-script@v7
        with:
          script: |
            const results = require('./performance-results.json');
            // Comment logic here

Use assets/github-workflow.yml for complete workflow template.

Lighthouse CI Configuration

Create lighthouserc.json:

{
  "ci": {
    "collect": {
      "startServerCommand": "npm run start",
      "url": ["http://localhost:3000", "http://localhost:3000/entities"],
      "numberOfRuns": 3
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 0.9 }],
        "first-contentful-paint": ["error", { "maxNumericValue": 1800 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

Reference assets/lighthouserc.json for complete configuration.

Bundle Analysis

Next.js Bundle Analyzer

To analyze bundle composition:

# Install analyzer
npm install --save-dev @next/bundle-analyzer

# Add to next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  // Next.js config
});

# Run analysis
ANALYZE=true npm run build

Size Tracking

Use scripts/track_bundle_size.py to track bundle size over time:

python scripts/track_bundle_size.py --record

Store results in performance-history/bundle-sizes.json for trend analysis.

Automated Alerts

Threshold Violations

To configure alerts:

// scripts/check_budgets.ts
interface BudgetCheck {
  metric: string;
  current: number;
  budget: number;
  status: 'pass' | 'warning' | 'error';
  percentOver: number;
}

function checkBudget(current: number, budget: number): BudgetCheck['status'] {
  const percentOver = ((current - budget) / budget) * 100;

  if (percentOver > 20) return 'error';
  if (percentOver > 10) return 'warning';
  return 'pass';
}

Notification Channels

To send alerts:

• GitHub PR Comments: Automated comments with performance report
• Slack: Webhook notifications for violations
• Email: Digest of performance trends
• Build Status: Fail builds on error-level violations

Use scripts/send_alerts.py to integrate notification channels.

Performance Monitoring

Real User Monitoring (RUM)

To track real user metrics:

// lib/web-vitals.ts
import { onCLS, onFID, onLCP, onFCP, onTTFB } from 'web-vitals';

export function reportWebVitals() {
  onCLS((metric) => sendToAnalytics(metric));
  onFID((metric) => sendToAnalytics(metric));
  onLCP((metric) => sendToAnalytics(metric));
  onFCP((metric) => sendToAnalytics(metric));
  onTTFB((metric) => sendToAnalytics(metric));
}

function sendToAnalytics(metric: Metric) {
  // Send to analytics service
  fetch('/api/analytics', {
    method: 'POST',
    body: JSON.stringify(metric),
  });
}

Enable in app/layout.tsx:

import { reportWebVitals } from '@/lib/web-vitals';

export default function RootLayout({ children }: { children: ReactNode }) {
  useEffect(() => {
    reportWebVitals();
  }, []);

  return <html>{children}</html>;
}

Synthetic Monitoring

To run scheduled Lighthouse audits:

# .github/workflows/scheduled-performance.yml
name: Scheduled Performance Audit

on:
  schedule:
    - cron: '0 0 * * *' # Daily at midnight

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Run Lighthouse
        run: lhci autorun --config=lighthouserc.json

      - name: Store results
        run: python scripts/store_performance_data.py

Performance Reports

PR Comments

To generate PR comments with results:

## Performance Report

### Bundle Size

- Initial Bundle: 185KB ([OK] under 200KB budget)
- Total Bundle: 480KB ([OK] under 500KB budget)

### Lighthouse Scores

- Performance: 92/100 ([OK] meets 90 target)
- Accessibility: 95/100 ([OK] meets 90 target)
- Best Practices: 88/100 ([WARN] below 90 target)

### Core Web Vitals

- LCP: 2.1s ([OK] under 2.5s)
- FID: 85ms ([OK] under 100ms)
- CLS: 0.05 ([OK] under 0.1)

### Bundle Comparison

| Route            | Current | Previous | Change  |
| ---------------- | ------- | -------- | ------- |
| /                | 185KB   | 180KB    | +5KB    |
| /entities        | 45KB    | 45KB     | No change |
| /entities/[id]   | 38KB    | 40KB     | -2KB [OK] |

[View detailed report](https://lighthouse-report-url)

Use scripts/generate_pr_comment.py to create formatted reports.

Trend Analysis

To visualize performance trends:

python scripts/generate_trends.py --days 30 --output performance-trends.html

Generate charts showing:

• Bundle size over time
• Lighthouse scores history
• Web Vitals percentiles
• Performance budget compliance rate

Reference assets/trend-visualization.html for dashboard template.

Optimization Strategies

Bundle Size Reduction

To reduce bundle sizes:

1. Code Splitting: Split large components into separate chunks
2. Tree Shaking: Remove unused code with proper imports
3. Dynamic Imports: Load components on demand
4. Lazy Loading: Defer non-critical resources
5. Compression: Enable gzip/brotli compression
6. Minification: Ensure production builds are minified

Image Optimization

To optimize images:

import Image from 'next/image';

<Image
  src="/entity-map.png"
  alt="World Map"
  width={800}
  height={600}
  quality={75}
  loading="lazy"
  placeholder="blur"
/>

Font Optimization

To optimize fonts:

// app/layout.tsx
import { Inter } from 'next/font/google';

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
});

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html className={inter.variable}>
      <body>{children}</body>
    </html>
  );
}

Third-Party Scripts

To optimize third-party scripts:

import Script from 'next/script';

<Script
  src="https://analytics.example.com/script.js"
  strategy="lazyOnload"
/>

Consult references/optimization-techniques.md for comprehensive optimization guide.

Best Practices

1. Set Realistic Budgets: Base on current metrics, improve gradually
2. Monitor Continuously: Track metrics on every deployment
3. Act on Violations: Investigate and fix budget overages promptly
4. Educate Team: Share performance impact of code changes
5. Review Regularly: Adjust budgets as app evolves
6. Prioritize UX: Focus on metrics that impact user experience
7. Test Real Devices: Verify performance on target devices

Troubleshooting

Common issues:

• Fluctuating Scores: Run multiple Lighthouse audits, use median scores
• CI vs Local: Ensure CI environment matches production setup
• False Positives: Adjust budgets for legitimate growth
• Missing Metrics: Verify analytics integration and data collection
• Slow CI: Cache dependencies and optimize build process
• Bundle Size Spikes: Use bundle analyzer to identify culprits