TanStack Router vs React Router v7: File-Based Routing Compared

Why This Comparison Matters Right Now

React routing hit a weird inflection point in 2024–2025. React Router v6 had already fragmented its own community by shipping the Remix-flavored v6.4 data APIs as a surprise mid-minor. Then Remix merged into React Router v7 and shipped in late 2024, turning what used to be a simple client-side router into a full-stack framework. Meanwhile TanStack Router v1 quietly went stable and started earning serious adoption as the type-safe alternative.

So now you've got two very different things both calling themselves 'file-based routers'. One is a full-stack framework with server rendering baked in. The other is a client-first router obsessed with TypeScript correctness. Choosing wrong means either fighting your framework or shipping a bundle that's far heavier than it needs to be.

This isn't a benchmark post. It's a practical walkthrough of how each router actually works — file conventions, type safety, data loading, search params — so you can make a real decision for your next project.

File-Based Routing: Conventions Side by Side

Both routers let you skip manually defining a route tree in code. Drop a file, get a route. But the conventions are meaningfully different. React Router v7 uses a routes.ts config file as its source of truth even in file-based mode — you're still explicitly listing routes, just with helpers that point to files. TanStack Router's file-based mode, enabled via @tanstack/router-plugin, generates a routeTree.gen.ts file automatically by scanning a routes/ directory. You never touch the generated file.

Worth noting: TanStack Router's flat-file convention uses dots as path separators. A file named routes/blog.post.$id.tsx maps to /blog/post/:id. React Router v7 uses a directory tree, which feels more familiar coming from Next.js but produces deeper folder nesting faster.

# TanStack Router (flat file convention)
routes/
  __root.tsx          # root layout
  index.tsx           # /
  blog.index.tsx      # /blog
  blog.$slug.tsx      # /blog/:slug
  settings.tsx        # /settings (layout route)
  settings.profile.tsx
  settings.billing.tsx

# React Router v7 (directory convention)
app/
  routes/
    _index.tsx        # /
    blog._index.tsx   # /blog
    blog.$slug.tsx    # /blog/:slug
    settings.tsx      # /settings (layout)
    settings/
      profile.tsx
      billing.tsx

Honestly, the flat-file approach in TanStack Router grows better. When you've got 40 routes, a flat list sorted alphabetically is way easier to scan than a deeply nested directory tree. That said, React Router v7's convention will feel more natural if you're migrating from Remix or Next.js.

Type Safety: Where TanStack Router Actually Wins

This is the headline difference. TanStack Router's entire design philosophy is 100% type-safe routing — path params, search params, router context, loader data, all of it. The generated routeTree.gen.ts gives the router complete knowledge of every route at compile time. You get autocomplete on to props, type errors when you mistype a param name, and typed search params with built-in validation.

// TanStack Router — fully typed navigate call
import { useNavigate } from '@tanstack/react-router'

function GoToPost({ id }: { id: number }) {
  const navigate = useNavigate()

  return (
    <button
      onClick={() =>
        navigate({
          to: '/blog/$slug',   // autocompleted
          params: { slug: String(id) },  // type-checked
          search: { page: 1 },  // type-checked against route schema
        })
      }
    >
      Read post
    </button>
  )
}

React Router v7 has made TypeScript improvements — it generates route types via a typegen command — but the coverage is narrower. Search params are still basically URLSearchParams, meaning you're doing your own parsing and validation manually or reaching for a library like nuqs. Path params are typed from your route file names, which is good, but loader return types require more explicit annotation.

In practice, if you're building something where search params carry real application state (filters, pagination, modals), TanStack Router's search param validation via Zod or Valibot is genuinely game-changing. You define a schema once and every navigate() call is validated at both compile time and runtime. That's 80px of boilerplate you'd otherwise write yourself on every filtered list page.

One more thing — TanStack Router's Link component will give you a TypeScript error if you pass a to prop that doesn't match any route in your tree. React Router v7 accepts any string. Small difference, huge impact over a large codebase.

Data Loading: Loaders, Suspense, and Prefetching

React Router v7 inherits Remix's loader model. You export a loader function from your route file, it runs on the server (or client in SPA mode), and the component gets the data via useLoaderData(). It's clean. It works. The mental model of 'colocate your data requirement with the route' is solid, and parallel loading across nested routes has been React Router's killer feature since v6.4.

// React Router v7 route with loader
import { useLoaderData } from 'react-router'

export async function loader({ params }: LoaderFunctionArgs) {
  const post = await fetchPost(params.slug)
  return { post }
}

export default function BlogPost() {
  const { post } = useLoaderData<typeof loader>()
  return <article>{post.title}</article>
}

