> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tanstack/router/llms.txt
> Use this file to discover all available pages before exploring further.
# Server-side rendering (SSR)
> Render your routes on the server for improved performance and SEO
Server-side rendering (SSR) enables rendering your application on the server, sending fully-rendered HTML to the client for faster initial page loads and better SEO.
## SSR setup
For React Router with SSR:
```bash npm theme={null}
npm install @tanstack/react-router
npm install -D @tanstack/router-plugin
```
```bash pnpm theme={null}
pnpm add @tanstack/react-router
pnpm add -D @tanstack/router-plugin
```
Create separate client and server entry points:
```tsx src/entry-client.tsx theme={null}
import ReactDOM from 'react-dom/client'
import { StartClient } from '@tanstack/react-start/client'
import { createRouter } from './router'
const router = createRouter()
ReactDOM.hydrateRoot(
document.getElementById('root')!,
)
```
```tsx src/entry-server.tsx theme={null}
import { renderToString } from 'react-dom/server'
import { StartServer } from '@tanstack/react-start/server'
import { createMemoryHistory } from '@tanstack/react-router'
import { createRouter } from './router'
export async function render(url: string) {
const router = createRouter()
const memoryHistory = createMemoryHistory({
initialEntries: [url],
})
router.update({ history: memoryHistory })
await router.load()
const html = renderToString()
return html
}
```
```tsx theme={null}
export function createHtml(content: string) {
return `
My App
${content}
`
}
```
## Using TanStack Start
For the easiest SSR setup, use TanStack Start:
```tsx app.config.ts theme={null}
import { defineConfig } from '@tanstack/react-start/config'
export default defineConfig({
// SSR is enabled by default
})
```
```tsx src/routes/__root.tsx theme={null}
import { createRootRoute, Outlet, ScrollRestoration } from '@tanstack/react-router'
import { Meta, Scripts } from '@tanstack/react-start'
export const Route = createRootRoute({
component: () => (
),
})
```
## Server-side data loading
Loaders run on the server during SSR:
```tsx src/routes/posts/$postId.tsx theme={null}
import { createFileRoute } from '@tanstack/react-router'
import { fetchPost } from '@/api/posts'
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
// Runs on server during SSR
const post = await fetchPost(params.postId)
return { post }
},
component: PostPage,
})
function PostPage() {
const { post } = Route.useLoaderData()
return (
{post.title}
{post.content}
)
}
```
## Hydration
Dehydrate server state and rehydrate on client:
```tsx src/entry-server.tsx theme={null}
import { DehydrateRouter } from '@tanstack/react-router'
export async function render(url: string) {
const router = createRouter()
// ... setup router
await router.load()
const html = renderToString(
<>
)
return html
}
```
```tsx src/entry-client.tsx theme={null}
import { HydrateRouter } from '@tanstack/react-router'
const router = createRouter()
ReactDOM.hydrateRoot(
document.getElementById('root')!,
)
```
## Client-only components
Render components only on the client:
```tsx theme={null}
import { ClientOnly } from '@tanstack/react-router'
function MyPage() {
return (
This renders on server
}>
{() => }
)
}
```
## Detecting SSR
Check if code is running on server:
```tsx theme={null}
import { isServer } from '@tanstack/react-router'
function MyComponent() {
React.useEffect(() => {
if (!isServer) {
// Client-only code
console.log('Running on client')
}
}, [])
return Content
}
```
## Streaming SSR
Stream HTML as it's generated:
```tsx src/entry-server.tsx theme={null}
import { renderToPipeableStream } from 'react-dom/server'
export function renderStream(url: string, res: Response) {
const router = createRouter()
// ... setup router
const { pipe } = renderToPipeableStream(
,
{
onShellReady() {
res.setHeader('Content-Type', 'text/html')
pipe(res)
},
onError(error) {
console.error(error)
},
}
)
}
```
## SEO and meta tags
Set meta tags from routes:
```tsx theme={null}
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const post = await fetchPost(params.postId)
return { post }
},
meta: ({ loaderData }) => [
{ title: loaderData.post.title },
{ name: 'description', content: loaderData.post.excerpt },
{ property: 'og:title', content: loaderData.post.title },
{ property: 'og:image', content: loaderData.post.image },
],
})
```
## Environment variables
Access env vars safely:
```tsx theme={null}
// Server-only env vars
if (isServer) {
const apiKey = process.env.SECRET_API_KEY
}
// Public env vars (prefixed with PUBLIC_)
const publicUrl = import.meta.env.PUBLIC_API_URL
```
## Error handling in SSR
Handle errors during server rendering:
```tsx theme={null}
export async function render(url: string) {
try {
const router = createRouter()
await router.load()
return renderToString()
} catch (error) {
console.error('SSR Error:', error)
// Return error page HTML
return renderToString()
}
}
```
## Deferred data in SSR
Stream deferred data after initial render:
```tsx theme={null}
import { defer, Await } from '@tanstack/react-router'
export const Route = createFileRoute('/dashboard')({
loader: async () => {
// Critical data loads first
const user = await fetchUser()
// Non-critical data is deferred
const stats = defer(fetchStats())
return { user, stats }
},
})
function Dashboard() {
const { user, stats } = Route.useLoaderData()
return (
Welcome, {user.name}
}>
{(data) => }
)
}
```
## Static generation
Pre-render routes at build time:
```tsx build.ts theme={null}
import { renderToString } from 'react-dom/server'
import { createRouter } from './router'
import { writeFileSync } from 'fs'
const routes = ['/', '/about', '/contact']
for (const route of routes) {
const router = createRouter()
// ... render route
const html = renderToString()
writeFileSync(`dist${route}/index.html`, html)
}
```
## Best practices
Use loaders for data needed for initial render to ensure it's available during SSR.
Wrap code that uses `window`, `document`, or other browser APIs in ClientOnly.
Keep server-only code separate and use tree-shaking to reduce bundle size.
Implement caching strategies for frequently-accessed pages.
Stream HTML as it's generated for faster time-to-first-byte.
## Performance tips
**Preload critical routes**: Preload routes users are likely to visit next.
**Use deferred data**: Defer non-critical data to improve initial page load.
Avoid heavy computations in loaders - cache results or move to background jobs.
## Next steps
Full-stack framework with SSR
Optimize server data fetching