audit-bundle-size

name	audit-bundle-size
description	Analyse and shrink JavaScript bundle size for any web app. Auto-detects bundler (Vite, Webpack, Rollup, esbuild, Next.js, Turbopack). Runs a production build with bundle analysis, identifies the largest chunks, duplicate dependencies, non-tree-shakeable imports, and missing code-splitting or lazy-load boundaries. Researches current best practices via Firecrawl and Context7. Maps every finding to a specific file and import with before/after size estimates. Generic across any framework. Use when asked to "reduce bundle size", "analyse bundle", "tree shaking", "lazy loading", "code splitting", "slow initial load", "large JS", "chunk size", "build performance", "LCP caused by JS", "why is the bundle so big", or "first load JS too large".
license	MIT

audit-bundle-size — Find and Eliminate Bundle Bloat

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. This skill finds exactly what is bloating it and tells you how to fix each item.

---

Phase 0: Detect bundler and existing setup

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

Vite / Rollup

If rollup-plugin-visualizer is not installed:

npm install --save-dev rollup-plugin-visualizer

Add temporarily to vite.config.ts:

import { visualizer } from 'rollup-plugin-visualizer';
// in plugins array:
visualizer({ open: false, filename: 'dist/bundle-report.html', gzipSize: true })

Then build:

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

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

This requires @next/bundle-analyzer in next.config.*:

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:

npx source-map-explorer 'dist/**/*.js' --html dist/bundle-report.html

Or for a quick size summary:

find dist -name '*.js' | xargs ls -lh | sort -k5 -hr | head -20
find dist -name '*.css' | xargs ls -lh | sort -k5 -hr | head -5

---

Phase 2: Parse the results — find the problems

For each chunk or entry point, record:

Chunk	Raw size	Gzip size	Largest contributors
main / page.js	...	...	[dep@version, ...]
vendor	...	...	[dep@version, ...]

Red flags to look for

Problem	Signal	Impact
One giant vendor chunk	Single vendor.js > 200 KB gzip	High — blocks first paint
Duplicate dependency	Same library listed twice (e.g. lodash + lodash-es)	Medium
Full library import	import _ from 'lodash' (imports everything)	High
Missing lazy routes	All routes in one bundle	High
Unused package	Large dep that appears in bundle but only 1–2 exports used	High
Dev-only dep in prod bundle	faker, debug, chalk in client code	Medium
Moment.js	67 KB gzip with all locales	Medium — replace with date-fns or dayjs
Material UI / Ant Design full import	Full icon library loaded	High
react-icons full package	50+ MB raw, huge when not tree-shaken	High

---

Phase 3: Research current alternatives

For the largest offenders, check current alternatives:

firecrawl:firecrawl_search
{
  "query": "replace <package-name> smaller alternative bundle size 2026",
  "limit": 3,
  "sources": [{ "type": "web" }]
}

Common swaps (research to confirm current state):

• moment → date-fns or dayjs (much smaller, tree-shakeable)
• lodash → native JS or lodash-es with named imports
• Full icon set → per-icon imports or SVG sprites
• axios → native fetch (if browser targets allow)
• Large chart libs → check if a lighter alternative exists for the charts used

---

Phase 4: Fix — ordered by size saved

Fix 1: Named imports (tree shaking)

// Before — pulls in the whole library
import _ from 'lodash';
import { BellIcon } from '@heroicons/react/24/solid'; // only needs Bell

// After — only the export you need
import debounce from 'lodash/debounce';
import { BellIcon } from '@heroicons/react/24/solid'; // already correct for heroicons v2

For icon libraries that do not tree-shake well, use per-icon deep imports or an SVG sprite sheet.

Fix 2: Dynamic imports for routes (code splitting)

Next.js App Router — code-splits by route automatically. If you have heavy components inside a page, split them:

import dynamic from 'next/dynamic';
const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
  loading: () => <ChartSkeleton />,
  ssr: false, // if it uses browser-only APIs
});

Vite / React Router:

const LazyPage = React.lazy(() => import('./pages/LazyPage'));
// Wrap in <Suspense fallback={<PageSkeleton />}>

SvelteKit — routes are code-split by default. For heavy components:

{#await import('./HeavyComponent.svelte') then { default: Component }}
  <Component />
{/await}

Fix 3: Replace or remove over-sized dependencies

Follow the research from Phase 3. For any replacement:

1. Read the new library's docs via Context7 or Firecrawl before touching code.
2. Make the swap in one file, run npm run build, compare sizes before merging everywhere.

Fix 4: Bundle splitting configuration

Vite — split large deps into their own cacheable chunks:

build: {
  rollupOptions: {
    output: {
      manualChunks: {
        'react-vendor': ['react', 'react-dom'],
        'router': ['react-router-dom'],
        'charts': ['recharts'], // or whatever charting lib
      },
    },
  },
},

Next.js — configure splitChunks in next.config.* only if the default chunking is creating sub-optimal splits. Prefer dynamic() over manual config.

Fix 5: Remove dev-only packages from the client bundle

Any package that should only run server-side or in tests must not be imported from client-side code. Move to devDependencies and verify it disappears from the bundle after rebuild.

---

Phase 5: Measure the improvement

After fixes, rebuild and re-run Phase 1:

Before: First Load JS = X KB gzip
After:  First Load JS = Y KB gzip
Saved:  Z KB (N%)

For each route (Next.js build output shows this), confirm the numbers improved. Run a quick Playwright check to confirm the app still works:

PW="npx --yes @playwright/cli@latest"
$PW -s=bundle-check open --headed "<app-url>"    # then `goto` each key route
$PW -s=bundle-check snapshot                      # no blank screen or error
$PW -s=bundle-check console                       # no new errors

---

Quick-reference: size targets (2026)

Asset	Target	Review if
Initial JS (gzip)	< 100 KB	> 250 KB
Route chunk (gzip)	< 50 KB	> 150 KB
CSS total (gzip)	< 20 KB	> 50 KB
Largest single image	< 200 KB	> 500 KB
Total page weight	< 500 KB	> 1.5 MB