1# Bundling
2 
3Fix common bundling issues with third-party packages.
4 
5## Server-Incompatible Packages
6 
7Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
8 
9### Error Signs
10 
11```
12ReferenceError: window is not defined
13ReferenceError: document is not defined
14ReferenceError: localStorage is not defined
15Module not found: Can't resolve 'fs'
16```
17 
18### Solution 1: Mark as Client-Only
19 
20If the package is only needed on client:
21 
22```tsx
23// Bad: Fails - package uses window
24import SomeChart from 'some-chart-library'
25 
26export default function Page() {
27  return <SomeChart />
28}
29 
30// Good: Use dynamic import with ssr: false
31import dynamic from 'next/dynamic'
32 
33const SomeChart = dynamic(() => import('some-chart-library'), {
34  ssr: false,
35})
36 
37export default function Page() {
38  return <SomeChart />
39}
40```
41 
42### Solution 2: Externalize from Server Bundle
43 
44For packages that should run on server but have bundling issues:
45 
46```js
47// next.config.js
48module.exports = {
49  serverExternalPackages: ['problematic-package'],
50}
51```
52 
53Use this for:
54- Packages with native bindings (sharp, bcrypt)
55- Packages that don't bundle well (some ORMs)
56- Packages with circular dependencies
57 
58### Solution 3: Client Component Wrapper
59 
60Wrap the entire usage in a client component:
61 
62```tsx
63// components/ChartWrapper.tsx
64'use client'
65 
66import { Chart } from 'chart-library'
67 
68export function ChartWrapper(props) {
69  return <Chart {...props} />
70}
71 
72// app/page.tsx (server component)
73import { ChartWrapper } from '@/components/ChartWrapper'
74 
75export default function Page() {
76  return <ChartWrapper data={data} />
77}
78```
79 
80## CSS Imports
81 
82Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
83 
84```tsx
85// Bad: Manual link tag
86<link rel="stylesheet" href="/styles.css" />
87 
88// Good: Import CSS
89import './styles.css'
90 
91// Good: CSS Modules
92import styles from './Button.module.css'
93```
94 
95## Polyfills
96 
97Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
98 
99Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
100 
101```tsx
102// Bad: Redundant polyfills
103<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />
104 
105// Good: Next.js includes these automatically
106```
107 
108## ESM/CommonJS Issues
109 
110### Error Signs
111 
112```
113SyntaxError: Cannot use import statement outside a module
114Error: require() of ES Module
115Module not found: ESM packages need to be imported
116```
117 
118### Solution: Transpile Package
119 
120```js
121// next.config.js
122module.exports = {
123  transpilePackages: ['some-esm-package', 'another-package'],
124}
125```
126 
127## Common Problematic Packages
128 
129| Package | Issue | Solution |
130|---------|-------|----------|
131| `sharp` | Native bindings | `serverExternalPackages: ['sharp']` |
132| `bcrypt` | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs` |
133| `canvas` | Native bindings | `serverExternalPackages: ['canvas']` |
134| `recharts` | Uses window | `dynamic(() => import('recharts'), { ssr: false })` |
135| `react-quill` | Uses document | `dynamic(() => import('react-quill'), { ssr: false })` |
136| `mapbox-gl` | Uses window | `dynamic(() => import('mapbox-gl'), { ssr: false })` |
137| `monaco-editor` | Uses window | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
138| `lottie-web` | Uses document | `dynamic(() => import('lottie-react'), { ssr: false })` |
139 
140## Bundle Analysis
141 
142Analyze bundle size with the built-in analyzer (Next.js 16.1+):
143 
144```bash
145next experimental-analyze
146```
147 
148This opens an interactive UI to:
149- Filter by route, environment (client/server), and type
150- Inspect module sizes and import chains
151- View treemap visualization
152 
153Save output for comparison:
154 
155```bash
156next experimental-analyze --output
157# Output saved to .next/diagnostics/analyze
158```
159 
160Reference: https://nextjs.org/docs/app/guides/package-bundling
161 
162## Migrating from Webpack to Turbopack
163 
164Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
165 
166```js
167// next.config.js
168module.exports = {
169  // Good: Works with Turbopack
170  serverExternalPackages: ['package'],
171  transpilePackages: ['package'],
172 
173  // Bad: Webpack-only - migrate away from this
174  webpack: (config) => {
175    // custom webpack config
176  },
177}
178```
179 
180Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack
181