Bundle Size Auditor#

You added one import. Your Lighthouse score dropped 12 points. Your LCP went from 1.8s to 3.1s.

This skill parses your bundler's output — webpack stats JSON, Vite build report, or Next.js .next/ directory — identifies the largest chunks, finds which packages are bloating them, detects treeshaking failures, and gives you the exact code changes to fix it.

Supports webpack, Vite, Rollup, Next.js. Zero external API.

---

Trigger Phrases#

• "bundle too large", "my bundle is huge", "reduce bundle size"
• "webpack stats", "analyze webpack output", "chunk size"
• "bundle budget", "size limit", "bundle regression"
• "treeshaking not working", "dead code in bundle"
• "which package is largest", "find large dependencies"
• "Next.js bundle", "Vite build report"
• "/bundle-size-audit"

---

How to Provide Input#

bash

# Option 1: Webpack stats JSON (most detailed)
webpack --profile --json > stats.json
/bundle-size-audit stats.json

# Option 2: Vite build (auto-detected)
vite build
/bundle-size-audit dist/

# Option 3: Next.js build (auto-detected)
next build
/bundle-size-audit .next/

# Option 4: Rollup stats
rollup -c --bundleConfigAsCjs
/bundle-size-audit rollup-stats.json

# Option 5: Set size budgets
/bundle-size-audit --max-chunk 250kb --max-initial 500kb

# Option 6: Focus on a specific chunk or package
/bundle-size-audit --chunk main --package lodash

# Option 7: Generate CI fail-gate only
/bundle-size-audit --ci-config

---

Step 1: Detect Build Artifacts#

bash

python3 -c "
import os, json
from pathlib import Path

# Priority order for detection
checks = [
    ('webpack stats', ['stats.json', 'webpack-stats.json', 'build/stats.json']),
    ('Next.js', ['.next/build-manifest.json', '.next/server/pages-manifest.json']),
    ('Vite', ['dist/', 'dist/assets/']),
    ('Rollup', ['dist/', 'build/']),
    ('Create React App', ['build/static/js/', 'build/asset-manifest.json']),
]

found = []
for name, paths in checks:
    for p in paths:
        if os.path.exists(p):
            found.append((name, p))
            break

if found:
    for name, path in found:
        size = 0
        if os.path.isfile(path):
            size = os.path.getsize(path)
            print(f'Detected {name}: {path} ({size:,} bytes)')
        else:
            # Directory — count JS files
            js_files = list(Path(path).rglob('*.js'))
            total = sum(f.stat().st_size for f in js_files)
            print(f'Detected {name}: {path}/ ({len(js_files)} JS files, {total/1024:.0f} KB total)')
else:
    print('No build artifacts found.')
    print('Run your build first:')
    print('  webpack --profile --json > stats.json')
    print('  vite build')
    print('  next build')
"

---

Step 2: Parse Bundle Data#

For Webpack Stats JSON#

python

import json
from pathlib import Path

def parse_webpack_stats(stats_path):
    """Parse webpack stats.json into chunk/asset summary."""
    with open(stats_path) as f:
        stats = json.load(f)

    assets = []
    for asset in stats.get('assets', []):
        name = asset['name']
        size = asset['size']
        # Only JS and CSS assets
        if not any(name.endswith(ext) for ext in ['.js', '.css', '.mjs']):
            continue
        assets.append({
            'name': name,
            'size': size,
            'size_kb': round(size / 1024, 1),
            'gzip_estimate_kb': round(size / 1024 * 0.3, 1),  # ~30% compression typical
            'chunks': asset.get('chunkNames', []),
            'initial': asset.get('isOverSizeLimit', False),
        })

    # Sort by size desc
    assets.sort(key=lambda x: x['size'], reverse=True)

    # Module analysis — find largest modules
    modules = []
    for module in stats.get('modules', []):
        if module.get('size', 0) > 10 * 1024:  # >10KB only
            modules.append({
                'name': module.get('name', 'unknown'),
                'size': module.get('size', 0),
                'size_kb': round(module.get('size', 0) / 1024, 1),
                'reasons': [r.get('moduleName', '') for r in module.get('reasons', [])[:3]],
            })
    modules.sort(key=lambda x: x['size'], reverse=True)

    return assets, modules[:50]  # top 50 modules

