performance-budget-enforcer

by charlie-morrison

Install this Skill

curl -fsSL -o performance-budget-enforcer.zip https://skill.seembox.com/api/v1/skills/performance-budget-enforcer/download && unzip performance-budget-enforcer.zip

Download performance-budget-enforcer.zip

SKILL.md About

---
name: performance-budget-enforcer
description: Define, measure, and enforce web performance budgets — bundle sizes, asset counts, image weights, third-party scripts. Fails CI when budgets are exceeded. Tracks trends across builds.
---

# Performance Budget Enforcer

Set performance budgets for web projects and enforce them in CI. Measures JS/CSS bundle sizes, image weights, font sizes, third-party script counts, and total transfer size. Compares against budgets, flags regressions, and tracks trends.

Use when: "check bundle size", "set performance budget", "are we over budget", "track asset size", "web performance audit", "lighthouse budget", or integrating perf checks into CI/CD.

## Commands

### 1. `measure` — Measure Current Asset Sizes

Scan the build output directory and measure everything.

```bash
# Auto-detect build output directory
BUILD_DIR=""
for dir in dist build out .next/static public/build _site; do
  if [ -d "$dir" ]; then
    BUILD_DIR="$dir"
    break
  fi
done

if [ -z "$BUILD_DIR" ]; then
  echo "No build directory found. Run your build command first, or specify the directory."
  exit 1
fi

echo "Scanning: $BUILD_DIR"
```

#### JavaScript Bundles
```bash
# JS files with sizes (sorted largest first)
find "$BUILD_DIR" -name "*.js" -type f -exec du -b {} + 2>/dev/null | sort -rn | head -20
TOTAL_JS=$(find "$BUILD_DIR" -name "*.js" -type f -exec du -b {} + 2>/dev/null | awk '{s+=$1} END {print s+0}')
echo "Total JS: $TOTAL_JS bytes ($(echo "scale=1; $TOTAL_JS / 1024" | bc) KB)"

# Gzipped sizes (more realistic transfer size)
find "$BUILD_DIR" -name "*.js" -type f | while read f; do
  ORIG=$(wc -c < "$f")
  GZIP=$(gzip -c "$f" | wc -c)
  echo "$GZIP $ORIG $f"
done | sort -rn | head -10
TOTAL_JS_GZ=$(find "$BUILD_DIR" -name "*.js" -type f -exec sh -c 'gzip -c "$1" | wc -c' _ {} \; 2>/dev/null | awk '{s+=$1} END {print s+0}')
echo "Total JS (gzip): $TOTAL_JS_GZ bytes ($(echo "scale=1; $TOTAL_JS_GZ / 1024" | bc) KB)"
```

#### CSS Bundles
```bash
find "$BUILD_DIR" -name "*.css" -type f -exec du -b {} + 2>/dev/null | sort -rn | head -10
TOTAL_CSS=$(find "$BUILD_DIR" -name "*.css" -type f -exec du -b {} + 2>/dev/null | awk '{s+=$1} END {print s+0}')
echo "Total CSS: $TOTAL_CSS bytes ($(echo "scale=1; $TOTAL_CSS / 1024" | bc) KB)"
```

#### Images
```bash
find "$BUILD_DIR" -type f $ -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.svg" -o -name "*.webp" -o -name "*.avif" $ \
  -exec du -b {} + 2>/dev/null | sort -rn | head -15
TOTAL_IMG=$(find "$BUILD_DIR" -type f $ -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.svg" -o -name "*.webp" -o -name "*.avif" $ \
  -exec du -b {} + 2>/dev/null | awk '{s+=$1} END {print s+0}')
echo "Total images: $TOTAL_IMG bytes ($(echo "scale=1; $TOTAL_IMG / 1024" | bc) KB)"

# Flag unoptimized images (PNG > 100KB, JPG > 200KB without WebP alternative)
find "$BUILD_DIR" -name "*.png" -size +100k -type f 2>/dev/null
find "$BUILD_DIR" -name "*.jpg" -size +200k -type f 2>/dev/null
```

#### Fonts
```bash
find "$BUILD_DIR" -type f $ -name "*.woff" -o -name "*.woff2" -o -name "*.ttf" -o -name "*.otf" -o -name "*.eot" $ \
  -exec du -b {} + 2>/dev/null | sort -rn
TOTAL_FONT=$(find "$BUILD_DIR" -type f $ -name "*.woff" -o -name "*.woff2" -o -name "*.ttf" -o -name "*.otf" -o -name "*.eot" $ \
  -exec du -b {} + 2>/dev/null | awk '{s+=$1} END {print s+0}')
echo "Total fonts: $TOTAL_FONT bytes ($(echo "scale=1; $TOTAL_FONT / 1024" | bc) KB)"

# Flag non-woff2 fonts (should be woff2 in 2026)
find "$BUILD_DIR" -type f $ -name "*.ttf" -o -name "*.otf" -o -name "*.eot" -o -name "*.woff" $ 2>/dev/null
```

#### Total Transfer Size
```bash
TOTAL=$(find "$BUILD_DIR" -type f -exec du -b {} + 2>/dev/null | awk '{s+=$1} END {print s+0}')
echo "Total build output: $TOTAL bytes ($(echo "scale=1; $TOTAL / 1024 / 1024" | bc) MB)"
FILE_COUNT=$(find "$BUILD_DIR" -type f | wc -l)
echo "Total files: $FILE_COUNT"
```

### 2. `budget` — Define Performance Budget

Create or update a `.perfbudget.json` file in the project root.

Default budgets (adjust per project type):

