Bundlers — What They Actually Do

// This ships one function, not the whole library
import { debounce } from 'lodash-es'

// This ships all of lodash — CommonJS cannot be statically analysed
const _ = require('lodash')
import _ from 'lodash'

// Requirements for tree shaking to work:
//   1. ES modules (static import/export), not CommonJS
//   2. No side effects at module top level
//   3. "sideEffects": false in the package's package.json

// A top-level side effect defeats it:
// utils.js
export function unused() { }
window.analytics = init()      // runs on import, so the module is kept

// Barrel files are the usual culprit in application code:
// components/index.ts re-exporting 80 components means importing
// one can pull the graph of all 80 into the analysis.
import { Button } from '@/components'        // risky
import { Button } from '@/components/Button' // predictable

// Static — always in the initial bundle
import { Editor } from './Editor'

// Dynamic — its own chunk, fetched when this line runs
const { Editor } = await import('./Editor')

// In React
const Editor = lazy(() => import('./Editor'))
<Suspense fallback={<Skeleton />}><Editor /></Suspense>

// In Next
const Editor = dynamic(() => import('./Editor'), {
  ssr: false,               // for anything that touches window
  loading: () => <Skeleton />,
})

// What is worth splitting: the code editor, chart libraries,
// markdown renderers, PDF generators, admin-only routes, modals.
// Anything heavy that most visitors never open.

// Routes split automatically in Next — each page is its own chunk.

# Next
ANALYZE=true npm run build          # with @next/bundle-analyzer

# Any project
npx source-map-explorer 'dist/**/*.js'
npx vite-bundle-visualizer

// The usual offenders and their fixes:
//   moment           -> date-fns, or Intl
//   lodash           -> lodash-es, or a native method
//   an icon set      -> import individual icons, never the barrel
//   a chart library  -> dynamic import
//   a duplicate dep  -> two versions of react in the tree; npm ls react

// Budgets, so a regression is caught in review rather than in a
// support ticket: fail CI if the initial chunk exceeds a threshold.