TanStack Start
TanStack Start is a full-stack React framework built on TanStack Router + Vite + Nitro. It provides file-based routing, server functions (RPC), SSR/SPA/static modes, and deploys anywhere (Cloudflare, Netlify, Vercel, Node, Bun).
Core API Quick Reference
| API | Purpose |
|---|---|
createFileRoute('/path') | Define a route with loader, component, head |
createRootRoute() / createRootRouteWithContext() | Root layout route |
createRouter({ routeTree, context }) | App router instance |
createServerFn({ method: 'GET'|'POST' }) | Server-only RPC function |
createMiddleware() | Request or function middleware |
useSession() | Cookie-based server session |
Route.useLoaderData() | Access route loader return value |
useNavigate() | Programmatic navigation |
<Link to="/path"> | Type-safe navigation link |
redirect({ to, throw: true }) | Redirect (throw inside loader/beforeLoad) |
notFound({ throw: true }) | Trigger 404 boundary |
Minimal Project Structure
src/
routes/
__root.tsx # Root layout (shellComponent when SSR disabled)
index.tsx # /
about.tsx # /about
posts/
$postId.tsx # /posts/:postId
routeTree.gen.ts # Auto-generated (never edit)
router.tsx # createRouter() entry
client.tsx # Client entry (StartClient)
ssr.tsx # SSR handler
app.config.ts # tanstackStart() vite plugin config
File-Based Routing Key Conventions
.in filename →/path separator (e.g.,posts.index.tsx→/posts/)$param→ dynamic segment_layout→ pathless layout (no URL segment)(group)→ route group (no URL impact)index.tsx→ index route for a directory*.lazy.tsx→ code-split lazy route
Core Dependencies
{
"@tanstack/react-start": "latest",
"@tanstack/react-router": "latest",
"react": "^19.0.0",
"vite": "^6.0.0",
"vinxi": "latest"
}
References
- Documentation URL Map — fetch live docs via WebFetch
- Project Setup — scaffold, vite.config, tsconfig, router.tsx
- Routing & Navigation — file conventions, Link, hooks
- Data Loading — loaders, preloading, staleTime
- Server Functions — createServerFn, validation, errors
- Middleware — request/function middleware, context, global
- Server Routes — API routes, HTTP handlers, dynamic params
- Execution Model — isomorphic code, server/client boundaries
- SSR Modes — selective SSR, SPA, static prerendering, ISR
- Authentication — sessions, route protection, OAuth
- Environment Variables — VITE_ prefix, .env, type safety
- Import Protection — server/client enforcement, markers
- Tailwind & Styling — v4 setup, CSS imports
- SEO & Head — meta, OG, structured data, sitemaps
- Hosting & Deployment — Cloudflare, Netlify, Vercel
- Error Handling — boundaries, notFound, hydration errors
- React Query & tRPC — integration patterns
- Database Patterns — DB access, recommended providers