```json
{
  "budgets": {
    "js_total_kb": 300,
    "js_total_gzip_kb": 100,
    "js_single_file_kb": 150,
    "css_total_kb": 100,
    "css_single_file_kb": 50,
    "img_total_kb": 1000,
    "img_single_file_kb": 200,
    "font_total_kb": 200,
    "total_transfer_mb": 3,
    "total_file_count": 200,
    "third_party_scripts": 5
  },
  "presets": {
    "strict": {
      "js_total_gzip_kb": 50,
      "total_transfer_mb": 1
    },
    "mobile": {
      "js_total_gzip_kb": 70,
      "img_total_kb": 500,
      "total_transfer_mb": 2
    }
  }
}
```

Preset suggestions based on project type:
- **SPA (React/Vue/Svelte)**: JS 150KB gzip, total 2MB
- **Static site / blog**: JS 50KB gzip, total 1MB
- **E-commerce**: JS 200KB gzip, images 2MB, total 5MB
- **Dashboard / admin**: JS 300KB gzip, total 5MB (internal tools can be larger)

### 3. `check` — Enforce Budget

Compare measurements against `.perfbudget.json`. This is the CI command.

```bash
# Read budget file
if [ ! -f ".perfbudget.json" ]; then
  echo "No .perfbudget.json found. Run 'budget' command first to create one."
  echo "Using default budgets..."
fi
```

For each metric, compare measured vs budget:

```
✅ JS total (gzip):   87 KB / 100 KB budget (87%)
✅ CSS total:          34 KB / 100 KB budget (34%)
⚠️  Images total:     890 KB / 1000 KB budget (89%) — approaching limit
❌ JS single file:    180 KB / 150 KB budget (120%) — OVER BUDGET
   └─ dist/vendor.chunk.js: 180 KB
❌ Total transfer:    3.4 MB / 3 MB budget (113%) — OVER BUDGET

RESULT: 2 budget violations found
```

Exit codes:
- 0: All within budget
- 1: One or more budgets exceeded
- 2: Budget file missing (warning only)

### 4. `trend` — Track Size Over Time

Append current measurements to `.perfbudget-history.json`:

```json
{
  "history": [
    {
      "date": "2026-04-28",
      "commit": "abc123",
      "branch": "main",
      "js_total_gzip_kb": 87,
      "css_total_kb": 34,
      "img_total_kb": 890,
      "total_transfer_mb": 2.1
    }
  ]
}
```

Display trend:
```
JS (gzip) over last 10 builds:
  Apr 20: 72 KB ██████████████
  Apr 21: 75 KB ███████████████
  Apr 23: 82 KB ████████████████
  Apr 25: 87 KB █████████████████   ↑ +20.8% in 8 days
  Budget: 100 KB ████████████████████ (limit)
```

Flag: "JS bundle grew 20.8% in 8 days — investigate recent additions."

### 5. `third-party` — Audit Third-Party Scripts

Scan HTML files and JS bundles for external domains:

```bash
# Find external script tags
rg -n 'src="https?://[^"]*"' -g '*.html' "$BUILD_DIR" 2>/dev/null

# Find external URLs in JS bundles
rg -o 'https?://[a-zA-Z0-9.-]+\.[a-z]{2,}' -g '*.js' "$BUILD_DIR" 2>/dev/null | \
  awk -F: '{print $NF}' | sort -u

# Common third-party domains to flag
# Analytics: google-analytics, segment, mixpanel, amplitude, hotjar, fullstory
# Ads: doubleclick, googlesyndication, facebook, criteo
# Chat: intercom, drift, zendesk, crisp
# A/B: optimizely, launchdarkly, split.io
```

Categorize by type (analytics, ads, chat, A/B testing, error tracking, CDN) and report impact on load time.

### 6. `optimize` — Suggest Optimizations

Based on measurements, provide specific actionable suggestions:

- **Large JS bundles**: Suggest code splitting, dynamic imports, tree shaking. Show which chunks are largest.
- **Uncompressed assets**: Check if gzip/brotli is configured. Measure compression ratios.
- **Unoptimized images**: Suggest WebP/AVIF conversion, lazy loading, responsive images.
- **Too many fonts**: Suggest subsetting, reducing font weights, system font fallbacks.
- **Third-party bloat**: Suggest self-hosting, defer/async loading, removing unused scripts.
- **Large CSS**: Suggest PurgeCSS/Tailwind purge, critical CSS extraction, unused CSS removal.

## Output Formats

- **text** (default): Human-readable with color indicators and bar charts
- **json**: Machine-readable `{measurements: {}, budget: {}, violations: [], suggestions: []}`
- **markdown**: PR comment format with tables and status icons
- **github-annotations**: `::warning file=...::Budget exceeded` format for GitHub Actions

## CI Integration Examples

```yaml
# GitHub Actions
- name: Check performance budget
  run: |
    npm run build
    # Agent runs: performance-budget-enforcer check
    # Exits 1 if over budget

# As PR comment (markdown format)
- name: Post budget report
  run: |
    # Agent runs: performance-budget-enforcer check --format markdown > budget-report.md
    gh pr comment $PR_NUMBER --body-file budget-report.md
```

## Notes

- Requires a built project (run your build command first)
- Gzip size measurement uses actual gzip compression, not estimates
- History file (`.perfbudget-history.json`) should be committed to track trends
- Does not run Lighthouse or browser-based metrics — focuses on static asset analysis which is fast and deterministic
- For Core Web Vitals (CLS, LCP, FID), use Lighthouse or web-vitals library separately

_meta.json Metadata

{
  "ownerId": "kn7d5eszdfwftk153ymhdm4qhs83qsqy",
  "publishedAt": 1777333280596,
  "slug": "performance-budget-enforcer",
  "version": "1.0.0"
}