TanStack Start is built on top of TanStack Router, so all of the features of TanStack Router are available to you.
We highly recommend reading theTanStack Router documentation to learn more about the features and capabilities of TanStack Router. What you learn here is more of a high-level overview of TanStack Router and how it works in Start.
Therouter.tsx file is the file that will dictate the behavior of TanStack Router used within Start. It's located in thesrc directory of your project.
src/├── router.tsxsrc/├── router.tsxHere, you can configure everything from the defaultpreloading functionality tocaching staleness.
// src/router.tsximport { createRouter } from '@tanstack/react-router'import { routeTree } from './routeTree.gen'// You must export a getRouter function that// returns a new router instance each timeexport function getRouter() { const router = createRouter({ routeTree, scrollRestoration: true, }) return router}// src/router.tsximport { createRouter } from '@tanstack/react-router'import { routeTree } from './routeTree.gen'// You must export a getRouter function that// returns a new router instance each timeexport function getRouter() { const router = createRouter({ routeTree, scrollRestoration: true, }) return router}Start uses TanStack Router's file-based routing approach to ensure proper code-splitting and advanced type-safety.
You can find your routes in thesrc/routes directory.
src/├── routes <-- This is where you put your routes│ ├── __root.tsx│ ├── index.tsx│ ├── about.tsx│ ├── posts.tsx│ ├── posts/$postId.tsxsrc/├── routes <-- This is where you put your routes│ ├── __root.tsx│ ├── index.tsx│ ├── about.tsx│ ├── posts.tsx│ ├── posts/$postId.tsxThe root route is the top-most route in the entire tree and encapsulates all other routes as children. It's found in thesrc/routes/__root.tsx file and must be named__root.tsx.
src/├── routes│ ├── __root.tsx <-- The root routesrc/├── routes│ ├── __root.tsx <-- The root route// src/routes/__root.tsximport { Outlet, createRootRoute, HeadContent, Scripts,} from '@tanstack/react-router'import type { ReactNode } from 'react'export const Route = createRootRoute({ head: () => ({ meta: [ { charSet: 'utf-8', }, { name: 'viewport', content: 'width=device-width, initial-scale=1', }, { title: 'TanStack Start Starter', }, ], }), component: RootComponent,})function RootComponent() { return ( <RootDocument> <Outlet /> </RootDocument> )}function RootDocument({ children }: Readonly<{ children: ReactNode }>) { return ( <html> <head> <HeadContent /> </head> <body> {children} <Scripts /> </body> </html> )}// src/routes/__root.tsximport { Outlet, createRootRoute, HeadContent, Scripts,} from '@tanstack/react-router'import type { ReactNode } from 'react'export const Route = createRootRoute({ head: () => ({ meta: [ { charSet: 'utf-8', }, { name: 'viewport', content: 'width=device-width, initial-scale=1', }, { title: 'TanStack Start Starter', }, ], }), component: RootComponent,})function RootComponent() { return ( <RootDocument> <Outlet /> </RootDocument> )}function RootDocument({ children }: Readonly<{ children: ReactNode }>) { return ( <html> <head> <HeadContent /> </head> <body> {children} <Scripts /> </body> </html> )}Notice theScripts component at the bottom of the<body> tag. This is used to load all of the client-side JavaScript for the application and should always be included for proper functionality.
TheHeadContent component is used to render the head, title, meta, link, and head-related script tags of the document.
It should berendered in the<head> tag of your root route's layout.
TheOutlet component is used to render the next potentially matching child route.<Outlet /> doesn't take any props and can be rendered anywhere within a route's component tree. If there is no matching child route,<Outlet /> will rendernull.
TheScripts component is used to render the body scripts of the document.
It should berendered in the<body> tag of your root route's layout.
You may notice arouteTree.gen.ts file in your project.
src/├── routeTree.gen.ts <-- The generated route tree filesrc/├── routeTree.gen.ts <-- The generated route tree fileThis file is automatically generated when you run TanStack Start (vianpm run dev ornpm run start). This file contains the generated route tree and a handful of TS utilities that make TanStack Start's type-safety extremely fast and fully inferred.
You may gitignore this file, since it is a build artifact.
TanStack Router uses nested routing to match the URL with the correct component tree to render.
For example, given the following routes:
routes/├── __root.tsx <-- Renders the <Root> component├── posts.tsx <-- Renders the <Posts> component├── posts.$postId.tsx <-- Renders the <Post> componentroutes/├── __root.tsx <-- Renders the <Root> component├── posts.tsx <-- Renders the <Posts> component├── posts.$postId.tsx <-- Renders the <Post> componentAnd the URL:/posts/123
The component tree would look like this:
<Root> <Posts> <Post /> </Posts></Root><Root> <Posts> <Post /> </Posts></Root>There are a few different types of routes that you can create in your project.
There are also a few different utility route types that you can use to group and organize your routes
The route tree is configured in thesrc/routes directory.
To create a route, create a new file that corresponds to the path of the route you want to create. For example:
| Path | Filename | Type |
|---|---|---|
| / | index.tsx | Index Route |
| /about | about.tsx | Static Route |
| posts.tsx | "Layout" Route | |
| /posts/ | posts/index.tsx | Index Route |
| /posts/:postId | posts/$postId.tsx | Dynamic Route |
| /rest/* | rest/$.tsx | Wildcard Route |
To define a route, use thecreateFileRoute function to export the route as theRoute variable.
For example, to handle the/posts/:postId route, you would create a file namedposts/$postId.tsx here:
src/├── routes│ ├── posts/$postId.tsxsrc/├── routes│ ├── posts/$postId.tsxThen, define the route like this:
// src/routes/posts/$postId.tsximport { createFileRoute } from '@tanstack/react-router'export const Route = createFileRoute('/posts/$postId')({ component: PostComponent,})// src/routes/posts/$postId.tsximport { createFileRoute } from '@tanstack/react-router'export const Route = createFileRoute('/posts/$postId')({ component: PostComponent,})The path string passed tocreateFileRoute isautomatically written and managed by the router for you via the TanStack Router Bundler Plugin or Router CLI. So, as you create new routes, move routes around or rename routes, the path will be updated for you automatically.
This has been just a high-level overview of how to configure routes using TanStack Router. For more detailed information, please refer to theTanStack Router documentation.
