lifecycle/migrate-from-react-router

Migrate from React Router v7 to TanStack Router

This is a step-by-step migration checklist. Each check covers one conversion task. Complete them in order.

CRITICAL: If your UI is blank after migration, open the console. Errors like "cannot use useNavigate outside of context" mean React Router imports remain alongside TanStack Router imports. Uninstall react-router (and react-router-dom if present) to surface them as TypeScript errors.

CRITICAL: TanStack Router uses to + params for navigation, NOT template literal paths. Never interpolate params into the to string.

NOTE: React Router v7 recommends importing from react-router (not react-router-dom). The react-router-dom package still exists but just re-exports from react-router. Check for imports from both.

Pre-Migration

• Create a migration branch

git checkout -b migrate-to-tanstack-router

• Install TanStack Router alongside React Router temporarily

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

• Configure bundler plugin (Vite example)

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
    react(),
  ],
})

• Create routes directory

mkdir src/routes

Route Definitions

• Create root route

React Router: <BrowserRouter> or createBrowserRouter([{ element: <Layout />, children: [...] }])

TanStack Router: src/routes/__root.tsx

// src/routes/__root.tsx
import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

export const Route = createRootRoute({
  component: () => (
    <>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/about">About</Link>
      </nav>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

• Create router instance with type registration

// src/main.tsx
import { StrictMode } from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

const rootElement = document.getElementById('root')!
if (!rootElement.innerHTML) {
  ReactDOM.createRoot(rootElement).render(
    <StrictMode>
      <RouterProvider router={router} />
    </StrictMode>,
  )
}

• Convert each route file to createFileRoute

React Router:

// Defined in route config array
{ path: '/posts', element: <Posts />, loader: postsLoader }

TanStack Router:

// src/routes/posts.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  loader: async () => {
    const posts = await fetchPosts()
    return { posts }
  },
  component: PostsPage,
})

function PostsPage() {
  const { posts } = Route.useLoaderData()
  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>{p.title}</li>
      ))}
    </ul>
  )
}

• Convert dynamic routes

React Router: /posts/:postId (colon syntax)

TanStack Router: /posts/$postId (dollar syntax)

// src/routes/posts/$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    return { post }
  },
  component: PostPage,
})

function PostPage() {
  const { post } = Route.useLoaderData()
  return <article>{post.title}</article>
}

Navigation

• Convert all <Link> components

React Router:

import { Link } from 'react-router'
;<Link to={`/posts/${postId}`}>View Post</Link>

TanStack Router:

import { Link } from '@tanstack/react-router'
;<Link to="/posts/$postId" params={{ postId }}>
  View Post
</Link>

Key differences:

• to is a route path pattern, NOT an interpolated string

• params is a separate prop with typed values

• Active styling: use activeProps={{ className: 'font-bold' }} or data-status="active" attribute for CSS

• Convert all useNavigate calls

React Router:

import { useNavigate } from 'react-router'
const navigate = useNavigate()
navigate(`/posts/${postId}`)

TanStack Router:

import { useNavigate } from '@tanstack/react-router'
const navigate = useNavigate()
navigate({ to: '/posts/$postId', params: { postId } })

Search Params

• Replace useSearchParams with validateSearch + useSearch

React Router:

import { useSearchParams } from 'react-router'

function Posts() {
  const [searchParams, setSearchParams] = useSearchParams()
  const page = Number(searchParams.get('page')) || 1

  const goToPage = (p: number) => setSearchParams({ page: String(p) })
}

TanStack Router:

// In the route definition:
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

export const Route = createFileRoute('/posts')({
  validateSearch: z.object({
    page: z.number().default(1).catch(1),
  }),
  component: Posts,
})

// In the component:
import { useNavigate } from '@tanstack/react-router'

function Posts() {
  const { page } = Route.useSearch()
  const navigate = useNavigate({ from: '/posts' })

  const goToPage = (p: number) => {
    navigate({ search: (prev) => ({ ...prev, page: p }) })
  }
}

Key differences:

• Search params are validated and typed at the route level
• useSearch() returns typed objects, not URLSearchParams
• Update with function form to preserve other params

Path Params

• Update useParams with from property

React Router:

import { useParams } from 'react-router'
const { postId } = useParams()

TanStack Router:

