---
id: context-bridge
title: Context Bridge
---
## What is a Context Bridge?
A context bridge transports server-side context values — produced by [middleware](./middleware.md) — 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:
```tsx
// 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.
```tsx
// 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
```tsx
// 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 (
User: {userId}
Role: {role}
)
}
```
## How it works
The context bridge is a router plugin that hooks into the router's dehydrate/hydrate lifecycle:
1. **On the server**: The plugin reads the global start context (populated by your middleware), runs the `select` function, and merges the selected values into `router.options.context`. It also hooks into `router.options.dehydrate` to serialize those values into the dehydrated payload sent to the client.
2. **On the client**: The plugin hooks into `router.options.hydrate` to read the serialized values from the dehydrated payload and merge them back into `router.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.
```tsx
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 `select` must 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.
```tsx
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:
- `startContextBridge` provides `userId` and `role`
- `ssrQueryPlugin` provides `queryClient`
- You only need to manually supply `appName` in `context`
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:
```tsx
createStartContextBridge({
key: '__myCustomBridgeKey',
select: (ctx) => ({ userId: ctx.userId }),
})
```
## Type safety
The context bridge integrates with the router plugin type system:
- The `select` function is typed based on your registered middleware
- The `context` option in `createRouter` becomes optional for keys that plugins provide
- Route loaders and components see the bridged values in their `context` parameter with full type inference