🛡 ChunkGuard

PR-based bundle size guard for modern frontend applications.

ChunkGuard helps teams detect bundle size increases before they reach production. It compares your current branch against a base branch, calculates compressed bundle size, and optionally fails CI if thresholds are exceeded.

🚀 Why ChunkGuard?

Frontend bundle bloat often goes unnoticed until:

• Lighthouse scores drop
• Performance metrics degrade
• Production monitoring alerts fire

ChunkGuard shifts that detection left into your pull request workflow.

✨ Features

• ✅ Compare bundle size against a base branch
• ✅ Gzip-based size calculation (realistic transfer size)
• ✅ CI-friendly exit codes
• ✅ Configurable size thresholds
• ✅ Clear terminal output

📦 Installation

Run via npx

npx chunkguard --max-increase 50

Install as dev dependency

npm install --save-dev chunkguard

Then run:

npx chunkguard

🛠 Usage

chunkguard [options]

Options

| Option | Description | Default | |---|---|---| | --base <branch> | Base branch to compare against | main | | --dist <path> | Build output directory | dist | | --max-increase <kb> | Maximum allowed size increase (in KB) | none |

📊 Example

chunkguard --base main --max-increase 50

Output:

🛡 ChunkGuard Report

Base:    210.45 KB
Current: 238.12 KB
Diff:    +27.67 KB

If the threshold is exceeded:

❌ Bundle size exceeded threshold.

Exit code: 1 (CI fails)

📐 How Size Is Calculated

ChunkGuard:

1. Builds the base branch
2. Builds the current branch
3. Scans the dist folder
4. Finds all .js files
5. Calculates gzip-compressed size
6. Compares totals

This approximates real browser transfer size.

⚠️ Requirements

• Must be run inside a Git repository
• Repository must have at least one commit
• Base branch must exist
• Project must have a working npm run build script
• Build output must exist in the specified dist folder

📄 License

MIT