def parse_webpack_chunks(stats_path):
    """Identify chunks and their composition."""
    with open(stats_path) as f:
        stats = json.load(f)

    chunks = []
    for chunk in stats.get('chunks', []):
        chunks.append({
            'id': chunk.get('id'),
            'names': chunk.get('names', []),
            'size': chunk.get('size', 0),
            'size_kb': round(chunk.get('size', 0) / 1024, 1),
            'initial': chunk.get('initial', False),
            'entry': chunk.get('entry', False),
            'module_count': len(chunk.get('modules', [])),
            'files': chunk.get('files', []),
        })

    chunks.sort(key=lambda x: x['size'], reverse=True)
    return chunks

For Vite / CRA (dist/ directory)#

python

import os
from pathlib import Path

def parse_dist_directory(dist_path):
    """Parse build output directory for Vite/CRA/Rollup."""
    js_dir = Path(dist_path)

    # Find all JS files
    js_files = []
    for fpath in js_dir.rglob('*.js'):
        if 'node_modules' in str(fpath):
            continue
        size = fpath.stat().st_size
        js_files.append({
            'name': str(fpath.relative_to(dist_path)),
            'path': str(fpath),
            'size': size,
            'size_kb': round(size / 1024, 1),
            'gzip_estimate_kb': round(size / 1024 * 0.3, 1),
            'is_chunk': 'chunk' in fpath.name.lower() or fpath.parent.name == 'assets',
            'is_vendor': 'vendor' in fpath.name.lower(),
        })

    js_files.sort(key=lambda x: x['size'], reverse=True)

    # CSS files
    css_files = []
    for fpath in js_dir.rglob('*.css'):
        size = fpath.stat().st_size
        css_files.append({
            'name': str(fpath.relative_to(dist_path)),
            'size_kb': round(size / 1024, 1),
        })

    return js_files, css_files

def estimate_gzip(size_bytes):
    """Estimate gzip size. JS typically compresses 65-75%."""
    return round(size_bytes * 0.30 / 1024, 1)

For Next.js (.next/ directory)#

bash

# Next.js provides build-manifest.json and .next/analyze/ if ANALYZE=true
python3 -c "
import json, os
from pathlib import Path

next_dir = Path('.next')
if not next_dir.exists():
    print('No .next/ directory found. Run: next build')
    exit(1)

# Read build-manifest
manifest_path = next_dir / 'build-manifest.json'
if manifest_path.exists():
    manifest = json.loads(manifest_path.read_text())

    # Collect all JS files referenced
    all_files = set()
    for page, files in manifest.get('pages', {}).items():
        for f in files:
            all_files.add(f)

    print(f'Pages: {len(manifest.get(\"pages\", {}))}')
    print(f'Unique JS chunks: {len(all_files)}')

# Read static/chunks/
chunks_dir = next_dir / 'static' / 'chunks'
if chunks_dir.exists():
    chunks = []
    for fpath in chunks_dir.rglob('*.js'):
        size = fpath.stat().st_size
        chunks.append((fpath.name, size))
    chunks.sort(key=lambda x: x[1], reverse=True)

    total = sum(s for _, s in chunks)
    print(f'\\nTotal chunks: {len(chunks)} ({total/1024:.0f} KB)')
    print('\\nTop 10 chunks:')
    for name, size in chunks[:10]:
        print(f'  {name}: {size/1024:.1f} KB (~{size*0.3/1024:.1f} KB gzip)')
"

---

Step 3: Detect Duplicate Dependencies#

python

import re
from pathlib import Path

