analyze-bundle

What this skill does

# Bundle Analyzer

Identify what's inflating your web application's bundle, trace it to specific dependencies and import patterns, and produce a prioritized list of optimizations with estimated size savings.

## When to Activate

- User wants to understand what's making their bundle large
- Initial page load is slow and JavaScript bundle size may be a factor
- Before or after a dependency update to measure size impact
- CI is flagging a bundle size regression
- Preparing to ship a performance improvement and need a baseline
- Code-splitting, lazy loading, or tree-shaking improvements are being planned

## Step 1: Detect Bundler and Stack

Scan for config files to identify the bundler and framework:

| Signal file                              | Bundler             | Analysis approach                                                        |
| ---------------------------------------- | ------------------- | ------------------------------------------------------------------------ |
| `vite.config.ts` / `vite.config.js`      | Vite                | Build with `--report` or `vite-bundle-visualizer`                        |
| `webpack.config.*`                       | Webpack             | `webpack-bundle-analyzer` via stats JSON                                 |
| `next.config.*`                          | Next.js (Webpack)   | `@next/bundle-analyzer` or source-map-explorer on `.next/static/chunks/` |
| `rollup.config.*`                        | Rollup              | Build with `rollup-plugin-visualizer`                                    |
| `esbuild.config.*` or esbuild in scripts | esbuild             | `--metafile` flag → analyze with `esbuild-bundle-analyzer`               |
| `parcel.config.*` / `.parcelrc`          | Parcel              | `parcel build --detailed-report`                                         |
| `turbo.json`                             | Turbopack/Turborepo | Check individual apps in the monorepo for their bundler                  |

Also check `package.json` scripts for build commands to understand the build pipeline:

```bash
cat package.json | grep -A5 '"scripts"'
```

If the project uses a monorepo (nx.json, turbo.json, pnpm workspaces), identify which packages have browser bundles before proceeding.

## Step 2: Check for Existing Build Artifacts

Before re-building, check whether a recent build already exists:

```bash
# Vite / generic
find dist -name "*.js" -mtime -1 2>/dev/null | head -20
ls -lhS dist/ 2>/dev/null | head -20

# Next.js
ls -lhS .next/static/chunks/ 2>/dev/null | head -20

# Create React App / webpack
ls -lhS build/static/js/ 2>/dev/null | head -20
```

If fresh artifacts are present (modified within the last day), skip rebuilding and use the existing output. Note this in your report.

If no build artifacts exist, run the build in Step 3.

## Step 3: Generate Bundle Report

Run the appropriate analysis tool based on the bundler detected in Step 1.

### Vite

Check for `vite-bundle-visualizer` or use the built-in rollup options:

```bash
# Using vite-bundle-visualizer (preferred if available)
npx vite-bundle-visualizer --output /tmp/bundle-report.json 2>/dev/null

# Fallback: build with rollup options to emit stats
npm run build -- --mode production 2>/dev/null
```

After building, read the manifest if present:

```bash
cat dist/.vite/manifest.json 2>/dev/null | head -100
```

### Webpack

```bash
# Generate stats.json
npx webpack --config webpack.config.js --profile --json > /tmp/webpack-stats.json 2>/dev/null

# If that fails, check if webpack is configured in package.json scripts
npm run build -- --stats 2>/dev/null
```

Then use `webpack-bundle-analyzer` in stats mode:

```bash
npx webpack-bundle-analyzer /tmp/webpack-stats.json --mode static --report /tmp/bundle-report.html --no-open 2>/dev/null
```

### Next.js

```bash
# Check if @next/bundle-analyzer is configured
grep -r "bundle-analyzer\|withBundleAnalyzer" next.config.* 2>/dev/null

# Run with ANALYZE flag if configured
ANALYZE=true npm run build 2>/dev/null

# Fallback: analyze .next/static/chunks directly
ls -lhS .next/static/chunks/*.js 2>/dev/null | head -30
```

