TanStack Start 是一个全栈 React 框架,构建在 TanStack Router + Vite + Nitro 之上,提供文件式路由、服务端函数(RPC)、SSR/SPA/静态模式,并可部署到任意环境(Cloudflare、Netlify、Vercel、Node、Bun)。该技能定位为 TanStack Start 全栈 React 框架专家,会在处理 TanStack Start 项目、TanStack Router、Vite+Nitro 全栈应用时自动加载,提供 API 参考与项目结构指引。
核心 API 速查:createFileRoute('/path') 用于定义带 loader、component、head 的路由;createRootRoute() / createRootRouteWithContext() 用于根布局路由;createRouter({ routeTree, context }) 创建应用路由器实例;createServerFn({ method: 'GET'|'POST' }) 定义仅服务端的 RPC 函数;createMiddleware() 定义请求或函数中间件;useSession() 提供基于 Cookie 的服务端会话;Route.useLoaderData() 访问路由 loader 返回值;useNavigate() 用于编程式导航;<Link to="/path"> 是类型安全的导航链接;redirect({ to, throw: true }) 用于重定向(在 loader/beforeLoad 内抛出);notFound({ throw: true }) 触发 404 边界。
最小项目结构:src/routes/ 下包含 __root.tsx(根布局,禁用 SSR 时使用 shellComponent)、index.tsx(/)、about.tsx(/about)、posts/$postId.tsx(/posts/:postId);routeTree.gen.ts 为自动生成文件(切勿编辑);router.tsx 是 createRouter() 入口;client.tsx 是客户端入口(StartClient);ssr.tsx 是 SSR 处理器;app.config.ts 是 tanstackStart() vite 插件配置。
文件式路由关键约定:文件名中的 . 转换为 / 路径分隔符(如 posts.index.tsx → /posts/);$param 表示动态段;_layout 表示无路径布局(不产生 URL 段);(group) 表示路由分组(不影响 URL);index.tsx 表示目录的索引路由;*.lazy.tsx 表示代码分割的懒加载路由。
核心依赖包括:"@tanstack/react-start": "latest"、"@tanstack/react-router": "latest"、"react": "^19.0.0"、"vite": "^6.0.0"、"vinxi": "latest"。
参考资料覆盖:文档 URL 映射(通过 WebFetch 获取实时文档)、项目搭建(脚手架、vite.config、tsconfig、router.tsx)、路由与导航(文件约定、Link、hooks)、数据加载(loader、预加载、staleTime)、服务端函数(createServerFn、校验、错误)、中间件(请求/函数中间件、context、全局)、服务端路由(API 路由、HTTP 处理器、动态参数)、执行模型(同构代码、服务端/客户端边界)、SSR 模式(选择性 SSR、SPA、静态预渲染、ISR)、认证(会话、路由保护、OAuth)、环境变量(VITE_ 前缀、.env、类型安全)、导入保护(服务端/客户端约束、标记)、Tailwind 与样式(v4 设置、CSS 导入)、SEO 与 Head(meta、OG、结构化数据、站点地图)、托管与部署(Cloudflare、Netlify、Vercel)、错误处理(边界、notFound、水合错误)、React Query 与 tRPC(集成模式)、数据库模式(数据库访问、推荐的提供商)。
适用场景:需要使用文件式路由与服务端 RPC 构建全栈 React 应用的开发工作,尤其是采用 TanStack Router、Vite+Nitro 技术栈的项目。限制方面,资料未提供收费、价格、平台与效果等信息。