def find_duplicate_modules(stats_path):
    """Find the same package duplicated across chunks (common with npm hoisting issues)."""
    with open(stats_path) as f:
        stats = json.load(f)

    # Track package versions seen in different chunks
    package_chunks = {}

    for module in stats.get('modules', []):
        name = module.get('name', '')
        # Extract package name from ./node_modules/package/...
        match = re.search(r'node_modules/(@[^/]+/[^/]+|[^/]+)', name)
        if not match:
            continue
        pkg = match.group(1)

        # Which chunks contain this module?
        chunk_ids = module.get('chunks', [])
        if pkg not in package_chunks:
            package_chunks[pkg] = set()
        package_chunks[pkg].update(chunk_ids)

    # Find packages in 3+ chunks (likely duplicated)
    duplicates = {
        pkg: chunks
        for pkg, chunks in package_chunks.items()
        if len(chunks) >= 3
    }

    return sorted(duplicates.items(), key=lambda x: len(x[1]), reverse=True)

def find_heavy_packages(stats_path, threshold_kb=50):
    """Find packages over threshold_kb in the bundle."""
    with open(stats_path) as f:
        stats = json.load(f)

    package_sizes = {}

    for module in stats.get('modules', []):
        name = module.get('name', '')
        size = module.get('size', 0)
        match = re.search(r'node_modules/(@[^/]+/[^/]+|[^/]+)', name)
        if not match:
            continue
        pkg = match.group(1)
        package_sizes[pkg] = package_sizes.get(pkg, 0) + size

    heavy = {
        pkg: size
        for pkg, size in package_sizes.items()
        if size / 1024 > threshold_kb
    }
    return sorted(heavy.items(), key=lambda x: x[1], reverse=True)

---

Step 4: Detect Treeshaking Failures#

python

# Known packages with treeshaking issues + their lightweight alternatives
TREESHAKING_ALERTS = {
    'lodash': {
        'issue': 'lodash CommonJS bundle cannot be treeshaken. Full ~70KB always included.',
        'fix': 'Use lodash-es OR import individual functions: import debounce from "lodash/debounce"',
        'savings': '60-68 KB',
    },
    'moment': {
        'issue': 'moment.js includes all 160+ locale files (~290KB). Treeshaking does NOT work.',
        'fix': 'Replace with date-fns (treeshakeable, ~13KB used) or dayjs (~2KB)',
        'savings': '270-290 KB',
    },
    'antd': {
        'issue': 'antd without babel-plugin-import bundles the entire component library.',
        'fix': 'Add babel-plugin-import or use antd/es/{component} imports',
        'savings': '500+ KB',
    },
    '@mui/material': {
        'issue': 'MUI default import (@mui/material) may bundle unused components.',
        'fix': 'Use named imports: import Button from "@mui/material/Button"',
        'savings': '100-200 KB',
    },
    'rxjs': {
        'issue': 'import { Observable } from "rxjs" bundles the full library if not configured.',
        'fix': 'Use rxjs/operators and ensure sideEffects: false in your bundler config',
        'savings': '50-100 KB',
    },
    'aws-sdk': {
        'issue': 'aws-sdk v2 cannot be treeshaken — it bundles every AWS service.',
        'fix': 'Migrate to @aws-sdk/client-{service} (v3, fully treeshakeable)',
        'savings': '200+ KB',
    },
    'firebase': {
        'issue': 'firebase/app includes all modules unless modular API is used.',
        'fix': 'Use modular imports: import { getAuth } from "firebase/auth"',
        'savings': '100-400 KB',
    },
}

def check_treeshaking_failures(stats_path):
    """Find packages known to have treeshaking issues."""
    with open(stats_path) as f:
        stats = json.load(f)

    found_packages = set()
    for module in stats.get('modules', []):
        name = module.get('name', '')
        for pkg in TREESHAKING_ALERTS:
            if f'node_modules/{pkg}' in name or f'node_modules/{pkg}/' in name:
                found_packages.add(pkg)

    alerts = []
    for pkg in found_packages:
        alerts.append({
            'package': pkg,
            **TREESHAKING_ALERTS[pkg]
        })

    return alerts

---

Step 5: Check Against Budgets#

python

