October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsPC HealthRecommendedCrashes, freezes, slowdowns? Check your PC nowSpot repairable issues before they interrupt work.Check PCOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk5 min

How to Move a React SPA to Next.js App Router Without a Rewrite—and Avoid Hydration Errors

A staged migration lets a React SPA run in a Next.js shell before routes adopt App Router rendering. Learn why hydration mismatches happen and how to fix them without masking the cause.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

You can migrate a production React SPA to the Next.js App Router in stages; you do not have to rewrite the whole application first. Start by getting the existing client-side app running inside a Next.js shell, then move routes and rendering behavior over deliberately. The main adjustment is that App Router changes the initial-render contract: even a Client Component may be rendered on the server before the browser hydrates it, so server and first-client output must agree.

How do I migrate a React SPA to Next.js App Router?

Next.js’s migration guidance for Vite and Create React App recommends first getting the existing application running, then adopting Next.js capabilities incrementally. The Vite guide starts by keeping the app client-side and retaining its existing router; the Create React App guide describes a similar client-only bridge. This lets a team establish a working Next.js shell before changing routing or rendering assumptions across the application.

As an Amazon Associate I earn from qualifying purchases.

  1. Bring up the shell. Embed the existing app as a client-only entry point and keep its current router initially. The Next.js SPA migration guidance uses next/dynamic with { ssr: false } to prevent a selected legacy component from being prerendered.
  2. Inventory one route or feature at a time. As an engineering recommendation, record each slice’s routing behavior, browser API usage, data dependencies, authentication needs, and whether it must render on the server.
  3. Choose the rendering model for that slice. Keep browser-dependent interaction in Client Components; move suitable data and presentation work to Server Components where that fits the route.
  4. Adopt App Router routing and server capabilities incrementally. The migration guide describes moving from React Router to App Router to use file-based routing, automatic code splitting, streaming server rendering, and React Server Components.
  5. Validate each slice before moving the next one. Check the route’s initial HTML and browser behavior, including authentication and any browser-only dependencies, before expanding the migration boundary.

The first step is a bridge, not the final architecture. Keeping the whole legacy app client-only indefinitely preserves its client-heavy behavior; use that stage to reduce migration risk while the team identifies which routes are ready for App Router rendering.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

What changes when App Router renders a page?

App Router pages and layouts are Server Components by default. On an initial page load, Server Components produce a React Server Component payload, which Next.js uses to reconcile the component tree. Client Components are also prerendered to HTML for that initial response, and JavaScript hydrates them in the browser. On later navigations, Client Components render on the client.

#1 Best Overall
Anker USB C Hub, 7in1 Multi-Port USB Adapter, 4K@60Hz USBC to HDMI Splitter
  • Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
  • Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
  • Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
  • Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
  • What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.

That is why 'use client' does not mean “this component never runs during server rendering.” It marks a boundary in the module graph: imports and descendants below it become part of the client bundle. Place the directive around the interaction or browser API that needs it rather than at the top of a broad tree, so unrelated code does not cross the boundary unnecessarily.

The migration guide’s dynamic-import pattern with { ssr: false } is useful when a particular legacy component fundamentally requires the browser. Treat it as a targeted exception, not as a reason to disable prerendering for every route.

Rank #2
Anker USB-C Hub, 5-in-1 USB Hub for Laptops, 4K HDMI Multiport Adapter
  • 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
  • 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
  • Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
  • 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
  • What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.

Why am I getting a hydration error?

A hydration mismatch means the browser’s first render does not match the React tree that produced the prerendered HTML. React cannot reliably attach the expected behavior when those initial outputs diverge. Next.js’s hydration guidance identifies these common causes:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  • Invalid or improperly nested HTML, such as nested paragraph elements or interactive elements nested inside the same kind of interactive element.
  • Render-time environment branches, such as checking typeof window !== 'undefined' and returning different markup on the server and browser.
  • Browser-only APIs, including window or localStorage, used while rendering.
  • Time-dependent output, such as a timestamp generated during render.
  • Browser extensions that change the page’s HTML.
  • Incorrect CSS-in-JS configuration.
  • An edge or CDN layer that modifies the HTML response; the documentation gives Cloudflare Auto Minify as an example.

How do I find the source of a hydration mismatch?

Use the mismatch as a clue to locate the first output that differs, rather than suppressing the warning before identifying its cause. A practical diagnostic order, based on the causes Next.js documents, is:

