performance-budget-setter

Performance Budget Setter

Set and enforce performance budgets to maintain fast user experiences.

Performance Budget Template

# Performance Budget: E-Commerce Website

## Bundle Size Budget

| Asset Type             | Budget     | Current    | Status |
| ---------------------- | ---------- | ---------- | ------ |
| Initial JS             | 200 KB     | 185 KB     | ✅     |
| Initial CSS            | 50 KB      | 48 KB      | ✅     |
| Vendor JS              | 150 KB     | 145 KB     | ✅     |
| Fonts                  | 100 KB     | 95 KB      | ✅     |
| Images (above fold)    | 300 KB     | 320 KB     | ❌     |
| **Total Initial Load** | **800 KB** | **793 KB** | ✅     |

API Latency Budget

Endpoint	p50	p95	p99
GET /products	<100ms	<300ms	<500ms
POST /checkout	<200ms	<500ms	<1000ms
GET /search	<150ms	<400ms	<800ms

Database Query Budget

Query Type	Budget	Current
Simple reads	<50ms	42ms
Complex joins	<200ms	185ms
Aggregations	<500ms	450ms
Queries per page	<20	18

Core Web Vitals

Metric	Good	Poor	Target
LCP (Largest Contentful Paint)	<2.5s	>4.0s	<2.0s
FID (First Input Delay)	<100ms	>300ms	<50ms
CLS (Cumulative Layout Shift)	<0.1	>0.25	<0.05

Page-Specific Budgets

Homepage

• Time to Interactive: <3s
• Total Blocking Time: <300ms
• Speed Index: <3s

Product Page

• Time to Interactive: <4s
• Images loaded: <2s
• Reviews section: <1s

Checkout

• Time to Interactive: <3s
• Payment processing: <2s
• Zero layout shifts

Third-Party Scripts

Service	Budget	Purpose
Analytics	30 KB	Google Analytics
Chat Widget	50 KB	Customer support
Payment	100 KB	Stripe
Total	180 KB

## Enforcement Strategy

### 1. CI/CD Integration

```yaml
# .github/workflows/performance-budget.yml
name: Performance Budget Check

on: [pull_request]

jobs:
  budget-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Build production bundle
        run: npm run build

      - name: Check bundle size
        run: |
          npx bundlesize

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

2. Webpack Bundle Analyzer

// webpack.config.js
const BundleAnalyzerPlugin =
  require("webpack-bundle-analyzer").BundleAnalyzerPlugin;

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: process.env.ANALYZE ? "server" : "disabled",
    }),
  ],
  performance: {
    hints: "error",
    maxAssetSize: 200000, // 200 KB
    maxEntrypointSize: 400000, // 400 KB
  },
};

3. package.json Configuration

{
  "bundlesize": [
    {
      "path": "./dist/js/main.*.js",
      "maxSize": "200 KB"
    },
    {
      "path": "./dist/css/main.*.css",
      "maxSize": "50 KB"
    },
    {
      "path": "./dist/js/vendor.*.js",
      "maxSize": "150 KB"
    }
  ]
}

Monitoring Plan

Real User Monitoring (RUM)

// Track Core Web Vitals
import { getCLS, getFID, getFCP, getLCP, getTTFB } from "web-vitals";

function sendToAnalytics(metric) {
  const body = JSON.stringify(metric);

  if (navigator.sendBeacon) {
    navigator.sendBeacon("/analytics", body);
  } else {
    fetch("/analytics", { body, method: "POST", keepalive: true });
  }
}

getCLS(sendToAnalytics);
getFID(sendToAnalytics);
getLCP(sendToAnalytics);

Synthetic Monitoring

# Lighthouse CI
lhci autorun --config=.lighthouserc.json

# WebPageTest API
curl "https://www.webpagetest.org/runtest.php?url=https://example.com&k=API_KEY"

Performance Dashboard

**Daily Metrics:**

- Bundle size trend
- API latency percentiles
- Core Web Vitals scores
- Page load times

**Alerts:**

- Bundle size exceeds budget by 10%
- LCP >2.5s for >5% of users
- API p95 >500ms
- Any metric exceeds budget

Optimization Strategies

Reduce Bundle Size

// Code splitting
const ProductPage = lazy(() => import("./ProductPage"));

// Tree shaking
import { specific } from "library"; // ✅
import * as library from "library"; // ❌

// Dynamic imports
if (featureFlag) {
  const module = await import("./feature");
}

Optimize API Calls

// Parallel requests
const [user, orders] = await Promise.all([fetchUser(id), fetchOrders(id)]);

// Caching
const cachedData = await redis.get(key);
if (cachedData) return cachedData;

// Pagination
const products = await db.products
  .find()
  .limit(20)
  .skip((page - 1) * 20);

Optimize Database Queries

-- Add indexes
CREATE INDEX idx_orders_user_created ON orders(user_id, created_at);

-- Limit columns
SELECT id, name FROM products; -- ✅
SELECT * FROM products;        -- ❌

-- Use EXPLAIN
EXPLAIN ANALYZE SELECT ...;

Budget Violation Response

When Budget Exceeded

1. Immediate:

   • Block PR from merging
   • Notify team in Slack
   • Create ticket

2. Within 24 hours:

   • Investigate cause
   • Identify optimization opportunities
   • Propose fix or budget increase

3. Decision:

   • Fix code (preferred)
   • Increase budget (requires justification)

Budget Increase Request Template

## Budget Increase Request

**Component:** Main JS bundle
**Current Budget:** 200 KB
**Requested Budget:** 250 KB
**Reason:** Added critical feature X

**Impact Analysis:**

- Load time increase: +0.5s
- User impact: Medium
- Revenue impact: Unknown

**Alternatives Considered:**

1. Code splitting: Reduces to 210 KB (preferred)
2. Remove feature Y: Reduces to 195 KB (rejected)
3. Lazy loading: Complex, 3 weeks effort

**Recommendation:** Implement code splitting

Best Practices

1. Set realistic budgets: Based on user data
2. Enforce in CI: Automated checks
3. Monitor continuously: RUM + synthetic
4. Review quarterly: Adjust as needed
5. Prioritize UX: User-centric metrics
6. Document exceptions: Why budget increased
7. Celebrate wins: When under budget

Output Checklist

• Bundle size budgets defined
• API latency targets set
• Database query budgets
• Core Web Vitals targets
• Page-specific budgets
• CI/CD enforcement configured
• Monitoring dashboard
• Alert thresholds set
• Violation response process
• Regular review schedule