import-cost-enforcer

Enforce bundle size budgets and stop accidental bloat in CI/CD. The CLI scans your built assets (raw/gzip/brotli), compares them to a baseline and budgets, prints a clear report, and exits non‑zero on violations.

Install

npm i -D import-cost-enforcer

Quick start

1. Build your app to dist (or any output dir).
2. Create an initial baseline from your current main build.

npx import-cost-enforcer \
  --dist dist \
  --write-baseline .cache/baseline.json

3. In PRs/CI, compare the current build against the baseline and fail on regressions.

npx import-cost-enforcer \
  --dist dist \
  --baseline .cache/baseline.json \
  --metrics gzip,brotli

CLI

npx import-cost-enforcer --dist <dir> [options]

• --dist <dir>: directory to scan (default: dist)
• --config <file>: JSON config path (default: import-cost.enforcer.json if present)
• --baseline <file>: baseline JSON to compare against (created from a previous run)
• --write-baseline <file>: write the current measurement as a new baseline (only written when this flag is provided)
• --threshold <n>: percent threshold for total increase (default: 30)
• --metrics <list>: comma list of raw,gzip,brotli (default: gzip,brotli)
• --json-out <file>: write a JSON report artifact
• --ignore <globs>: comma list of file globs to ignore (default includes **/*.map)

Exit codes:

• 0: no violations
• 1: violations detected (threshold/budgets)
• 2: unexpected error

Configuration

Place an optional import-cost.enforcer.json in your repo or point to a custom path via --config.

{
  "distDir": "dist",
  "threshold": { "type": "percent", "limit": 30 },
  "metrics": ["brotli", "gzip"],
  "budgets": [
    { "target": "total", "maxKB": 800, "metric": "brotli" },
    { "target": "file:assets/*.js", "maxKB": 200, "metric": "gzip" }
  ],
  "ignore": ["**/*.map"],
  "report": { "jsonOut": "reports/import-cost.json" },
  "baselineIn": ".cache/baseline.json"
}

Notes:

• target supports total and file:<glob>.
• Thresholds are checked per selected metric; any metric exceeding the limit triggers a violation.
• Baseline writing only occurs with --write-baseline (CLI flag). This prevents accidental overwrites from config.

GitHub Actions example

- name: Build
  run: npm run build

- name: Enforce import costs
  run: |
    npx import-cost-enforcer \
      --dist dist \
      --baseline .cache/baseline.json \
      --metrics gzip,brotli \
      --json-out reports/import-cost.json

To refresh the baseline on main (after an intentional change), run the CLI with --write-baseline and commit/upload the updated baseline file or artifact.

Why this tool?

• Catch accidental bloat early with a simple, bundler-agnostic check.
• Enforce both relative regressions (percent threshold) and absolute budgets (per total or file patterns).
• Human‑readable report + optional JSON artifact for CI.

License

MIT