Nextjs Rsc To React Router V8 Migration

nextjs-rsc-to-react-router-v8-migration

Migrate a multi-locale Next.js RSC / App-Router site to React Router v8 so its SSR HTML is CDN-cacheable at the edge. The migration is not a "framework swap" — it is a cache-frame swap. RSC payload is per-request, per-cookie, per-header, and Vercel-only. RR8 gives you plain SSR HTML that Cloudflare can hold for hours if the response varies only by URL. The whole workflow enforces that invariant.

The gain is real only when locale × page multiplies the bill. On a 17-locale marketing surface with dynamic OG, sitemaps, and marketplace pages, RSC payload cost dominates even under ISR. RR8's plain SSR wins because the CDN can bypass origin for anonymous traffic.

When to use

• Multi-locale (≥ 5 locales) SSR site whose RSC payload / ISR bill is a measurable cost driver.
• Anonymous traffic dominates — the CDN can serve the same HTML to everyone in the same locale.
• Team can absorb a phased cut: leave 3–5 URL groups on the legacy Next site behind for later ports (privacy/terms, growth pages, …).
• CDN in front is Cloudflare (or any CDN that honours Cloudflare-CDN-Cache-Control). Vercel-CDN-only stacks lose the point — Vercel CDN cannot cache HTML that varies by cookie.

When NOT to use

• Small site — RSC payload cost is a rounding error; keep Next.
• Heavy Server Components composition — RR8 has no RSC. If your product surface is dashboard-shaped and you rely on RSC boundaries for streaming/composition, this trade is a loss.
• SSR that legitimately varies per-user (dashboards, auth-gated pages) — CDN caching is moot; the migration only pays for anonymous surfaces.
• Vercel CDN is the only CDN and you cannot bring Cloudflare in front.

Scope

• Marketing / blog / marketplace-style SSR pages, multi-locale.
• Loader-driven data fetch, most of which can move to client-side after hydration.
• CSS-in-JS with SSR extraction (antd-style / emotion / stitches).
• Middleware doing locale redirects, UA detection, geo hints.

Files

• references/cache-control-profiles.md — the seven header profiles (HOME, PAGE, SITEMAP, DYNAMIC_OG, BADGE, STATIC_LONG, FEED, NO_STORE) and the 3-tier header rule.
• references/loader-triage.md — decision matrix for splitting a loader between SSR-critical, prerender-safe, and client-fetch.
• references/theme-ssr-recipe.md — next-themes + inline head script + cacheable /theme-vars.css compile-time recipe, incl. antd v6 cssVar override gotcha.

Workflow

[1]  Frame the migration as an edge-cache swap, not a framework swap
[2]  Stand up RR8 shell alongside legacy site (separate Vercel project)
[3]  Move src/app tree to RR8 route config; keep Next-like FS shape
[4]  Kill UA / geo / cookie-derived SSR variance
[5]  Split loader traffic: SSR-critical vs prerender-safe vs client-fetch
[6]  Restage theme SSR: next-themes + inline head script + /theme-vars.css
[7]  Rebuild middleware: Vercel Routing Middleware + root-loader mirror
[8]  Prerender the static surface (blog, about, docs) at build time
[9]  Decouple route-FS from feature-FS: routes/ = entry only
[10] Compile-time-ify runtime CSS via vite virtual modules
[11] Land 3-tier Cache-Control headers per route profile
[12] Cut traffic; leave the legacy Next site on for un-ported URL groups

Per-step notes

[1] Frame it as a cache swap. Before touching code, write down the per-locale RSC / ISR bill and the target cf-cache-status: HIT ratio. If the answer is "we cannot let CDN cache HTML because we personalise X", the migration will not pay — either fix X (move to CSR) or stop.

[3] Route FS shape. Do not flatten. Keep a Next-like nested tree (routes/blog/[slug]/page.tsx, routes/api/geo/route.ts, routes/docs/[...slugs]/page.tsx) even though RR8 uses explicit routes.ts. Every page module registers twice via a localized() helper: locale-less path (/blog/:slug, default en) and prefixed path (/:locale/blog/:slug). One module, two ids.

[4] Kill SSR variance. The single rule: SSR output must vary only by URL. No UA sniffing, no cookie-derived theme, no per-request geo. Move device detection to CSS media queries (or a matchMedia-based useIsMobile hook that agrees with those media queries), theme to next-themes + inline <head> script, geo to a client-side useGeo that calls /api/geo. If you leave one cookie-varying loader on a public route, that route stops caching.

[5] Loader triage. RR8 loaders re-run on client navigation as .data requests, which the CDN will not cache. Three buckets:

• SSR-critical, prerender-safe (locale/route info, static blog metadata) → loader, and prerender at build.
• SSR-critical, dynamic (fresh market/API data needed for first paint) → loader, but keep the SSR HTML cacheable by CDN because the URL fully identifies the result.
• Post-hydration (marketplace lists, star counts, changelog tails) → strip from the loader; fetch client-side after hydration. This is the biggest CDN win — the .data round-trip disappears.