DEFAULT_BUDGETS = {
    'initial_js': 250 * 1024,    # 250 KB initial JS (gzipped target)
    'initial_css': 50 * 1024,     # 50 KB initial CSS
    'any_chunk': 500 * 1024,      # 500 KB max any single chunk
    'total_js': 1000 * 1024,      # 1 MB total JS
}

def check_budgets(assets, custom_budgets=None):
    """Check assets against size budgets."""
    budgets = {**DEFAULT_BUDGETS, **(custom_budgets or {})}
    violations = []

    total_js = sum(a['size'] for a in assets if a['name'].endswith('.js'))
    initial_js = sum(
        a['size'] for a in assets
        if a['name'].endswith('.js') and a.get('initial', False)
    )

    if initial_js > budgets['initial_js']:
        violations.append({
            'type': 'INITIAL_JS',
            'actual_kb': round(initial_js / 1024, 1),
            'budget_kb': round(budgets['initial_js'] / 1024, 1),
            'overage_kb': round((initial_js - budgets['initial_js']) / 1024, 1),
            'severity': 'HIGH',
        })

    for asset in assets:
        if asset['size'] > budgets['any_chunk']:
            violations.append({
                'type': 'CHUNK_SIZE',
                'chunk': asset['name'],
                'actual_kb': asset['size_kb'],
                'budget_kb': round(budgets['any_chunk'] / 1024, 1),
                'overage_kb': round((asset['size'] - budgets['any_chunk']) / 1024, 1),
                'severity': 'MEDIUM',
            })

    if total_js > budgets['total_js']:
        violations.append({
            'type': 'TOTAL_JS',
            'actual_kb': round(total_js / 1024, 1),
            'budget_kb': round(budgets['total_js'] / 1024, 1),
            'overage_kb': round((total_js - budgets['total_js']) / 1024, 1),
            'severity': 'LOW',
        })

    return violations

---

Step 6: Output Report#

markdown

## Bundle Size Audit
Project: my-app | Bundler: webpack 5.89 | Build: production

---

### Size Summary

| Chunk | Raw | Gzip Est. | Type | Status |
|-------|-----|-----------|------|--------|
| main.abc123.js | 312 KB | 94 KB | initial | 🔴 OVER BUDGET |
| vendor.def456.js | 489 KB | 147 KB | initial | 🟠 WARNING |
| dashboard.ghi789.js | 95 KB | 29 KB | async | ✅ OK |
| settings.jkl012.js | 41 KB | 12 KB | async | ✅ OK |

**Total JS: 937 KB (281 KB gzipped)**
**Initial JS: 801 KB — 🔴 EXCEEDS 500 KB budget (301 KB over)**

---

### 🔴 Budget Violations

| Violation | Actual | Budget | Overage | Impact |
|-----------|--------|--------|---------|--------|
| Initial JS | 801 KB | 500 KB | +301 KB | Slow LCP, fails Core Web Vitals |
| main.js chunk | 312 KB | 250 KB | +62 KB | Blocking parse time |

---

### 🔴 Treeshaking Failures (High Impact)

**lodash** — 68 KB that could be 4 KB

Problem: import { debounce } from 'lodash' bundles the entire library (CommonJS) Fix: import debounce from 'lodash/debounce' OR: replace with lodash-es Savings: ~64 KB

text

**moment** — 287 KB that could be 13 KB

Problem: moment.js bundles all 160+ locale files Fix: Replace with date-fns (treeshakeable): import { format, parseISO } from 'date-fns' Savings: ~274 KB

text

---

### 🟠 Duplicate Dependencies (Same Package in 3+ Chunks)

Package Chunk Count Issue react-dom 6 chunks Included in vendor + 5 async chunks lodash 4 chunks Not deduplicated — CommonJS import in multiple files styled-components 3 chunks Multiple versions? Run: npm ls styled-components

text

