Migrate Next.js to TanStack Start: Practical Guide with Real Examples

Railway moved 200+ routes off Next.js onto TanStack Start in two pull requests. Their builds dropped from 10+ minutes to under 2 minutes. Inngest made a similar move shortly after. TanStack Start hit v1.0 in March 2026, and a clear pattern emerged: teams running client-heavy, real-time apps are migrating because Next.js's server-first App Router doesn't add value for their use case.

The common thread is friction. These teams fight the framework more than they benefit from it. Server Components add complexity to dashboards that are 95% client-side. Webpack builds crawl when Vite would finish in seconds. Vercel-specific optimizations don't help when you deploy to Railway, Fly, or bare Docker.

This guide combines official TanStack docs with practical lessons from production migrations. It covers the two-PR strategy Railway used, route conversion patterns, and the trade-offs you should weigh before committing. TanStack Start pairs naturally with a Hono-based API layer, so if your backend is already decoupled, the move is even smoother.

Railway's engineering team summarized it well: their app is "overwhelmingly client-side, a rich stateful interface, websockets everywhere." Server Components added nothing. The App Router's file conventions felt like overhead for routes that immediately hydrate into fully interactive client code.

If that description matches your app, keep reading. If your site depends on static generation, edge middleware, or server-side rendering for SEO on every page, Next.js is still the better tool.

A framework migration is a cost with no user-visible payoff. Nobody opens your app and notices that the router changed. The only reasons that justify the spend are compounding ones: build minutes you pay on every commit, a rendering model you keep fighting, or a hosting arrangement you cannot escape.

Skip the migration if your app is mostly static content or marketing pages. Static generation, incremental revalidation, and the crawler behaviour around them are genuinely good in Next.js, and you would be rebuilding all of it by hand for no ranking benefit.

Skip it if Server Components are load-bearing in your codebase. If you stream data from async components, keep heavy dependencies off the client with server-only imports, or rely on partial prerendering, you are using the exact features TanStack Start deliberately does not replicate.

Skip it if your team is small and mid-roadmap. A framework swap on a five-person team is weeks of work plus a long tail of unfamiliar bugs in code you thought you understood. A slow build is annoying. Missing a quarter is worse.

Skip it if your only complaint is your hosting bill. You can self-host Next.js on a container platform today and keep every other decision intact. Price that option honestly before you commit to a rewrite.

For a greenfield project, the scaffolding command gets you running in seconds:

For an existing Vite project (or when migrating from Next.js), install the packages manually:

Configure Vite with the TanStack Start plugin and Nitro server settings:

Railway's approach splits the migration into two independent, reviewable pull requests. Each PR ships on its own. If something breaks, you know exactly which change caused it.

The two-PR strategy assumes you can convert every route in one sitting. That works for an app with thirty routes and a team that can pause feature work for a week. It does not work for an app with three hundred routes, and it does not work when the migration has to happen alongside a roadmap.

The alternative is to run both apps at once and shift traffic across gradually. A reverse proxy sits in front of both deployments and decides, per path prefix, which app answers the request. You migrate a section at a time, ship it, and move the prefix.

Three things have to be true before this works. Sessions must be shared, which usually means both apps read the same cookie on the same parent domain and validate it against the same session store. Shared UI has to be extracted into a package both apps import, or you accept temporary duplication. And the boundary between the two apps has to sit where a full page load is acceptable, because navigation across it is a hard reload, not a client-side transition.

Routing logic that currently lives in Next.js middleware has to move up into the proxy, since middleware only runs for requests the Next.js app still owns. Moving Next.js middleware logic into a proxy layer walks through that shift in detail, and the reasoning applies directly here.

Be honest about the cost of this mode: two builds, two deploy pipelines, two dependency trees, and two places to fix any bug that spans both. Set a deadline for decommissioning the old app when you start, and treat a stalled parallel run as a failed migration rather than a stable architecture.

TanStack Router uses a $ prefix for dynamic segments instead of Next.js's [bracket] syntax. The file structure maps closely, but data loading and layouts work differently.

