用途
TanStack Start 是一个全栈 React 框架，由 TanStack Router 和 Vite 提供支持，适用于需要在 React 应用中同时处理客户端路由与服务端能力的场景。其定位是提供 SSR、流式渲染、服务器函数、服务器路由、中间件以及通用部署能力。如果只需客户端路由而无需 SSR、流式渲染、服务器函数或中间件，官方建议直接使用 TanStack Router，而非 Start。该框架不面向 Next.js、Remix 或 React Router 项目。
主要能力
框架的关键差异点包括：端到端类型安全、可组合中间件（客户端加服务端）、按路由选择性 SSR、部署无关（可运行于任意兼容 Vite 的托管环境），以及显式优于隐式的设计模式。RSC 支持通过 Composite Components 提供，即服务端生成、由客户端获取并缓存和流式接收的 React 组件，相关细节见 references/migration.md。
使用方式
快速创建项目可使用 pnpm create @tanstack/start@latest 或 npm create @tanstack/start@latest。也可克隆官方示例：npx gitpick TanStack/router/tree/main/examples/react/EXAMPLE_SLUG my-project。官方示例包括 start-basic、start-basic-auth、start-counter、start-basic-react-query、start-clerk-basic、start-convex-trellaux、start-supabase-basic、start-trellaux、start-workos、start-material-ui。
手动安装依赖：npm i @tanstack/react-start @tanstack/react-router react react-dom 以及开发依赖 npm i -D vite @vitejs/plugin-react typescript vite-tsconfig-paths @types/node @types/react @types/react-dom。
必需文件包括 vite.config.ts，其中需使用 tsConfigPaths()、tanstackStart() 与 viteReact()，且 tanstackStart() 必须在 viteReact() 之前。可使用 @vitejs/plugin-react-swc 或 @vitejs/plugin-react-oxc 替代 @vitejs/plugin-react。src/router.tsx 用于创建 router，src/routes/__root.tsx 定义根路由与 HTML 外壳，其中需在 head 中放置 HeadContent，在 body 末尾放置 Scripts。package.json 中设置 "type": "module"，脚本为 vite dev 与 vite build。
核心工作流包括：基于文件的路由（src/routes/，routeTree.gen.ts 在开发/构建时自动生成，支持 index、static、dynamic、wildcard、pathless layout 与分组目录）；服务器函数（使用 createServerFn()，可配合 inputValidator，支持 Zod 校验、redirect、notFound，并可通过 .url 属性支持 HTML 表单的渐进增强）；中间件（请求中间件与服务端函数中间件，可全局配置于 src/start.ts）；服务器路由（API 端点，按 createFileRoute 定义 server.handlers 处理 GET、POST 等）；会话（通过 useSession 配置密码与 cookie 选项）。
适用场景
适合需要全栈 React 能力、端到端类型安全、服务端渲染、按路由选择性 SSR、流式数据加载、渐进增强表单、自定义 API 端点以及跨平台部署的 React 项目。提供路由、SSR、服务器函数、中间件、会话、认证、数据流、SEO、部署、预渲染缓存、可观测性、迁移与故障排查等参考文档。
限制与约束
Loader 是同构的，在 SSR 期间于服务端运行，导航时于客户端运行，因此不应在 loader 中直接访问 process.env 密钥，应改用 createServerFn()。环境变量中，服务端可用 process.env.ANY_VAR，客户端仅可导入以 VITE_ 前缀的 import.meta.env.VITE_*，且不应给密钥加 VITE_ 前缀。插件顺序要求 tanstackStart() 先于 viteReact()。TypeScript 不应启用 verbatimModuleSyntax，必需设置为 jsx: "react-jsx"、moduleResolution: "Bundler"、module: "ESNext"。服务器函数可安全地静态导入，应避免动态导入。执行边界可使用 createServerOnlyFn()、createClientOnlyFn() 与 createIsomorphicFn()。根路由必须同时包含 HeadContent 与 Scripts。服务器函数可直接返回 Response 对象以处理二进制数据或自定义内容类型。常见错误涉及水合不匹配、客户端环境变量未定义、密钥泄露与服务器代码进入客户端包。