audit-bundle-size

Files (1)

• SKILL.md

SKILL.md (first lines)

# audit-bundle-size — Find and Eliminate Bundle Bloat

**Degree of freedom: MIXED** — Offender triage and swap choice `[HIGH freedom]`;
Phase 1 production build + analyser `[LOW freedom — run exactly]`.

> **Audit-and-fix exception.** Measure the payload, then shrink it. Runtime
> slowness → `audit-performance`.
>
> Fix only what the measurement named, in the files it named; a repo-wide
> dependency sweep the report did not list is a different session. Edit
> surgically — the offending import, `dynamic()` boundary, or chunk config —
> rather than rewriting whole files. Pre-existing bugs met on the way go in
> the report as follow-ups. Add or change tests only where the repo already
> keeps them for that surface; scratch checks and generated analyser reports
> (`client.html`, `bundle-report.html`) stay out of the commit. An
> `ANALYZE=true`-guarded analyser config stays only if the repo already keeps one.

**Every kilobyte of JavaScript the browser must download, parse, and compile
before showing anything costs real users real time.** A large initial bundle is
the #1 avoidable cause of slow LCP and poor Core Web Vitals. Find exactly what
is bloating it and fix each item.

## This skill vs neighbors

| Skill | Owns |
|---|---|
| **audit-bundle-size** (this) | Analyse and shrink the JavaScript bundle: code splitting, initial load |
| `audit-performance` | Audit and fix runtime performance: Core Web Vitals, load priority |
| `workflow-quality-gate` | Pre-release gate across red-team, security, bundle, performance, unit tests |
| `workflow-launch-ready` | Launch-preparation sweep for a new app or major release |

## How to reason — Observe → Interpret → Classify → Severity

1. **Observe** — quote First Load JS / chunk gzip and the treemap contributor (`file` + package)
2. **Interpret** — is this unused code on the critical path, a duplicate, or a missing split?
3. **Classify** — giant-vendor / full-library import / missing-lazy / unused-dep / dev-in-prod / duplicate
4. **Severity** — by gzip on the initial route: >250 KB First Load JS = review; do not delete a feature to save KB

## Worked example

> **Observe:** Next.js First Load JS 420 KB gzip. Treemap: default `lodash`
> import in `lib/utils.ts`; `moment` with all locales in the shared layout.
> **Interpret:** two libraries pull unused code onto every route.
> **Classify:** full-library import + oversized date lib.
> **Severity:** High — over the 250 KB review threshold.
> **Finding:** named `lodash/debounce` + replace `moment` with `dayjs`; remesure
> First Load JS before claiming a save.

---

## Phase 0: Detect bundler and existing setup  [HIGH freedom]

```
package.json scripts.build   → build command and framework
vite.config.*                → Vite + rollupOptions
next.config.*                → Next.js (webpack / Turbopack)
webpack.config.*             → standalone Webpack
astro.config.*               → Astro (islands, Vite underneath)
```

Identify:
- **Bundler**: Vite / Webpack / Rollup / esbuild / Turbopack / Next.js built-in
- **Analyser available**: `rollup-plugin-visualizer`, `webpack-bundle-analyzer`,
  `@next/bundle-analyzer`, `source-map-explorer`
- **Framework**: Next.js (App / Pages), SvelteKit, Astro, Remix, Nuxt, Vite SPA

---

## Phase 1: Run a production build with analysis  [LOW freedom — run exactly]

### Vite / Rollup

If `rollup-plugin-visualizer` is not installed:
```bash
npm install --save-dev rollup-plugin-visualizer
```

Add temporarily to `vite.config.ts`:
```typescript
import { visualizer } from 'rollup-plugin-visualizer';
// in plugins array:
visualizer({ open: false, filename: 'dist/bundle-report.html', gzipSize: true })
```

Then build:
```bash
npm run build 2>&1 | tail -40
```

Read `dist/bundle-report.html` for the treemap, or parse `dist/stats.json` if
the plugin is configured to output JSON.

### Next.js

```bash
ANALYZE=true npm run build 2>&1 | tail -60
```

This requires `@next/bundle-analyzer` in `next.config.*`:
```javascript
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});
module.exports = withBundleAnalyzer({ /* your config */ });
```

Read the generated `client.html` report. Key number: **First Load JS** per route.
Next.js prints this in the build output — capture it for before/after comparison.

### If no analyser is installed

Use `source-map-explorer` on the build output:
```bash
npx source-map-explorer 'dist/**/*.js' --html dist/bundle-report.html
```

Or for a quick size summary:
```bash
find dist -name '*.js' | xargs ls -lh | sort -k5 -hr | head -20

From kensaurus/skills, MIT.

More from kensaurus/skills