Vite To Nextjs App Router

Vite to Next.js (App Router) Migration

A migration skill, not a vibe. Every step below is a decision I made (and defended) on a production migration serving +500k users, so the agent reproduces a route that already shipped rather than improvising.

When to use

• "Migrate this Vite app to Next.js"
• "Switch to App Router / file-based routing"
• "Add SSR / server components to my React SPA"
• "Move off react-router onto Next.js routing"

If the app is a marketing site with no auth and no client state, this is overkill. This skill earns its keep on authenticated, stateful SPAs with real routes and API consumption.

Iron rules

1. Never a big-bang rewrite. Migrate route-by-route behind a feature boundary. The old app keeps serving until a route is verified.
2. TanStack Query stays. Do not rip it out for "pure" server components on day one. Keep the cache for client-side mutations; add Server Components only where the payoff (SEO, initial paint, reduced client JS) is concrete.
3. Auth/session bridges, doesn't fork. Keycloak (or whatever IdP) session is shared; do not build a parallel auth flow in Next.
4. Validation lives in Zod, shared. One schema source for client + server + form. Do not hand-roll validators per layer.

Migration order (do it in this sequence)

0. Audit before touching code

• Map every route in react-router (including nested + dynamic params + redirects).
• List every useEffect data fetch. These are Server Component candidates.
• List every mutation / optimistic UI. These stay client.
• Identify the auth boundary: where is the session read? (Keycloak token, cookie, context?)

1. Scaffold Next.js alongside, not over

• npx create-next-app@latest with App Router, TypeScript, the same styling lib (Material UI / Tailwind / Shadcn).
• Do not delete the Vite app yet. Run Next on a different port; reverse-proxy or feature-flag route-by-route.

2. Routing first, components second

• Translate react-router paths to App Router file conventions:
  • /users/:id becomes app/users/[id]/page.tsx
  • layout routes become layout.tsx
  • index becomes page.tsx
  • * becomes not-found.tsx
• Keep the exact same URL surface. Renaming URLs is a separate, deliberate task, not a side effect of migration.

3. Auth/session bridge

• Read the existing session mechanism (Keycloak: keycloak-js on the client, or a server-side session cookie).
• For Keycloak: keep the client adapter for the transition; expose the token via a provider so migrated routes can read it. Move to server-side session verification on protected routes once the route is cut over.
• Do not invent a new auth flow. If the old app reads window.keycloak, the new route reads the same source until cutover.

4. Data fetching: Server Components where it pays

• For each useEffect fetch from step 0, ask: does this need client interactivity after load?
  • No -> convert to an async Server Component. Pass typed data to a client child for interactivity.
  • Yes (mutations, optimistic) -> keep useQuery in a "use client" component.
• Keep TanStack Query for all client-side cache + mutations. The migration is not the moment to also change your data library.

5. Forms and validation

• react-hook-form + zod move as-is into "use client" components.
• Define Zod schemas in a shared lib/schemas/ so Server Components and Client Components import the same source.
• Server Actions become the eventual target for submits, but only after the route is stable with the existing API. Don't couple the migration to an API rewrite.

6. Styling

• Material UI / Tailwind / Shadcn: carry over directly. Material UI's SSR works in App Router; register the AppRouterCacheProvider in the root layout.
• Modular CSS files: import paths change, semantics don't.

7. Cut over one route at a time

• For each route: build the Next version, verify against the Vite version (same data, same URL, same auth), then flip the proxy/flag.
• Keep the Vite route reachable for one release as a rollback. Only delete it once the Next route has served real traffic without incident.

8. Cleanup

• Remove the Vite app, react-router, and the old proxy once every route is cutover.
• Delete dead useEffect fetches that became Server Components.
• Update CI to build only Next.

Anti-patterns to refuse

• "Let's also redesign the API while we migrate." -> No. One change at a time.
• "Replace TanStack Query with RSC fetch everywhere." -> No. Mutations and optimistic UI stay client.
• "Rename the URLs to be cleaner." -> No. Separate task, separate PR.
• "Big-bang: delete Vite, ship Next in one release." -> No. Route-by-route, with rollback.

Matriz de Progreso y Corte de Rutas (docs/migration-matrix.md)

Mantener el seguimiento exhaustivo de la migración utilizando la matriz de corte ruta por ruta:

Verification (what "done" looks like per route)

• Diff de respuesta / HTML: Validar que la misma URL devuelva la misma información comparando el payload localmente:

  # Diff de HTML o response entre Vite (puerto 5173) y Next.js (puerto 3000):
  diff -u <(curl -s http://localhost:5173/ruta) <(curl -s http://localhost:3000/ruta)
  

• Same auth state is respected (logged-in user stays logged-in).
• No regression in client interactivity for mutation-heavy routes.

Provenance

Codified from the Mendoza por Mí migration (Necta, 2025): Vite + React Router SPA serving +500k users migrated to Next.js App Router, route-by-route, with Keycloak auth and TanStack Query retained for mutations. The decisions above are the ones that shipped, not a generic checklist.