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.
Full-Stack Architecture
TanStack Start is a full-stack framework built on top of TanStack Router that enables you to build modern web applications with seamless client-server integration. It combines the power of server-side rendering (SSR), streaming, and server functions into a unified development experience.
Overview
TanStack Start provides a complete full-stack solution that includes:
- Unified Router: Built on TanStack Router with file-based or code-based routing
- Server Functions: Type-safe RPC-like functions that run on the server
- SSR & Streaming: Server-side rendering with progressive hydration
- API Routes: File-based API endpoints with full HTTP method support
- Middleware System: Request and function-level middleware for cross-cutting concerns
- Built-in Bundling: Powered by Vite with optimized code splitting
Architecture Components
Client-Server Split
TanStack Start automatically splits your application into client and server bundles:
// This code runs on both client and server
import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'
// Server function - runs only on the server
const getUser = createServerFn({ method: 'GET' })
.inputValidator((id: string) => id)
.handler(async ({ data: userId }) => {
// This code only runs on the server
const user = await db.users.findById(userId)
return user
})
// Route component - runs on both server (SSR) and client
export const Route = createFileRoute('/users/$userId')({
loader: async ({ params }) => {
// Call server function - works on both client and server
const user = await getUser({ data: params.userId })
return { user }
},
component: UserProfile,
})
function UserProfile() {
const { user } = Route.useLoaderData()
return <div>{user.name}</div>
}
packages/start-server-core/src/createStartHandler.ts:352
Package Structure
TanStack Start is organized into specialized packages:
@tanstack/start-client-core: Client-side runtime for server function calls@tanstack/start-server-core: Server-side request handling and SSR@tanstack/react-start: React-specific bindings and components@tanstack/start-plugin-core: Build-time transformations and routing
Request Flow
Here’s how a typical request flows through TanStack Start:
1. Initial Page Load (SSR)
┌─────────┐ ┌──────────────┐ ┌─────────────┐
│ Browser │─────>│ Start Handler│─────>│ Router │
└─────────┘ └──────────────┘ └─────────────┘
│ │
│ ▼
│ ┌──────────────┐
│ │ Route Loader │
│ └──────────────┘
│ │
│ ▼
│ ┌──────────────┐
│ │Server Function│
│ └──────────────┘
│ │
▼ ▼
┌────────────────────────────────┐
│ Rendered HTML + Hydration │
└────────────────────────────────┘
2. Client-Side Navigation
┌─────────┐ ┌──────────────┐ ┌─────────────┐
│ Click │─────>│ Router │─────>│Route Loader │
└─────────┘ └──────────────┘ └─────────────┘
│
▼
┌──────────────┐
│ Server Fn RPC│
└──────────────┘
│
▼
┌──────────────┐
│ HTTP Request │
└──────────────┘
Start Handler
The createStartHandler function is the entry point for your server:
import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server'
export default createStartHandler({
handler: defaultStreamHandler,
})
- Normalizes incoming requests
- Executes request middleware
- Routes to server functions or page routes
- Handles SSR and streaming responses
- Manages asset URLs and manifests
Reference: packages/start-server-core/src/createStartHandler.ts:353-650
Type Safety
TanStack Start provides end-to-end type safety:
import { z } from 'zod'
import { createServerFn } from '@tanstack/react-start'
// Define input schema
const updateUser = createServerFn({ method: 'POST' })
.inputValidator(z.object({
id: z.string(),
name: z.string(),
email: z.string().email(),
}))
.handler(async ({ data }) => {
// `data` is fully typed!
// { id: string, name: string, email: string }
await db.users.update(data.id, {
name: data.name,
email: data.email,
})
return { success: true }
})
// Type-safe call
await updateUser({
data: {
id: '1',
name: 'John',
email: 'john@example.com'
}
})
Environment Detection
TanStack Start automatically handles code that runs in different environments:
import { createServerFn } from '@tanstack/react-start'
const getSecret = createServerFn({ method: 'GET' }).handler(() => {
// This code only runs on the server
// Environment variables are safe here
return process.env.SECRET_KEY
})
// This runs on both client and server
function MyComponent() {
const [secret, setSecret] = useState(null)
useEffect(() => {
// Server function call from client
getSecret().then(setSecret)
}, [])
return <div>{secret}</div>
}
Development vs Production
TanStack Start optimizes differently for each environment:
Development
- Hot module replacement (HMR) for instant updates
- Source maps for debugging
- Detailed error messages
- Fresh manifest on each request for route-specific styles
Production
- Optimized bundles with code splitting
- Cached manifests for performance
- Minified assets
- CDN-ready asset URLs
Reference: packages/start-server-core/src/createStartHandler.ts:165-173
Middleware System
TanStack Start supports two types of middleware:
Request Middleware
Runs once per HTTP request:
import { createMiddleware } from '@tanstack/react-start'
export const authMiddleware = createMiddleware()
.server(async ({ request, next }) => {
const session = await getSession(request.headers.get('cookie'))
return next({ context: { session } })
})
Function Middleware
Runs for each server function call:
import { createMiddleware } from '@tanstack/react-start'
export const loggingMiddleware = createMiddleware()
.server(async ({ next, context }) => {
console.log('Function called with context:', context)
const result = await next()
console.log('Function completed')
return result
})
packages/start-client-core/src/createServerFn.ts:196-336
Asset Management
TanStack Start automatically manages your application assets:
import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server'
export default createStartHandler({
handler: defaultStreamHandler,
// Transform asset URLs for CDN
transformAssetUrls: 'https://cdn.example.com',
})
- JavaScript module preloads
- CSS stylesheet links
- Client entry scripts
Reference: packages/start-server-core/src/createStartHandler.ts:59-112
Next Steps
- Learn about Server Functions for client-server communication
- Explore SSR capabilities for server-side rendering
- Understand Streaming for progressive rendering
- Review Deployment strategies for production