TanStackRouter v1
Framework
Version

Migration from React Location

Before you begin your journey in migrating from React Location, its important that you have a good understanding of the Routing Concepts and Design Decisions used by TanStack Router.

Differences between React Location and TanStack Router

React Location and TanStack Router share much of same design decisions concepts, but there are some key differences that you should be aware of.

  • React Location uses generics to infer types for routes, while TanStack Router uses module declaration merging to infer types.
  • Route configuration in React Location is done using a single array of route definitions, while in TanStack Router, route configuration is done using a tree of route definitions starting with the root route.
  • File-based routing is the recommended way to define routes in TanStack Router, while React Location only allows you to define routes in a single file using a code-based approach.

Migration guide

In this guide we'll go over the process of migrating the React Location Basic example over to TanStack Router using file-based routing, with the end goal of having the same functionality as the original example (styling and other non-routing related code will be omitted).

Note: To use a code-based approach for defining your routes, you can read the code-based Routing guide.

Step 1: Swap over to TanStack Router's dependencies

First, we need to install the dependencies for TanStack Router.

bash
npm install @tanstack/react-router @tanstack/router-devtools

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

And remove the React Location dependencies.

bash
npm uninstall @tanstack/react-location @tanstack/react-location-devtools

npm uninstall @tanstack/react-location @tanstack/react-location-devtools

Step 2: Use the file-based routing watcher

If your project uses vite, you can use the our plugin to watch for changes in your routes files and automatically update the routes configuration.

Install the vite plugin:

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

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

And add it to your vite.config.js:

js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'

export default defineConfig({
  // ...
  plugins: [TanStackRouterVite(), react()],
})

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'

export default defineConfig({
  // ...
  plugins: [TanStackRouterVite(), react()],
})

However, if your application does not use vite, you can use the @tanstack/router-cli package to watch for changes in your routes files and automatically update the routes configuration.

bash
npm install -D @tanstack/router-cli

npm install -D @tanstack/router-cli

And add a script to your package.json:

json
{
  "scripts": {
    "dev": "tsr watch"
  }
}

{
  "scripts": {
    "dev": "tsr watch"
  }
}

Step 3: Add the file-based configuration file to your project

Create a tsr.config.json file in the root of your project with the following content:

json
{
  "routesDirectory": "./src/routes",
  "generatedRouteTree": "./src/routeTree.gen.ts"
}

{
  "routesDirectory": "./src/routes",
  "generatedRouteTree": "./src/routeTree.gen.ts"
}

You can find the full list of options for the tsr.config.json file here.

Step 4: Create the routes directory

Create a routes directory in the src directory of your project.

bash
mkdir src/routes

mkdir src/routes

Step 5: Create the root route file
tsx
// src/routes/__root.tsx
import { createRootRoute, Outlet, Link } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/router-devtools'

export const Route = createRootRoute({
  component: () => {
    return (
      <>
        <div>
          <Link to="/" activeOptions={{ exact: true }}>
            Home
          </Link>
          <Link to="/posts">Posts</Link>
        </div>
        <hr />
        <Outlet />
        <TanStackRouterDevtools />
      </>
    )
  },
})

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

export const Route = createRootRoute({
  component: () => {
    return (
      <>
        <div>
          <Link to="/" activeOptions={{ exact: true }}>
            Home
          </Link>
          <Link to="/posts">Posts</Link>
        </div>
        <hr />
        <Outlet />
        <TanStackRouterDevtools />
      </>
    )
  },
})

Step 6: Create the index route file
tsx
// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Index,
})

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

export const Route = createFileRoute('/')({
  component: Index,
})

You will need to move any related components and logic needed for the index route from the src/index.tsx file to the src/routes/index.tsx file.

Step 7: Create the posts route file
tsx
// src/routes/posts.tsx
import { createFileRoute, Link, Outlet } from '@tanstack/react-router'

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

function Posts() {
  const { posts } = Route.useLoaderData()
  return (
    <div>
      <nav>
        {posts.map((post) => (
          <Link
            key={post.id}
            to={`/posts/$postId`}
            params={{ postId: post.id }}
          >
            {post.title}
          </Link>
        ))}
      </nav>
      <Outlet />
    </div>
  )
}

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

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

function Posts() {
  const { posts } = Route.useLoaderData()
  return (
    <div>
      <nav>
        {posts.map((post) => (
          <Link
            key={post.id}
            to={`/posts/$postId`}
            params={{ postId: post.id }}
          >
            {post.title}
          </Link>
        ))}
      </nav>
      <Outlet />
    </div>
  )
}

You will need to move any related components and logic needed for the posts route from the src/index.tsx file to the src/routes/posts.tsx file.

Step 8: Create the posts index route file
tsx
// src/routes/posts.index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/')({
  component: PostsIndex,
})

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

export const Route = createFileRoute('/posts/')({
  component: PostsIndex,
})

You will need to move any related components and logic needed for the posts index route from the src/index.tsx file to the src/routes/posts.index.tsx file.

Step 9: Create the posts id route file
tsx
// src/routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

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

function PostsId() {
  const { post } = Route.useLoaderData()
  // ...
}

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

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

function PostsId() {
  const { post } = Route.useLoaderData()
  // ...
}

You will need to move any related components and logic needed for the posts id route from the src/index.tsx file to the src/routes/posts.$postId.tsx file.

Step 10: Generate the route tree

If you are using vite as your bundler, the route tree will be generated automatically when you run the dev script.

If you are not using vite, you can generate the route tree by running the following command:

bash
npx tsr generate

npx tsr generate

Step 11: Update the main entry file to render the Router

Once you've generated the route-tree, you can then update the src/index.tsx file to create the router instance and render it.

tsx
// src/index.tsx
import React from 'react'
import ReactDOM from 'react-dom'
import { createRouter, RouterProvider } from '@tanstack/react-router'

// Import the generated route tree
import { routeTree } from './routeTree.gen'

// Create a new router instance
const router = createRouter({ routeTree })

// Register the router instance for type safety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

const domElementId = 'root' // Assuming you have a root element with the id 'root'

// Render the app
const rootElement = document.getElementById(domElementId)
if (!rootElement) {
  throw new Error(`Element with id ${domElementId} not found`)
}

ReactDOM.createRoot(rootElement).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>,
)

// src/index.tsx
import React from 'react'
import ReactDOM from 'react-dom'
import { createRouter, RouterProvider } from '@tanstack/react-router'

// Import the generated route tree
import { routeTree } from './routeTree.gen'

// Create a new router instance
const router = createRouter({ routeTree })

// Register the router instance for type safety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

const domElementId = 'root' // Assuming you have a root element with the id 'root'

// Render the app
const rootElement = document.getElementById(domElementId)
if (!rootElement) {
  throw new Error(`Element with id ${domElementId} not found`)
}

ReactDOM.createRoot(rootElement).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>,
)

Finished!

You should now have successfully migrated your application from React Location to TanStack Router using file-based routing.

React Location also has a few more features that you might be using in your application. Here are some guides to help you migrate those features:

TanStack Router also has a few more features that you might want to explore:

If you are facing any issues or have any questions, feel free to ask for help in the TanStack Discord.

Edit on GitHub
Migrate from React Router
Decisions on DX
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.