# 2. Bundle Size Optimization > **Impact:** CRITICAL > **Focus:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint. --- ## Overview This section contains **5 rules** focused on bundle size optimization. --- ## Rule 2.1: Avoid Barrel File Imports **Impact:** CRITICAL **Tags:** bundle, imports, tree-shaking, barrel-files, performance ## Avoid Barrel File Imports Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`). Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts. **Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph. **Incorrect (imports entire library):** ```tsx import { Check, X, Menu } from 'lucide-react' // Loads 1,583 modules, takes ~2.8s extra in dev // Runtime cost: 200-800ms on every cold start import { Button, TextField } from '@mui/material' // Loads 2,225 modules, takes ~4.2s extra in dev ``` **Correct (imports only what you need):** ```tsx import Check from 'lucide-react/dist/esm/icons/check' import X from 'lucide-react/dist/esm/icons/x' import Menu from 'lucide-react/dist/esm/icons/menu' // Loads only 3 modules (~2KB vs ~1MB) import Button from '@mui/material/Button' import TextField from '@mui/material/TextField' // Loads only what you use ``` **Alternative (Next.js 13.5+):** ```js // next.config.js - use optimizePackageImports module.exports = { experimental: { optimizePackageImports: ['lucide-react', '@mui/material'] } } // Then you can keep the ergonomic barrel imports: import { Check, X, Menu } from 'lucide-react' // Automatically transformed to direct imports at build time ``` Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR. Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`. Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js) --- ## Rule 2.2: Conditional Module Loading **Impact:** HIGH **Tags:** bundle, conditional-loading, lazy-loading ## Conditional Module Loading Load large data or modules only when a feature is activated. **Example (lazy-load animation frames):** ```tsx function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch> }) { const [frames, setFrames] = useState(null) useEffect(() => { if (enabled && !frames && typeof window !== 'undefined') { import('./animation-frames.js') .then(mod => setFrames(mod.frames)) .catch(() => setEnabled(false)) } }, [enabled, frames, setEnabled]) if (!frames) return return } ``` The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed. --- ## Rule 2.3: Defer Non-Critical Third-Party Libraries **Impact:** MEDIUM **Tags:** bundle, third-party, analytics, defer ## Defer Non-Critical Third-Party Libraries Analytics, logging, and error tracking don't block user interaction. Load them after hydration. **Incorrect (blocks initial bundle):** ```tsx import { Analytics } from '@vercel/analytics/react' export default function RootLayout({ children }) { return ( {children} ) } ``` **Correct (loads after hydration):** ```tsx import dynamic from 'next/dynamic' const Analytics = dynamic( () => import('@vercel/analytics/react').then(m => m.Analytics), { ssr: false } ) export default function RootLayout({ children }) { return ( {children} ) } ``` --- ## Rule 2.4: Dynamic Imports for Heavy Components **Impact:** CRITICAL **Tags:** bundle, dynamic-import, code-splitting, next-dynamic ## Dynamic Imports for Heavy Components Use `next/dynamic` to lazy-load large components not needed on initial render. **Incorrect (Monaco bundles with main chunk ~300KB):** ```tsx import { MonacoEditor } from './monaco-editor' function CodePanel({ code }: { code: string }) { return } ``` **Correct (Monaco loads on demand):** ```tsx import dynamic from 'next/dynamic' const MonacoEditor = dynamic( () => import('./monaco-editor').then(m => m.MonacoEditor), { ssr: false } ) function CodePanel({ code }: { code: string }) { return } ``` --- ## Rule 2.5: Preload Based on User Intent **Impact:** MEDIUM **Tags:** bundle, preload, user-intent, hover ## Preload Based on User Intent Preload heavy bundles before they're needed to reduce perceived latency. **Example (preload on hover/focus):** ```tsx function EditorButton({ onClick }: { onClick: () => void }) { const preload = () => { if (typeof window !== 'undefined') { void import('./monaco-editor') } } return ( ) } ``` **Example (preload when feature flag is enabled):** ```tsx function FlagsProvider({ children, flags }: Props) { useEffect(() => { if (flags.editorEnabled && typeof window !== 'undefined') { void import('./monaco-editor').then(mod => mod.init()) } }, [flags.editorEnabled]) return {children} } ``` The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.