Migrating a Real Next.js App

Step 1 — Install & create the router

Install TanStack Router + the Vite plugin (or your bundler's equivalent). The plugin watches your routes/ folder and generates routeTree.gen.ts — the typed route tree that powers all the type safety from Lessons 5–7.

npm install @tanstack/react-router
npm install -D @tanstack/router-plugin vite

Wire the plugin in vite.config.ts, then create your router in a router.ts file pointing at the generated route tree. You can run Next.js and TanStack side-by-side during migration — they don't have to swap in one shot.

Step 2 — Map your route tree on paper first

Before touching files, draw the route tree. For each Next.js route:

1. Does it own a URL segment? If yes → directory or $param.
2. Is it structural chrome? If yes → pathless layout (_name).
3. Is it purely organizational? If yes → group ((name)).

Translate Next.js conventions to TanStack (recap from Lessons 1–4):

Step 3 — Convert one route, end-to-end

Pick the smallest leaf route in your app — a static page like /about. Convert it fully:

1. Create routes/about/index.tsx
2. createFileRoute('/about')({ component: AboutPage })
3. Move the JSX from page.tsx into the component
4. Verify it renders at /about via the TanStack router

One green route proves the pipeline. Resist converting everything at once.

Step 4 — Migrate data fetching route-by-route

For each route with data (Lesson 7):

• App Router async component → route loader + Route.useLoaderData() in the component
• useEffect + fetch → same; delete the effect, the loading state, the error state
• SWR / React Query → can stay; loaders are optional. Use loaders for route-critical data, keep React Query for mutations + cross-route caches

For params-dependent routes, declare loader: ({ params, signal }) => .... For search-dependent routes, add validateSearch + loaderDeps.

Step 5 — Rewire navigation (Lesson 5)

Find every <Link href="..."> and router.push(...). Replace:

// Before (Next.js)
<Link href={`/posts/${post.id}`}>{post.title}</Link>
router.push(`/posts/${newId}`)

// After (TanStack)
<Link to="/posts/$postId" params={{ postId: post.id }}>{post.title}</Link>
navigate({ to: '/posts/$postId', params: { postId: newId } })

The conversion is mechanical but catches bugs: any broken string interpolation surfaces as a TypeScript error now.

Step 6 — Promote UI state to search params (Lesson 6)

For each useState that holds shareable UI state — filters, pagination, modal-open, selected tab — ask: should this be in the URL? If yes:

1. Add a Zod validateSearch schema with .catch() fallbacks
2. Read via Route.useSearch()
3. Write via navigate({ search: prev => ({ ...prev, ... }) })
4. Delete the useState

This is the highest-leverage refactor — shareable URLs and natural back-button behavior for free.