Next.js uses bracket notation for dynamic segments. TanStack Router uses a dollar-sign prefix:

Next.js App Router uses async Server Components or getServerSideProps (Pages Router). TanStack Start uses a loader function on the route definition. The loader runs before the component renders and its return value is available via useLoaderData().

Next.js uses co-located layout.tsx files. TanStack Router uses parent route files that render an <Outlet /> for child content:

Type safety is TanStack Router's headline feature and the clearest thing you gain from this migration. Route paths, path params, and search params are all inferred from a generated route tree, so a link to a route that does not exist is a compile error instead of a 404 you find in production.

In Next.js, a link target is just a string. Nothing checks that the path exists or that you interpolated the params it needs. Rename a directory under app/ and every link pointing at it breaks silently until someone clicks it.

Search params get the same treatment, and this is where the gap with Next.js is widest. A route declares a validateSearch function that parses the raw query object into a typed shape, and components read it back with a typed hook. Invalid or missing values are handled once, at the route, instead of being re-parsed and re-defaulted in every component.

Schema library adapters exist for validators like Zod and Valibot if you prefer to declare the shape once and reuse it, but a plain function works and adds no dependency.

The cost of all this typing is a code generation step. The router writes a route tree file that has to stay in sync with your route files, so it runs in dev, in CI, and before every build. On very large route trees, editor responsiveness can suffer because the inferred types are genuinely large. Both are real, and both are usually worth it.

Most of the conversion is a rename. A handful of App Router conventions have no one-to-one counterpart, and those are where migration estimates go wrong. Map them before you start so nothing surprises you halfway through.

Anything you built around a Next.js-specific rendering quirk also needs rechecking. A no-flash dark mode, for example, depends on a blocking inline script placed before hydration, and that script moves into your root route document shell instead of the Next.js root layout. Our guide on avoiding the dark mode flash in Next.js explains the mechanism you need to reproduce.

The other reliable source of breakage is navigation hooks. Every call to a Next.js router hook, every read of the current pathname, and every search param read has a TanStack equivalent, but the shapes differ. Grep for them before the swap rather than discovering them one failing page at a time.

This is the deepest difference between the two frameworks, and the one that decides whether the migration is mechanical or a rewrite. Next.js gives you a server-first component model with an opinionated caching layer built into fetch. TanStack Start gives you client components, route loaders, and explicit remote procedure calls.

There is no Server Component equivalent in TanStack Start. If your components fetch data by being async and awaiting inside the render, that pattern does not survive the move. The data fetch goes up into the route loader and the component reads the result. For a dashboard that hydrates immediately anyway, this is a small change. For a content site built around streaming server output, it is a redesign.

Next.js patches the global fetch to deduplicate and cache requests, with per-call options controlling revalidation. The defaults have changed between major versions, which is precisely the complaint many teams have: caching behaviour is implicit and version-dependent.

TanStack Start does not patch fetch. Nothing is cached unless you say so. Route loaders have their own staleness settings, so a loader result can be reused across navigations for a configured window and refetched in the background afterwards. Beyond that, caching is a library decision, and in practice that library is TanStack Query.

The pattern that works best is to combine them. The loader primes the query cache so server rendering and the first paint have data, and the component subscribes to the same query so refetching, mutations, and invalidation behave normally afterwards.

Next.js server actions are async functions marked with a directive that the framework turns into a POST endpoint, wired into form submissions and its own cache invalidation helpers. TanStack Start's equivalent is the server function, created with createServerFn. The concept is the same: code that only ever runs on the server, callable from the client with types preserved across the boundary.

The differences are in what the framework does for you afterwards. There is no revalidatePath or tag-based cache invalidation to call, because there is no framework-managed cache to invalidate. You invalidate the router or the query cache yourself, which is more code and considerably easier to reason about.

Environment variables change shape too. The NEXT_PUBLIC_ convention disappears and Vite's prefixed import.meta.env variables take over, with the same build-time inlining behaviour and the same risk of leaking a secret into the client bundle if you prefix the wrong one. Our breakdown of Next.js environment variables covers that build-time versus runtime distinction, and the mental model transfers directly to Vite.

