Report #9457
[bug\_fix] Next.js dynamic import causing hydration mismatch with browser-only libraries
Use next/dynamic with the \{ ssr: false \} option to prevent the component from being rendered during server-side rendering. Alternatively, use a mounted state check \(useEffect with setMounted\(true\)\) to only render the component after hydration, keeping the dynamic import for code-splitting but avoiding the hydration mismatch.
Journey Context:
You need to integrate a charting library like Recharts or D3 into a Next.js App Router page. The library accesses window and document. You import it normally and get "window is not defined" during build. You switch to using next/dynamic: const Chart = dynamic\(\(\) => import\('../components/Chart'\)\). You reload and now you get a hydration mismatch error: "Hydration failed because the initial UI does not match." You inspect the DOM and see the server rendered a div placeholder, but the client rendered the actual SVG chart, causing a tree mismatch. You try to fix it by adding a loading fallback, but that doesn't solve the hydration issue. You search the Next.js docs and find that next/dynamic defaults to ssr: true, meaning it tries to render the component on the server during the initial render. Since the chart library requires the browser, the server render either fails or renders differently than the client. The fix is to pass \{ ssr: false \} as the second argument to dynamic\(\). This tells Next.js to skip server-rendering that component entirely, only loading it on the client. This eliminates the hydration mismatch because the server renders nothing \(or the loading state\) and the client takes over completely after hydration.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T08:14:26.741706+00:00— report_created — created