Create the application's central router instance
Application bootstrap
TanStack · Function
createRouter
Creates a TanStack Router instance from a RouterOptions object. The required route tree and other router-wide settings are supplied through that object.
How it works
Call createRouter with a RouterOptions object to construct a Router instance. The routeTree option supplies the routes used by the router, while other options configure behavior such as preloading; the resulting instance is passed to a router provider.
Syntax
createRouter(options: RouterOptions): RouterParameters
| Name | Type | Description |
|---|---|---|
options | RouterOptions | Options used to configure the router instance, including the required route tree. |
Returns
An instance of the Router.
Key points
- Its single input is a configuration object typed as RouterOptions.
- The function constructs and returns a new router rather than modifying an existing one.
- RouterOptions provides router-wide configuration.
- A React application supplies the created instance to RouterProvider.
Common mistakes
- Pass the configuration object to createRouter; it expects RouterOptions rather than a route definition or provider component.
- The returned router coordinates route matching and navigation, so it should be created as the application's central router instance.
Example: Create and provide a router
import { createRouter, RouterProvider } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
const router = createRouter({
routeTree,
defaultPreload: 'intent',
})
export default function App() {
return <RouterProvider router={router} />
}Creates a router from the generated route tree and enables intent-based preloading, then supplies that router to the provider.
When to use it
Provide routing through RouterProvider
React integration
Set router-wide behavior such as default preloading
Routing configuration
Share consistent router construction across server and client
Server-side rendering
Interview questions
QWhat does createRouter do?
createRouter accepts a RouterOptions object and returns a Router instance. The options configure the router, including the route tree it uses.
Follow-up: Why is routeTree required? It supplies the routes the router uses to match and render the application.
QWhat is the purpose of routeTree?
The routeTree option is required and identifies the route tree used to configure the router instance. It is typically imported from the generated route-tree module.
Follow-up: How would you share router creation between server and client? Put a createRouter wrapper in a shared file and call it from both entry points.
QHow is the returned router used in a React application?
After creating the instance, pass it to RouterProvider through its router prop. Router-wide behavior can be configured in the createRouter options object.
Follow-up: What should an SSR implementation consider? The router should be created consistently in both server and client environments.
Related
RouterOptionsRouterProviderrouteTree