### source-map-explorer (Universal Fallback)

When bundler-specific tools aren't available, `source-map-explorer` works on any build output that includes source maps:

```bash
# Ensure source maps exist
ls dist/*.js.map build/static/js/*.js.map .next/static/chunks/*.js.map 2>/dev/null | head -5

# Run source-map-explorer on the detected build output (use only the matching path to
# avoid the second command silently overwriting the first report)
if [ -d dist ]; then
  npx source-map-explorer 'dist/*.js' --json > /tmp/sme-report.json 2>/dev/null
elif [ -d build/static/js ]; then
  npx source-map-explorer 'build/static/js/*.js' --json > /tmp/sme-report.json 2>/dev/null
fi
```

Parse the JSON output to extract module sizes.

### Raw File Sizes (Minimal Fallback)

If no analysis tool is available and source maps are absent:

```bash
# Raw sizes sorted by size
find dist build .next/static/chunks -name "*.js" -not -name "*.map" 2>/dev/null \
  | xargs du -h | sort -rh | head -20

# Gzip estimate (multiply raw size by ~0.3 for a rough gzip estimate)
find dist -name "*.js" -not -name "*.map" 2>/dev/null \
  | xargs gzip -c | wc -c
```

Note: raw fallback provides size totals only — no per-module breakdown. Recommend the user install `vite-bundle-visualizer` or enable source maps for a full analysis.

## Step 4: Identify Heaviest Modules and Dependencies

From the report data, extract:

### Top Modules by Size

List the 15 largest modules (by parsed/compressed size). For each entry note:

- Module path or package name
- Size (raw bytes and gzip estimate if available)
- Whether it's a production dependency, dev dependency, or application code
- Whether a lighter alternative exists

### Duplicate Packages

Check if the same package appears at multiple versions (common with monorepos and conflicting peer dependencies):

```bash
# Preferred: use npm/pnpm/yarn to report all resolved versions — this catches nested
# hoisting conflicts that a flat node_modules scan would miss
npm ls --all --json 2>/dev/null | node -e "
const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
const seen = {};
function walk(node, depth) {
  if (!node || depth > 10) return;
  if (node.name && node.version) {
    if (!seen[node.name]) seen[node.name] = new Set();
    seen[node.name].add(node.version);
  }
  for (const dep of Object.values(node.dependencies || {})) walk(dep, depth+1);
}
walk(data, 0);
Object.entries(seen).filter(([,vs])=>vs.size>1)
  .forEach(([n,vs])=>console.log(n+': '+[...vs].join(', ')));
" 2>/dev/null | head -20

# Fallback if npm ls is too slow: flat scan (note: excludes nested node_modules,
# so it may miss hoisted duplicates — use npm ls output for authoritative results)
find node_modules -maxdepth 2 -name "package.json" \
  | xargs node -e "
const fs=require('fs');
const map={};
process.argv.slice(1).forEach(f=>{
  try{
    const p=JSON.parse(fs.readFileSync(f,'utf8'));
    if(!map[p.name]) map[p.name]=[];
    map[p.name].push(p.version);
  }catch(e){}
});
Object.entries(map).filter(([,vs])=>vs.length>1)
  .forEach(([n,vs])=>console.log(n+': '+vs.join(', ')));
" 2>/dev/null | head -20
```

Duplicates that appear in multiple versions often land in the bundle multiple times. Flag any duplicate that is both large (>50 KB raw) and frequently used (React, lodash, date-fns, etc.).

### Tree-Shaking Issues

Scan for import patterns that defeat tree-shaking:

```bash
# Namespace imports (import * as X) — barrel imports that pull in everything
grep -r "import \* as" src/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -20

# Default imports from packages known to have named exports (lodash, date-fns, ramda)
grep -r "import _ from 'lodash'" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -5
grep -r "import moment from 'moment'" src/ --inc