Migrate a React SPA to Next.js without a big-bang rewrite

A common starting point is a B2B platform with a public catalogue and an authenticated product area. The React frontend uses Vite and React Router against a stable Node.js API. Services run in Docker, and product delivery continues throughout the migration.

Replacing Vite is not an objective in itself. The public-page response currently contains little more than an empty shell. Titles, content, links and sometimes the canonical URL appear only after the application has loaded and several API requests have completed. Those requests may form waterfalls, while routing, session handling and global state remain tightly coupled to the SPA. A long-lived rewrite branch would merely defer the integration risk until cutover.

Google can run JavaScript, but crawling, rendering and indexing are still separate stages. When a SPA returns an empty container, a crawler must download the application, start React and wait for data before it can see the content. Not every crawler has that capability.

In the App Router, pages and layouts are React Server Components by default. They can load data close to its source, render content on the server and contribute to the pre-rendered HTML. Their code is not added to the browser bundle. Only filters, buttons and other interactive UI need to be Client Components.

Next.js does not receive a special ranking signal. The SEO benefit comes from controlling the response: a meaningful HTTP status, title, description, canonical URL, main content and internal links can all be present before client-side JavaScript runs.

import type { Metadata } from 'next'
import { notFound } from 'next/navigation'
import { cache } from 'react'

import { readResource } from '@/lib/resources'
import { ShareButton } from './share-button'

type Props = { params: Promise<{ slug: string }> }

const getResource = cache(readResource)

export async function generateMetadata({
    params,
}: Props): Promise<Metadata> {
    const resource = await getResource((await params).slug)
    if (!resource) return {}

    return {
        title: resource.seoTitle,
        description: resource.excerpt,
        alternates: {
            canonical: `/resources/${resource.slug}`,
        },
        openGraph: {
            title: resource.seoTitle,
            description: resource.excerpt,
        },
    }
}

export default async function Page({ params }: Props) {
    const resource = await getResource((await params).slug)
    if (!resource) notFound()

    return (
        <article>
            <h1>{resource.title}</h1>
            <div>{resource.content}</div>
            <ShareButton />
        </article>
    )
}

The Metadata API covers page metadata and social sharing. The sitemap.ts and robots.ts file conventions and Open Graph images keep this configuration close to the route. JSON-LD remains explicit and must describe the content users can actually see.

The assessment starts with routes. For each one, the team records traffic, interactivity, browser dependencies, SEO value and the product cost of a regression. It then checks the HTML received without JavaScript, status codes, metadata, internal links, structured data, cookies, deep links, VITE_* variables, analytics, the service worker and global styles.

The baseline covers error rate, LCP, INP, CLS, TTFB, JavaScript volume and network calls. For public pages, it also includes impressions, discovered URLs, crawl errors and the HTML reported by Search Console. These signals detect regressions; they do not promise an uplift before the first route ships.

Next.js serves migrated routes while the SPA continues to serve everything else. The Node.js API remains the source of truth for business behaviour. A Next.js fallback forwards routes that Next.js does not yet serve. To restore an already migrated route without rebuilding the application, the reverse proxy must be able to route that URL back to the SPA.

import type { NextConfig } from 'next'

const legacyOrigin = process.env.LEGACY_FRONTEND_ORIGIN

if (!legacyOrigin) {
    throw new Error('LEGACY_FRONTEND_ORIGIN is required')
}

const nextConfig = {
    output: 'standalone',
    async rewrites() {
        return {
            fallback: [{
                source: '/:path*',
                destination: legacyOrigin + '/:path*',
            }],
        }
    },
} satisfies NextConfig

export default nextConfig

Fallback rewrites run after Next.js routes, so this configuration supports incremental adoption but cannot restore a route that already exists in Next.js. The rollback rule belongs in the ingress or reverse proxy, and the team tests it with query strings, Vite assets, deep links and error pages.

1. 1

   Write down the invariants

   URLs, cookies, API contracts, analytics events and redirects form one Definition of Done for both applications.
2. 2

   Deploy the shell

   The Next.js service starts in Docker, connects to the API, exposes a health check and emits logs before it receives user traffic.
3. 3

   Migrate one vertical slice

   Migrate one public page end to end, including data, initial HTML, metadata, JSON-LD, internal links, errors, analytics, tests and rollback.
4. 4

   Keep client-side JavaScript for interactive UI only

   Pages and layouts stay on the server by default. The “use client” directive covers only search, filters or buttons that need state and browser APIs.
5. 5

   Cut over and observe

   The route goes live with monitoring, a tested proxy rule and a named rollback owner. If it regresses, the proxy sends only that route back to the SPA.

React Server Components do not make every page static. Editorial content may be pre-rendered and revalidated, while fresh data can still be rendered on demand. In both cases, the initial response needs an appropriate status code, metadata and main content.

The output: 'standalone' mode produces the deployment directory used by the Docker image. The public and .next/static directories must also be copied. With multiple replicas, caching and revalidation need an explicit coordination strategy.

The consultant pairs with the team on the first slice, and short ADRs capture the decisions that affect later routes. Each review asks four questions: where does this code run, what data is cached, what HTML and JavaScript reach the browser, and how would we route traffic back to the legacy SPA?

After cutover, the team inspects the response in Search Console and compares error rate, field Core Web Vitals, latency, transferred JavaScript and API-call volume. Impressions and indexing need a longer observation window. A single Lighthouse score does not validate the migration, and rollback is tested before the legacy route is removed.

Once the SPA no longer serves user traffic, the team removes fallback rules and Vite assets, unregisters the service worker and clears its caches, then deletes the old dependencies and Docker image. Coexistence is a migration stage, not the target architecture.

Next.js does not guarantee search rankings. It restores control over the HTML, metadata and JavaScript sent to the browser. An incremental migration validates that benefit one route at a time without betting the whole production system.