Rank #3
Anker USB C Hub, 5-in-1 USBC to HDMI Splitter with 4K Display
  • 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
  • Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
  • Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
  • HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
  • What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
  1. Read the mismatch diff and identify the component or text whose initial output diverges.
  2. Inspect the generated markup around that output for invalid nesting or duplicate interactive elements.
  3. Check render logic for environment branches, browser storage, browser globals, clocks, randomness, or other values that can differ between server and browser.
  4. Review the CSS-in-JS integration if the structure appears consistent but generated styles or markup do not.
  5. Inspect the delivered HTML for changes introduced by a browser extension, edge layer, CDN, or HTML-minification setting.

This order is a debugging approach, not a guarantee that every mismatch has one of these causes. The useful starting point is the actual divergent output.

How do I fix a hydration mismatch?

Choose the fix according to what the UI should show on the initial load:

Rank #4
Sale
UGREEN USB C Hub 5 in 1 Multiport USB Adapter 4K HDMI, 100W Power Delivery
  • 5 in 1 Connectivity: The USB C Multiport Adapter is equipped with a 4K HDMI port, a 100W USB C PD port, a 5 Gbps USB A data port, and two 480 Mbps USB A ports
  • The initial content should be identical: make the server render and the browser’s first render use the same input and produce the same markup.
  • The value exists only in the browser: render a stable initial state, then read the browser API or update the display in useEffect. Effects run after hydration, so the browser-only change does not alter the initial tree.
  • The component fundamentally requires the browser: use a targeted dynamic import with ssr: false so that component is not prerendered.
  • A small text difference cannot be avoided: suppressHydrationWarning is a narrow escape hatch. It applies one level deep, and React does not patch mismatched text content when it is set; do not use it to hide wider structural divergence.

Handle clocks according to the intended behavior

Timestamps, relative-time labels, and current-year values can change between prerendering and hydration simply because time has passed. If the value should be cached, evaluated for each request, or updated in the browser, choose a rendering approach that matches that intent. Current Next.js rendering guidance covers cached and request-time rendering as well as browser-side updates. A warning suppression may hide a small unavoidable difference, but it is not a general solution for time-dependent UI.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Should the app remain client-side or adopt App Router capabilities?

Decision area Keep the SPA client-side initially Adopt App Router capabilities incrementally
Migration risk Preserves more existing behavior and is the documented starting point in the migration guides. Introduces server/client boundaries and new routing or data patterns route by route.
Initial rendering Can remain strictly client-side when prerendering is disabled for the legacy app. Server-rendered HTML and hydration become part of the initial-load contract.
Routing The existing router can remain during initial setup. Moving to App Router enables file-based routing and its associated capabilities.
Server features Static export does not provide server-side features. Removing static export permits Next.js server features, subject to deployment setup.
Client JavaScript The legacy app remains client-heavy. Server Components may reduce client-side work, but the result depends on the application.

In the Create React App migration path, output: 'export' produces a static export. It is a deployment and capability choice, not just a migration switch: if the application needs server-side features, the guide says to remove that setting. Decide whether those features are needed before choosing a deployment mode.

Best Value
Anker USB C Hub, USB Extender, 4-in-1 USB Splitter, Computer Accessories
  • Ultra-Fast Data Transfers: Experience the power of 5Gbps transfer speeds with this USB hub and sync data in seconds, making file transfers a breeze.
  • Long Cable, Endless Convenience: Say goodbye to short and restrictive cables. This USB hub comes with a 2 ft long cable, giving you the freedom to connect your devices exactly where you need them.
  • Sleek and Compact: Measuring just 4.2 × 1.2 × 0.4 inches, carry the USB hub in your pocket or laptop bag and connect effortlessly wherever you go.
  • Instant Connectivity: Anker USB-C data hub offers a true plug-and-play experience, instantly connecting your devices and enabling seamless file transfers.
  • What You Get: 2ft Anker USB-C Data Hub (4-in-1, 5Gbps) , welcome guide, our worry-free 18-month warranty, and friendly customer service.

App Router offers capabilities, not a guaranteed performance result. The migration and component guidance does not provide a controlled before-and-after benchmark for a particular production SPA, so bundle-size reductions, faster loads, or other gains should be measured in the application rather than assumed.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Crashes, No Sound, or Screen Glitches?Free driver scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.