TanStack Router uses a loader function too, but it's designed for client-side execution and integrates tightly with TanStack Query. You can return data directly from the loader, but the recommended pattern is to kick off a query prefetch in the loader and let your component read from the cache via useSuspenseQuery. This means your router and server state cache are always in sync.

// TanStack Router + TanStack Query
import { createFileRoute } from '@tanstack/react-router'
import { useSuspenseQuery } from '@tanstack/react-query'
import { postQueryOptions } from '../queries/posts'

export const Route = createFileRoute('/blog/$slug')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(postQueryOptions(params.slug)),

  component: BlogPost,
})

function BlogPost() {
  const { slug } = Route.useParams()
  const { data: post } = useSuspenseQuery(postQueryOptions(slug))
  return <article>{post.title}</article>
}

Quick aside: if you're already using TanStack Query for server state management, TanStack Router's ensureQueryData pattern means zero duplicate fetching. The loader warms the cache, the component reads from it — no waterfalls, no prop drilling, no loader-versus-cache drift. React Router v7 doesn't have this built-in. You'd add TanStack Query alongside it, but then your loader data and query cache can diverge on stale data.

Search Params: The Often-Ignored Differentiator

Look, search params are where most routers quietly fail you. Raw URLSearchParams are strings. Your app wants booleans, numbers, arrays, and enums. Every project eventually ships a useTypedSearchParams hook that's slightly broken in a different way. Both routers try to fix this, but with different energy.

TanStack Router makes you define a validateSearch function on every route that needs search params. You can use Zod, Valibot, or write a plain validator. The validated output is what useSearch() returns — fully typed, runtime-safe, with default values applied automatically. Stale or invalid params don't crash your component; they get replaced with defaults.

import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

const searchSchema = z.object({
  page: z.number().int().min(1).default(1),
  q: z.string().default(''),
  tag: z.string().optional(),
})

export const Route = createFileRoute('/blog/')({
  validateSearch: searchSchema,
  component: BlogIndex,
})

function BlogIndex() {
  const { page, q, tag } = Route.useSearch()
  // page is number, q is string, tag is string | undefined
  // No casting. No NaN. No surprises.
}

React Router v7 leaves search params as a you-figure-it-out problem. You can use useSearchParams() from the React Router API, but it returns a URLSearchParams object. Validation, coercion, and defaults are all yours to build. The nuqs library fills this gap nicely, but you're adding another dependency to work around a gap in the router.

If your UI has any kind of filter panel, table pagination, or shareable URLs with state — and most production apps do — TanStack Router's search param validation saves you real time. It's not a gimmick.

When to Pick React Router v7

React Router v7 makes the most sense when you want server-side rendering with progressive enhancement and you're not already deep in the TanStack ecosystem. It's a full-stack framework now — you get server loaders, server actions, streaming, and deployment adapters for Cloudflare, Vercel, Node, and others out of the box. For teams coming from Remix, upgrading to React Router v7 is the obvious path.

The ecosystem is also massive. Almost every React tutorial, blog post, and library integration guide since 2017 assumes React Router. Your junior devs will already know it. Your Stack Overflow results will be dense with answers. That network effect is real and shouldn't be dismissed.

One more thing — if you need server actions and form mutations with optimistic UI, React Router v7's action + useFetcher pattern is mature and well-documented. TanStack Router doesn't ship server actions at all (that's TanStack Start's territory, which is a separate framework layered on top). If you want a single dependency that handles routing + server communication, React Router v7 wins.

When to Pick TanStack Router

Choose TanStack Router when type safety and client-side complexity are your primary concerns. If you're building a dashboard, an admin panel, a design tool, or anything with rich interactive state that lives in the URL, TanStack Router's type-safe search params and deep TanStack Query integration will pay for themselves within the first week. You can build something like a component library explorer with complex filter and search state and never write a single parseInt() on a URL param.

It's also the better pick if you're running a pure SPA — no SSR, hosted on a CDN, talking to an external API. React Router v7's full-stack features don't help you there, and you'd be shipping their server runtime for zero benefit. TanStack Router's bundle is smaller and more focused for that use case.

Worth noting: TanStack Start (the framework layer on top of TanStack Router) is reaching maturity as of mid-2026. If you want SSR with TanStack Router, that's the path. It's still newer than React Router v7's equivalent, so weigh ecosystem maturity against type-safety benefits for your specific team.

Both routers work great with a solid component library. If you're building out UI around either one, browse Empire UI's components — they're framework-agnostic React and pair with either router. The gradient generator and box shadow generator are also worth bookmarking while you're getting your design tokens sorted.

FAQ

Read next