Do the audit during the swap: list every variable, mark each one server-only or public, and confirm after the first build that no server-only value appears in the client output. Grep the built assets for a known secret value. It takes a minute and catches the one mistake that matters.

The next/image component does two things: lazy loading and image optimization (resizing, format conversion, CDN caching). You need to replace both. Two solid options:

If you deploy behind Cloudflare, Fastly, or any CDN with image transformation, use a plain <img> tag with the CDN's URL pattern. The CDN handles resizing and format negotiation (WebP/AVIF).

@unpic/react is a framework-agnostic image component that generates responsive srcset attributes and handles lazy loading. It works with any image CDN.

TanStack Start uses Nitro as its server layer. Nitro handles redirects, security headers, caching rules, and deployment adapters. Railway reported consolidating "500+ redirects, security headers, and caching rules into one place" after the migration.

Here is a typical conversion from Next.js config to Nitro route rules. Nitro's routeRules consolidate caching configuration into a single, declarative format.

Next.js concentrates request-time logic in a single middleware file that runs before rendering for every matching path. Auth redirects, locale detection, A/B bucketing, and header rewriting all end up there, which makes it powerful and also makes it the file nobody wants to touch.

TanStack Start splits that work across three places, and knowing which one to use is most of the migration effort for auth.

The common auth setup is a pathless layout route that every protected page nests under. The gate is written once, and the type system enforces that protected routes have an authenticated user in context.

That warning applies to Next.js middleware too, but the failure mode is quieter there because middleware always runs on the server. Moving the same logic into a route hook that also runs client-side is exactly the kind of change that turns a working auth model into a broken one without a single test failing.

One practical consequence: your session lookup now happens in two contexts. Write a single function that resolves the current user from a request, call it from your root route context on the server, and call it again inside every server function. Duplicated verification is the point, not a smell.

Every migration has trade-offs. Be honest about what you lose before committing:

Your build commands and output directories change. Update your CI pipeline accordingly.

Deploying to a workers runtime rather than a Node server changes the rules on both frameworks in the same way: no Node built-ins, Web APIs only, a hard CPU budget per request, and a bundle size ceiling. What changes is where you configure it.

In Next.js you opt individual routes into the edge runtime and rely on an adapter to package the output. In TanStack Start you select a deployment preset and the server build targets that platform, so the choice is made once for the whole app rather than per route.

That is simpler, and also less flexible. Mixed deployments, where a handful of latency-sensitive routes run at the edge and everything else runs on a Node server, are natural in Next.js and awkward in TanStack Start. If you rely on that split today, prototype it before committing.

The reason PR 1 exists is that framework-agnostic components have framework-agnostic tests. Component tests written against plain props and plain DOM keep passing across the swap. Tests that mock Next.js navigation modules do not, and you will rewrite each one.

Router-dependent components need a router in the test, and TanStack Router supports this directly with an in-memory history. You build a small test router, render your component inside it, and assert as normal. Write that helper once and reuse it across the suite rather than reconstructing it per file.

End-to-end tests are the real safety net here, because they are the only layer that does not care which framework serves the response. A Playwright suite written against the Next.js app should pass unchanged against the TanStack Start app. If it does not, you found a genuine behavioural difference, which is exactly what you want the suite to tell you.

For anything with organic traffic, add a URL parity check on top of the functional tests. Crawl your sitemap before the migration and store the status code, canonical URL, and title for every page. Replay that list against the new build and diff it. Silent 404s and dropped canonicals are the most expensive mistakes a migration can ship, and they are trivially preventable.

The migration pays off when the framework is actively costing you something measurable and the thing it costs you is not going away. It does not pay off as a preference, and it never pays off as a rewrite of working code.

Whichever way you decide, the App Router model is worth understanding properly before you reject it, if only because it comes up constantly in Next.js interview questions and in architecture reviews. A migration decision made from a clear understanding of both models will survive review. One made from frustration usually will not.