Performance Budget Trigger

Triggers performance budget analysis after build commands, blocking deployments that exceed bundle size and code quality thresholds.

When to Use This Hook

Attach this hook when you need to:

• Automatically analyze Next.js, Webpack, or Vite build output for bundle size regressions
• Block deployments when JavaScript bundles exceed defined kilobyte budgets
• Get real-time optimization recommendations when code changes impact performance

Consider alternatives when:

• You use a dedicated performance monitoring service like Lighthouse CI in your pipeline
• Your project is a backend service with no client-side bundle to measure

Quick Start

Configuration

Copy
name: performance-budget-trigger
type: hook
trigger: PostToolUse
category: performance

Example Trigger

Copy
# Hook triggers after a build command succeeds
npm run build
# Hook automatically analyzes .next/static/chunks for size

Example Output

Performance Budget Trigger: Analyzing build output...
  Total bundle size: 287KB
  Budget limit: 350KB
  Bundle size within budget: 287KB / 350KB
  Remaining budget: 63KB
  Top 5 chunks by size:
    framework-a1b2c3.js   98KB
    main-d4e5f6.js        67KB
    commons-g7h8i9.js     54KB
    pages/_app-j0k1.js    38KB
    webpack-l2m3n4.js     30KB

Core Concepts

Budget Analysis Overview

Aspect	Details
Bundle Size Check	Sums all JS chunks in build output directory
Budget Threshold	Configurable limit in KB (default 350KB)
File-Level Analysis	Ranks individual chunks by size for targeted optimization
Import Analysis	Detects wildcard imports and heavy libraries like moment.js or full lodash
Warning Zone	Alerts when remaining budget drops below 50KB

Budget Enforcement Workflow

Build Command Completes
         |
    Success? ─── No ──→ Skip
         |
        Yes
         |
   Find Build Dir
         |
   Sum JS Chunks
         |
   Compare to Budget
    /           \
Under            Over
  |               |
Report OK     Block Deploy
+ Remaining   + Show Top Files
  Budget      + Recommendations

Configuration

Parameter	Type	Default	Description
budget_limit_kb	number	350	Maximum total bundle size in kilobytes
build_dir	string	.next/static/chunks	Directory containing build output JS files
warning_threshold_kb	number	50	Warn when remaining budget is below this value
check_imports	boolean	true	Scan source files for heavy import patterns
block_on_exceed	boolean	true	Exit with error code 2 when budget is exceeded

Best Practices

1. Start with a Generous Budget - Set your initial budget 20% above your current bundle size, then ratchet it down as you optimize. Starting too tight causes friction before the team builds optimization habits.

2. Monitor File-Level Changes - The top-5 chunk report identifies where size is concentrated. Focus optimization efforts on the largest chunks first for maximum impact per effort invested.

3. Check on Edit, Not Just Build - The hook also watches for heavy import patterns (wildcard imports, moment.js, full lodash) during file edits, catching regressions before the next build.

4. Separate Budgets by Route - For Next.js apps, consider per-route budgets rather than a single global budget. A heavy dashboard page should not consume the budget meant for a lightweight landing page.

5. Track Budget Trends Over Time - Log budget usage after each build to spot gradual creep. A chart of bundle size over commits reveals whether optimization gains are being maintained.

Common Issues

1. Build Directory Not Found - The hook defaults to .next/static/chunks. For Vite or Webpack projects, update build_dir to dist/assets or your custom output path. The hook will report an error if the directory is missing.

2. stat Command Incompatibility - macOS uses stat -f%z while Linux uses stat -c%s for file size. The hook should include both variants with a fallback to ensure cross-platform operation.

3. Source Maps Inflating Size - If source maps are included in the build directory, they inflate the reported bundle size. Exclude .map files from the size calculation or move them to a separate directory.