Typed dependency context
A router needs shared services such as a QueryClient available to route loaders and child routes.
TanStack · Function
createRootRouteWithContext
Creates a typed root-route factory whose context contract must be satisfied when the router is created. Use it to make router context available with consistent types across the route tree.
How it works
Call createRootRouteWithContext with the router-context type, then call the returned factory with root-route options. The resulting route tree carries that type contract, so createRouter must receive a context object satisfying it; the context remains available throughout the route tree.
Syntax
createRootRouteWithContext<TRouterContext>()(routeOptions)Parameters
| Name | Type | Description |
|---|---|---|
TRouterContext | generic type | The router context type that must be supplied when createRouter is called. It is optional but recommended. |
Returns
A factory function for creating a createRootRoute instance; it accepts the same argument as createRootRoute.
Key points
- It takes one generic argument, TRouterContext, representing the context type the router must later provide.
- The context generic is optional, although the documentation recommends specifying it for stronger type safety.
- The declared type becomes a requirement on the context passed during router creation.
- The result is a factory for creating a root-route instance.
- The factory accepts the same root-route options as createRootRoute.
Common mistakes
- The function returns a factory, so route options belong in a second call rather than the initial invocation.
Example: Create a typed router context
import { createRootRouteWithContext, createRouter } from '@tanstack/react-router'
interface RouterContext {
queryClient: QueryClient
}
declare const QueryClient: new () => unknown
const rootRoute = createRootRouteWithContext<RouterContext>()({
component: () => null,
})
const routeTree = rootRoute.addChildren([])
const queryClient = new QueryClient()
const router = createRouter({
routeTree,
context: { queryClient },
})
void routerThe typed root route requires the router to provide a matching context object.
When to use it
Typed application state
Authentication state or other application-wide values must be passed into the router with compile-time checking.
Route-tree type safety
A route tree should expose one consistent context contract to all descendant routes.
Interview questions
QWhat problem does createRootRouteWithContext solve?
It creates a root-route factory whose generic context type becomes a requirement when the router is instantiated. Supplying the generic gives the route tree and its child routes a consistent context contract.
Follow-up: What happens if the router omits a required context property? TypeScript reports that the router configuration does not satisfy the context contract.
QHow is the function called?
The first call supplies the context type, and the returned factory is then called with the same root-route options accepted by createRootRoute. This produces the root route used to build the route tree.
Follow-up: Why are there two calls? The first configures the factory's generic type; the second creates the route instance.
QWhere is the context value provided?
The context is supplied in createRouter through its context option. Once the root route establishes the type, that object must fulfill the declared contract.
Follow-up: Can child routes use the context? Yes; the typed context is available throughout the route tree.
Related
createRootRoutecreateRouterRouter ContextrootRoute