**Fix:** Ensure these packages are in `optimization.splitChunks.cacheGroups.vendor`:
```js
// webpack.config.js
optimization: {
  splitChunks: {
    cacheGroups: {
      vendor: {
        test: /[\\/]node_modules[\\/](react|react-dom|lodash-es)[\\/]/,
        name: 'vendors',
        chunks: 'all',
      },
    },
  },
},

---

Top 10 Heaviest Modules#

PackageSize% of BundleTreeshakeable?moment287 KB30.6%❌ Nolodash68 KB7.3%⚠️ Only with lodash-es@mui/icons-material61 KB6.5%✅ Yes, if named importsdraft-js58 KB6.2%⚠️ Partialhighlight.js49 KB5.2%✅ Use registerLanguage()...

---

💡 Optimization Recommendations (Ordered by Impact)#

#1 — Replace moment.js → date-fns (~274 KB savings)

bash

npm uninstall moment
npm install date-fns
# Then: find . -name "*.ts" | xargs grep -l "from 'moment'"
# Replace: import { format } from 'date-fns'

#2 — Fix lodash imports (~64 KB savings)

bash

# Find all lodash imports:
grep -r "from 'lodash'" src/ --include="*.ts" --include="*.tsx"
# Change to: import debounce from 'lodash/debounce'
# OR install lodash-es: npm install lodash-es

#3 — Lazy-load dashboard route (~95 KB off initial bundle)

tsx

// Before:
import Dashboard from './Dashboard'
// After:
const Dashboard = React.lazy(() => import('./Dashboard'))

Estimated total savings: 433 KB raw / ~130 KB gzipped After fixes: Initial JS ~368 KB ✅ (under 500 KB budget)

---

CI Fail-Gate#

Add to your CI pipeline to prevent bundle regressions:

bash

# Option 1: bundlesize (npm package)
npx bundlesize
# Requires .bundlesizerc in repo:
# {"files": [{"path": "dist/js/*.js", "maxSize": "250 kB"}]}

# Option 2: size-limit
npx size-limit
# Requires .size-limit.json:
# [{"path": "dist/js/main.*.js", "limit": "250 KB"}]

# Option 3: Pure bash check (no npm package needed)
python3 -c "
import os, sys
from pathlib import Path

budgets = {
    'dist/js/main': 250 * 1024,
    'dist/js/vendor': 500 * 1024,
}

failed = False
for pattern, limit in budgets.items():
    matches = list(Path('.').glob(f'{pattern}*.js'))
    for f in matches:
        size = f.stat().st_size
        if size > limit:
            print(f'FAIL: {f} is {size/1024:.0f} KB (limit: {limit/1024:.0f} KB)')
            failed = True
        else:
            print(f'PASS: {f} is {size/1024:.0f} KB')

sys.exit(1 if failed else 0)
"

Add to .github/workflows/build.yml:

yaml

- name: Check bundle size
  run: python3 scripts/check-bundle-size.py

---

Webpack Bundle Analyzer (Visual)#

For interactive visualization:

bash

# Install once
npm install --save-dev webpack-bundle-analyzer

# Generate report
npx webpack-bundle-analyzer stats.json dist/ --no-open --report report.html
# Opens interactive treemap — look for unexpectedly large node_modules blocks

# Next.js
ANALYZE=true next build
# Opens browser with interactive bundle analysis

text

---

## Quick Mode Output

Bundle Audit: my-app (webpack 5, production)

Initial JS: 801 KB gzip → 🔴 OVER 500 KB budget Total JS: 937 KB (281 KB gzip) Chunks: 4 (2 initial, 2 async)

🔴 moment.js: 287 KB — replace with date-fns → -274 KB 🔴 lodash: 68 KB — fix imports → -64 KB 🟠 @mui/icons-material: 61 KB — use named imports 🟡 6 duplicate react-dom instances — fix splitChunks

Estimated savings: 433 KB → Initial JS drops to ~368 KB ✅ Run /bundle-size-audit --ci-config for CI fail-gate

text

---

## Author

**[Canlah AI](https://canlah.ai)** — Run performance marketing without breaking your brand.

- GitHub: [github.com/PHY041](https://github.com/PHY041)
- All Skills: [clawhub.ai/PHY041](https://clawhub.ai/PHY041)