See references/loader-triage.md.

[6] Theme SSR. Ship both palettes (light + dark) as one cacheable stylesheet /theme-vars.css?v=<hash>, linked render-blocking from the root. An inline <head> script sets html[data-theme] from localStorage before first paint. antd v6 in cssVar mode re-declares --ant-* on any element carrying .ant-app / [class*='css-var-'], so scope the palette blocks to those selectors too, else the light literals shadow your dark palette on hydration. SSR CSS must be theme-agnostic: rewrite every appearance-dependent token to a var(--ant-*) reference so first paint picks the correct colour.

See references/theme-ssr-recipe.md.

[7] Middleware split. Legacy middleware.ts becomes two things:

• src/middleware.ts (Vercel Routing Middleware, web-standard Request/Response, next()/rewrite() from @vercel/functions/middleware) — runs in prod before the CDN cache. Handles locale redirects, AI-tool redirects, NEXT_LOCALE cookie.
• Root loader mirror — Vercel Routing Middleware does not run under bun run dev. Mirror the same locale / redirect logic in the root loader so dev matches prod.
• Vercel's middleware compiler cannot resolve tsconfig path aliases. Pre-bundle src/middleware.ts (rolldown via vite's dep tree) into a self-contained /middleware.js in a build:middleware step.

[8] Prerender. RR8 supports build-time prerender. Ship the entire static surface (default-locale blog, docs, about, changelog) as HTML on disk; the CDN turns every one into a permanent HIT. Non-default locales stay dynamic if the bill allows; prerendering all 17 locales adds build minutes and repo weight.

[9] Route/feature FS. routes/ holds only route entry files (page.tsx, route.ts, Client.tsx, layout.tsx, [param] segments, not-found.tsx, pending-loading.tsx). Every feature implementation the route imports lives in src/features/<domain>/. Sub-features under [param] drop the brackets (coding/[agent] → features/coding/agent).

[10] Compile-time-ify runtime CSS. Any CSS generated in route.ts at request time (theme vars, antd static rules) becomes a vite virtual module baked at build. The route serves the module contents with a hash query and a long-lived Cache-Control. Zero runtime cost, infinite CDN cache.

[11] 3-tier Cache-Control. Every response ships three headers:

• Cache-Control (browser)
• Cloudflare-CDN-Cache-Control (Cloudflare)
• Vercel-CDN-Cache-Control: no-store (bypass Vercel CDN — deliberate)

Because Cloudflare owns cache, Vercel CDN is a pass-through. Seven profiles (HOME, PAGE, SITEMAP, DYNAMIC_OG, BADGE, STATIC_LONG, FEED, NO_STORE) — see references/cache-control-profiles.md. Apply per route via export const headers = () => toHeaderMap(PAGE).

[12] Phased cut. Do not port every URL group at once. Leave privacy/terms, growth pages, im-landing, icon marketplace on the legacy Next site behind their existing URLs; port them one PR at a time using the frozen legacy repo as reference. The traffic split lives at the DNS / edge layer (see the sibling skill dokploy-traefik-traffic-split for the SPA-asset trap that breaks naive weighted splits).

Common pitfalls

Rules

• SSR varies only by URL. No exceptions on public routes. If a variance is required (auth, session), that route is NO_STORE.
• Skill first, cut second. Do not remove the legacy site until the new site's cf-cache-status HIT ratio matches the target.
• Every route declares a Cache-Control profile. No implicit defaults; explicit headers export per route.
• Middleware logic mirrors in the root loader. Two homes, one behaviour.

Verification

• bun run build produces /middleware.js with no unresolved aliases (grep for @/ in the emitted bundle → zero hits).
• bun run start serves the production build.
• curl -I https://<host>/ twice: second response has cf-cache-status: HIT and vercel-cache: MISS (Vercel is pass-through by design).
• No public route emits Set-Cookie in its SSR response.
• curl -I https://<host>/blog/<slug>.data returns a body but is not cached at the CDN (cf-cache-status: BYPASS or MISS); that route was demoted to a client fetch instead if it appears on hot paths.
• First paint shows the correct theme (light or dark) with no white → dark repaint. Test with prefers-color-scheme: dark and with theme=dark in localStorage.
• NEXT_LOCALE=zh cookie on /blog/foo triggers 307 to /zh/blog/foo — both in dev (root-loader mirror) and prod (Vercel Routing Middleware).
• build/client/blog/**/*.html exists for the prerendered default locale.
• Every route module exports headers and each profile in references/cache-control-profiles.md appears at least once in the emitted route table.
• Legacy site still serves the un-ported URL groups; traffic split config committed alongside the migration cut.