5.9 KiB
| id | title |
|---|---|
| context-bridge | Context Bridge |
What is a Context Bridge?
A context bridge transports server-side context values — produced by middleware — to the client via the router's dehydrate/hydrate mechanism. This allows your route loaders and components to access server middleware context on both the server and the client without any manual serialization.
Why do I need it?
When global request middleware provides context (e.g. user info, feature flags, tenant data), that context is only available on the server during SSR. The context bridge selects specific values from your middleware context, serializes them during dehydration, and restores them on the client during hydration — making them available in the router context everywhere.
Setup
1. Define middleware that provides context
In your src/start.ts, define global request middleware that provides context values:
// src/start.ts
import { createMiddleware, createStart } from '@tanstack/react-start'
const authMiddleware = createMiddleware().server(async ({ next }) => {
return next({
context: {
userId: 'user-123',
role: 'admin',
},
})
})
export const startInstance = createStart(() => ({
requestMiddleware: [authMiddleware],
}))
2. Create the context bridge
Use createStartContextBridge to select which middleware context values to bridge to the client. The select function receives the accumulated context from all global request middleware.
// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { createStartContextBridge } from '@tanstack/react-start'
import { routeTree } from './routeTree.gen'
export function getRouter() {
return createRouter({
routeTree,
plugins: [
createStartContextBridge({
select: (ctx) => ({
userId: ctx.userId,
role: ctx.role,
}),
}),
],
})
}
That's it. The bridged values (userId, role) are now available in context throughout your route tree — on both server and client.
3. Use the bridged context in routes
// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/')({
loader: ({ context }) => {
// context.userId and context.role are available here
console.log('User:', context.userId, 'Role:', context.role)
},
component: IndexPage,
})
function IndexPage() {
const { userId, role } = Route.useRouteContext()
return (
<div>
<p>User: {userId}</p>
<p>Role: {role}</p>
</div>
)
}
How it works
The context bridge is a router plugin that hooks into the router's dehydrate/hydrate lifecycle:
-
On the server: The plugin reads the global start context (populated by your middleware), runs the
selectfunction, and merges the selected values intorouter.options.context. It also hooks intorouter.options.dehydrateto serialize those values into the dehydrated payload sent to the client. -
On the client: The plugin hooks into
router.options.hydrateto read the serialized values from the dehydrated payload and merge them back intorouter.options.context.
This means the bridged values are available synchronously in route loaders and components on both server and client.
The select function
The select function controls which middleware context values are bridged to the client. It receives the full accumulated context from all global request middleware.
createStartContextBridge({
select: (ctx) => ({
// Only bridge what you need on the client
userId: ctx.userId,
role: ctx.role,
// Don't bridge secrets or large objects
}),
})
Important
The return value of
selectmust be serializable. Do not include functions, class instances, or other non-serializable values. The type system will warn you if you try to return non-serializable data.
Warning
Be careful not to bridge sensitive values (API keys, secrets, tokens) since they will be serialized and sent to the client in the HTML payload.
Combining with other plugins
The context bridge works alongside other router plugins. Each plugin contributes its own keys to the router context, and the type system tracks which keys are provided by plugins so you only need to manually supply the remaining ones.
import { QueryClient } from '@tanstack/react-query'
import { createRouter } from '@tanstack/react-router'
import { createSsrQueryPlugin } from '@tanstack/react-router-ssr-query'
import { createStartContextBridge } from '@tanstack/react-start'
import { routeTree } from './routeTree.gen'
export function getRouter() {
const queryClient = new QueryClient()
return createRouter({
routeTree,
// Only need to provide keys NOT covered by plugins
context: {
appName: 'My App',
},
plugins: [
createStartContextBridge({
select: (ctx) => ({
userId: ctx.userId,
role: ctx.role,
}),
}),
createSsrQueryPlugin({ queryClient }),
],
})
}
In this example:
startContextBridgeprovidesuserIdandrolessrQueryPluginprovidesqueryClient- You only need to manually supply
appNameincontext
The type system enforces this — if a plugin provides a key, you don't need to include it in context, and if you're missing a required key that no plugin provides, you'll get a type error.
Custom bridge key
If you need multiple context bridges (uncommon), you can provide a custom key to avoid collisions in the dehydrated payload:
createStartContextBridge({
key: '__myCustomBridgeKey',
select: (ctx) => ({ userId: ctx.userId }),
})
Type safety
The context bridge integrates with the router plugin type system:
- The
selectfunction is typed based on your registered middleware - The
contextoption increateRouterbecomes optional for keys that plugins provide - Route loaders and components see the bridged values in their
contextparameter with full type inference