bundle-size-guardian

An open-source npm CLI tool (and optional MCP server) that uses an LLM to audit your JavaScript/TypeScript project's dependencies, surface bloated imports, and automatically refactor them to lighter alternatives.

Installation

npm install -g bundle-size-guardian
# or run directly with npx
npx bundle-size-guardian analyze

Requirements

• Node.js 18+
• ANTHROPIC_API_KEY environment variable (required for suggest and refactor commands on unlisted packages)

Commands

analyze — Audit bundle sizes

Scans package.json and all source files; reports every dependency's gzip size and severity.

npx bundle-size-guardian analyze [path]

Output:

Bundle-Size-Guardian — Audit Report
────────────────────────────────────
✖  CRITICAL   moment               329 kB   uses: default
⚠  MODERATE   lodash                71 kB   uses: debounce, cloneDeep, pick, omit, groupBy
✔  FINE       axios                 13 kB   uses: default
✔  FINE       picocolors             3 kB   uses: default

Total audited: 4 packages  |  Potential savings: up to 400 kB

Severity thresholds:

• CRITICAL — > 100 kB gzip
• MODERATE — 20–100 kB gzip
• FINE — < 20 kB gzip

suggest — Get lighter alternatives

Suggests smaller alternatives for heavy dependencies, ranked by bundle savings.

# Suggestions for all heavy deps in a project
npx bundle-size-guardian suggest [path]

# Suggestions for a single package
npx bundle-size-guardian suggest --package moment

Output:

Suggestions for moment (329 kB gzip)
──────────────────────────────────────
1. date-fns        13 kB   drop-in          Tree-shakeable, same API surface for format/parse/diff
   Example: import { format, parseISO } from 'date-fns';
2. dayjs             3 kB   drop-in          Moment-compatible API, immutable, much smaller
3. native            0 kB   partial-rewrite  Built-in Intl.DateTimeFormat covers most formatting use cases

refactor — Auto-rewrite imports

Uses the LLM to rewrite import statements and call sites throughout your project.

# Dry run — show diff only (safe default)
npx bundle-size-guardian refactor --package moment --to date-fns

# Apply changes to disk
npx bundle-size-guardian refactor --package lodash --to lodash-es --write

# Apply + run tests; roll back automatically if tests fail
npx bundle-size-guardian refactor --package axios --to native --write --test

Options:

| Flag | Description | | --- | --- | | --package <name> | Package to replace (required) | | --to <replacement> | Replacement package or native (required) | | --dry-run | Show diff without writing (default) | | --write | Write changes to disk | | --test | Run tests after patching; roll back on failure |

The refactor tool adds // TODO: verify comments on any conversion it is uncertain about. If a migration is rated manual, it prints the suggestion but skips the automated rewrite.

refactor-all — Refactor everything in one pass

Combines analyze, suggest, and refactor into a single command. Finds all heavy dependencies, picks the best automatically-applicable alternative for each, and rewrites them.

# Dry run — show diffs for all heavy deps (safe default)
npx bundle-size-guardian refactor-all

# Apply all changes
npx bundle-size-guardian refactor-all --write

# Apply + run tests after each package; roll back on failure
npx bundle-size-guardian refactor-all --write --test

Options:

| Flag | Description | | --- | --- | | --write | Write changes to disk (default is dry-run) | | --test | Run tests after each patch; roll back on failure |

Packages whose only alternatives have manual migration complexity are reported but skipped — they require hand-crafted changes.

MCP server mode

Run as an MCP server for use inside Claude Code or other MCP clients:

npx bundle-size-guardian --mcp

Add to your .claude/mcp_servers.json:

{
  "bundle-size-guardian": {
    "command": "npx",
    "args": ["bundle-size-guardian", "--mcp"]
  }
}

This exposes three tools: analyze_imports, suggest_alternatives, auto_refactor.

npm scripts

After installing the package, add these scripts to your project's package.json to run commands via npm run:

{
  "scripts": {
    "bundle:analyze":     "bundle-size-guardian analyze",
    "bundle:suggest":     "bundle-size-guardian suggest",
    "bundle:refactor-all": "bundle-size-guardian refactor-all --write",
    "bundle:refactor-all:test": "bundle-size-guardian refactor-all --write --test"
  }
}

Then run with:

npm run bundle:analyze
npm run bundle:suggest
npm run bundle:refactor-all
npm run bundle:refactor-all:test

If installed locally (npm install --save-dev bundle-size-guardian), npm resolves the bin automatically — no npx needed in scripts.

How it works

1. Import scanning — ts-morph parses all .ts/.tsx/.js/.jsx files and extracts every import declaration, including dynamic imports and require() calls.
2. Bundle size lookup — Queries the bundlephobia REST API for gzip sizes. Falls back to a local esbuild dry-run estimate if bundlephobia is unreachable (CI-friendly).
3. Alternative suggestions — Checks a built-in mapping of well-known heavy→light swaps first (fast, free, no API call). Falls back to Claude Sonnet for packages not in the seed list.
4. Code rewriting — Sends affected file contents to Claude Sonnet with instructions to rewrite imports and call sites. The LLM is prompted to be conservative: it adds // TODO: verify for any uncertain conversion rather than silently producing wrong code.

Known alternative mappings (built-in, no API key needed)

| Heavy package | Lighter alternatives | | --- | --- | | moment | date-fns, dayjs, native Intl | | lodash | lodash-es (tree-shakeable), native ES2020+ | | axios | native fetch, ky | | jquery | vanilla DOM APIs | | underscore | native array/object methods, lodash-es | | uuid | crypto.randomUUID() | | chalk | picocolors, kleur | | glob | fast-glob, tinyglobby | | rimraf | fs.rm (Node 16+) |

Contributing

To add a new known-alternative mapping, edit src/known-alternatives.ts and open a PR. See CONTRIBUTING.md for details.

License

MIT