Skip to main content
skill CX Codex

migrate-from-react-router — Claude Code skill for TanStack Router migration

migrate-from-react-router is a Claude Code skill with a step-by-step checklist for moving from React Router v7 to TanStack Router, covering routes, navigation, and search params.

MIT 188 installs ★ 15,341 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TanStack/router --skill migrate-from-react-router -a claude-code
Open on GitHub

What migrate-from-react-router does

The skill splits the migration into individual checks you work through in order. It starts with a git branch and package installs, then walks through each API replacement.

Two things trip people up. TanStack Router expects a path pattern in to plus a separate params prop — template literal paths will break. And if the UI renders blank after migration, leftover React Router imports are usually the cause. Uninstalling react-router (and react-router-dom if present) turns those leftovers into TypeScript errors.

For search params, useSearchParams becomes a validateSearch zod schema on the route plus useSearch in the component. useParams needs a from argument to infer types. The skill assumes router-core and react-router are present, and you'll need zod for validation.

What it helps with

  • convert route definitions from colon to dollar syntax
  • replace useSearchParams with a typed validateSearch schema
  • rewrite Link and useNavigate calls to use to + params
  • track down React Router imports left after migration
  • set up the Vite plugin for routeTree generation

Example prompts for the agent

  • Start migrating this project from React Router v7 to TanStack Router using the skill steps
  • Show me how to rewrite useSearchParams as validateSearch with zod
  • Why is my screen blank after migration with a useNavigate context error?

How to install migrate-from-react-router

1Skills CLI (Vercel)

npx skills add TanStack/router --skill migrate-from-react-router -a claude-code

2Manually: put the files in place

~/.claude/skills/migrate-from-react-router/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/migrate-from-react-router/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about migrate-from-react-router

How do I install migrate-from-react-router in Claude Code?

Run npx skills add TanStack/router --skill migrate-from-react-router -a claude-code. The skill lands at ~/.claude/skills/migrate-from-react-router/SKILL.md.

What does this skill do?

It provides an ordered migration checklist from React Router v7 to TanStack Router: route conversion, Link and useNavigate differences, useSearchParams to validateSearch + useSearch, useParams with from, Outlet replacement, loader conversion, and code splitting.

What does the skill require?

You need @tanstack/react-router and @tanstack/react-router-devtools, the @tanstack/router-plugin dev dependency, and zod for search param validation. React Router should stay installed during the migration.

Source text

SKILL.md · MIT
---
name: migrate-from-react-router
description: >-
  Step-by-step migration from React Router v7 to TanStack Router:
  route definition conversion, Link/useNavigate API differences,
  useSearchParams to validateSearch + useSearch, useParams with from,
  Outlet replacement, loader conversion, code splitting differences.
metadata:
  type: lifecycle
  library: tanstack-router
  library_version: '1.166.2'
requires:
  - router-core
  - react-router
sources:
  - TanStack/router:docs/router/how-to/migrate-from-react-router.md
  - TanStack/router:docs/router/installation/migrate-from-react-router.md
---

# 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**

```bash
git checkout -b migrate-to-tanstack-router
```

- [ ] **Install TanStack Router alongside React Router temporarily**

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

- [ ] **Configure bundler plugin (Vite example)**

```ts
// 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**

```bash
mkdir src/routes
```

## Route Definitions

- [ ] **Create root route**

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

TanStack Router: `src/routes/__root.tsx`

```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**

```tsx
// 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:

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

TanStack Router:

```tsx
// 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)

```tsx
// 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:

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

TanStack Router:

```tsx
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:

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

TanStack Router:

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

## Search Params

- [ ] **Replace `useSearchParams` with `validateSearch` + `useSearch`**

React Router:

```tsx
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:

```tsx
// 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:

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

TanStack Router:

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

Or from within the route component:

```tsx
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](https://github.com/TanStack/router/issues/3110).

Replace based on what you actually need:

```tsx
// 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:

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

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

## Loaders

- [ ] **Convert React Router loaders**

React Router (v7):

```tsx
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:

```tsx
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:

```tsx
// 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**

```bash
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.

```tsx
// 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

```tsx
// 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

```tsx
// 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`

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

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

## Quick Reference: API Mapping

| React Router v7              | TanStack Router                                      |
| ---------------------------- | ---------------------------------------------------- |
| `<BrowserRouter>`            | `<RouterProvider router={router} />`                 |
| `<Routes>` / `<Route>`       | File-based: `src/routes/*.tsx`                       |
| `<Link to="/path">`          | `<Link to="/path">`                                  |
| `<Link to={`/posts/${id}`}>` | `<Link to="/posts/$postId" params={{ postId: id }}>` |
| `useNavigate()('/path')`     | `navigate({ to: '/path' })`                          |
| `useParams()`                | `useParams({ from: '/route/$param' })`               |
| `useSearchParams()`          | `validateSearch` + `useSearch({ from })`             |
| `useLoaderData()`            | `Route.useLoaderData()`                              |
| `useLocation()`              | `useMatch`, `useMatches`, `useParams`, `useSearch`   |
| `<Outlet />`                 | `<Outlet />`                                         |
| `loader({ params })`         | `loader: ({ params }) => ...` (route option)         |
| `action({ request })`        | Use mutations / form libraries                       |
| `lazy(() => import(...))`    | `autoCodeSplitting` or `.lazy.tsx` files             |
| `:paramName`                 | `$paramName`                                         |
| `*` (splat)                  | `$` (splat, accessed via `_splat`)                   |

© TanStack · MIT · TanStack/router

Similar skills

All skills for Frontend and UI →

From the same set25

The whole set →
deployment deployment deploys TanStack Start to Cloudflare Workers, Netlify, Vercel, Node.js, Bun, and Railway. Controls SSR per route, static prerendering, and SEO config. CX Codex +1 210installs path-params path-params — a skill for handling dynamic URL parameters in TanStack Router. Teaches agents to capture variable path segments, set up optional routes, and create patterns with prefixes and suffixes. CX Codex +1 208installs middleware Covers TanStack Start middleware: createMiddleware, context chaining via next(), sendContext for cross-boundary transfers, and global registration in src/start.ts. CX Codex +1 206installs server-routes This skill guides an agent through API endpoints in TanStack Router, including HTTP handlers and request parsing. Use it when routes need an HTTP contract. CX Codex +1 205installs ssr The ssr skill for Claude Code configures streaming or non-streaming server-side rendering in TanStack Router for projects integrating the router with an existing server. CX Codex +1 202installs auth-server-primitives auth-server-primitives is a Claude Code skill for server-side authentication in TanStack Start. It covers session handling, OAuth, password-reset defenses, and protection for server functions. CX Codex +1 201installs bundle-size-optimization bundle-size-optimization — a skill that makes the agent measure TanStack Router client bundles and compare each candidate against a saved baseline. Useful when gzip creeps up after a change. CX Codex +1 139installs virtual-file-routes The virtual-file-routes skill for Claude Code builds route trees programmatically instead of relying on filesystem conventions. It triggers during router configuration updates. CX Codex +1 108installs

Project sponsors

Companies that keep this analytics open