struxadotcloud/struxa

public

initial commitd4cb9e15 months ago182 lines · 4.7 KB

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