import { useParams } from '@tanstack/react-router'
const { postId } = useParams({ from: '/posts/$postId' })

Or from within the route component:

const { postId } = Route.useParams()

useLocation — Common Pitfall

• Replace useLocation with specific hooks

React Router's useLocation is heavily used, and TanStack Router has a hook with the same name — but they are NOT equivalent. TanStack Router's useLocation() returns the router's current location, which during pending navigations may differ from what's currently rendered. Most React Router useLocation usage should be replaced with more specific hooks. See #3110.

Replace based on what you actually need:

// React Router
import { useLocation } from 'react-router'
const location = useLocation()

// ❌ DON'T just swap to TanStack Router's useLocation — it's the "live" URL
import { useLocation } from '@tanstack/react-router'

// ✅ DO use the specific hook for what you need:
import {
  useMatch,
  useMatches,
  useParams,
  useSearch,
} from '@tanstack/react-router'

// Current route match (replaces most useLocation().pathname usage)
const match = useMatch({ from: '/posts/$postId' })

// All active matches (replaces useLocation for breadcrumbs/analytics)
const matches = useMatches()

// Path params (replaces useLocation + manual parsing)
const { postId } = useParams({ from: '/posts/$postId' })

// Search params (replaces useLocation().search parsing)
const { page } = useSearch({ from: '/posts' })

Outlet

• Replace React Router Outlet with TanStack Router Outlet

The API is identical — just change the import:

// Before
import { Outlet } from 'react-router'

// After
import { Outlet } from '@tanstack/react-router'

Loaders

• Convert React Router loaders

React Router (v7):

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

export default function Post() {
  const { post } = useLoaderData()
  return <div>{post.title}</div>
}

TanStack Router:

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    return { post }
  },
  component: Post,
})

function Post() {
  const { post } = Route.useLoaderData()
  return <div>{post.title}</div>
}

Key differences:

• Loader is a route option, not a separate export
• useLoaderData() is called via Route.useLoaderData() (or useLoaderData({ from }))
• TanStack Router loaders run on the CLIENT by default (not server-only)
• No json() wrapper needed — return plain objects

Code Splitting

• Convert lazy route imports — with autoCodeSplitting: true in the plugin config, this is automatic. For manual splitting, use .lazy.tsx files:

// src/routes/lazy-page.lazy.tsx
import { createLazyFileRoute } from '@tanstack/react-router'

export const Route = createLazyFileRoute('/lazy-page')({
  component: () => <div>Lazy loaded</div>,
})

Cleanup

• Remove React Router and verify

npm uninstall react-router react-router-dom
grep -r "from 'react-router" src/  # find stale imports
npx tsc --noEmit                    # verify clean build

• Test all routes — verify rendering, navigation (incl. back/forward), search params, dynamic params, and loaders

Common Mistakes

1. HIGH: Leaving React Router imports alongside TanStack Router

Both libraries export Link, useNavigate, Outlet, etc. Leftover React Router imports cause "cannot use useNavigate outside of context" errors because the wrong context provider is used.

// WRONG — mixed imports
import { Link } from '@tanstack/react-router'
import { useNavigate } from 'react-router' // <- still React Router!

// CORRECT — all from TanStack Router
import { Link, useNavigate } from '@tanstack/react-router'

Fix: Uninstall react-router/react-router-dom completely. TypeScript will flag every stale import.

2. HIGH: Using React Router useSearchParams pattern

// WRONG — React Router pattern, returns URLSearchParams
const [searchParams, setSearchParams] = useSearchParams()
const page = Number(searchParams.get('page'))

// CORRECT — TanStack Router pattern, returns typed object
// Route definition:
validateSearch:
  z.object({
    page: z.number().default(1).catch(1),
  }),

// Component:
const { page } = Route.useSearch()
// page is already typed as number — no casting needed

3. HIGH: Interpolating params into to string

// WRONG — React Router habit
<Link to={`/posts/${postId}`}>Post</Link>

// CORRECT — TanStack Router: path pattern + params prop
<Link to="/posts/$postId" params={{ postId }}>Post</Link>

4. MEDIUM: Using :param syntax instead of $param

React Router: /posts/:postId
TanStack Router: /posts/$postId

File naming also uses $: src/routes/posts/$postId.tsx

Quick Reference: API Mapping