@tanstack/react-start 是 TanStack Start 的 React 绑定入口技能。官方说明中强调三点关键约束:所有代码默认是同构的(isomorphic),loader 会在服务端与客户端两端运行,仅服务端逻辑必须放进 createServerFn;不要把它与 Next.js 或 Remix 混淆,它们是 API 完全不同的框架;类型是全量推断的,不要做类型断言或给可推断的值加注解。
【用途与工作流】 技能建议采用如下全栈工作流:先用 createFileRoute 定义路由和组件;把私有的或仅服务端的读写放进 createServerFn,读取可直接从 loader 调用;在组件变更时使用 useServerFn,写入解决后让 router 或 query 缓存失效;在每个私有服务端函数或服务端路由中强制鉴权,同时为导航体验单独添加 beforeLoad;最后运行初始 SSR 路径、客户端导航、变更加重载、直接匿名端点请求、运行时响应断言、类型测试和生产构建。当需要裸 HTTP 端点时,应加载 start-core/server-routes 而不是 server-functions;只有在涉及特定路由关注点(如参数或搜索校验)时才加载 router-core/*。
【包 API 表面】 @tanstack/react-start 再导出了 @tanstack/start-client-core 的全部内容,并额外提供 useServerFn(React 钩子,用于从组件调用服务端函数)。核心 API(createServerFn、createMiddleware、createStart、createIsomorphicFn、createServerOnlyFn、createClientOnlyFn)均可从 @tanstack/react-start 获取。服务端工具(getRequest、getRequestHeader、setResponseHeader、setResponseHeaders、setResponseStatus)需从 @tanstack/react-start/server 导入。
【完整项目搭建】 资料给出的搭建步骤包括:安装依赖(npm i @tanstack/react-start @tanstack/react-router react react-dom,以及开发依赖 vite、@vitejs/plugin-react、typescript、@types/react、@types/react-dom);配置 package.json(type 为 module,scripts 为 vite dev / vite build / node .output/server/index.mjs);配置 tsconfig.json(react-jsx、Bundler、ESNext、ES2022 等);配置 vite.config.ts(tanstackStart() 必须放在 viteReact() 之前);编写路由工厂 src/router.tsx(createRouter 配合 routeTree.gen,启用 scrollRestoration);编写根路由 src/routes/__root.tsx(使用 Outlet、createRootRoute、HeadContent、Scripts);编写索引路由 src/routes/index.tsx(createServerFn 定义 GET、createFileRoute 设置 loader 与组件、通过 Route.useLoaderData() 取数)。
【useServerFn 钩子】 该钩子用于从 React 组件调用服务端函数,典型示例为 createServerFn({ method: 'POST' }).validator(...).handler(...),在表单提交时通过 useServerFn(updatePost) 调用,并传入 data 参数。
【全局 Start 配置】 在 src/start.ts 中,通过 createStart 与 createMiddleware 配置全局,例如添加 requestLogger 中间件,记录请求方法与 URL 后调用 next()。
【React 专用组件】 @tanstack/react-router 的所有路由组件在 Start 中均可用:RouterProvider(Start 中无需手动使用,已自动处理)、Outlet、Link、Navigate、HeadContent(必须放在 head 中)、Scripts(必须放在 body 中)、Await、ClientOnly、CatchBoundary。
【钩子参考】 所有 @tanstack/react-router 的钩子在 Start 中可用:useRouter、useRouterState、useNavigate、useSearch({ from })、useParams({ from })、useLoaderData({ from })、useMatch({ from })、useRouteContext({ from }),以及在路由文件中更推荐的 Route.useLoaderData() 与 Route.useSearch()。
【常见错误】 资料列出三类常见问题:从错误包导入(createServerFn 应来自 @tanstack/react-start,而非 @tanstack/react-router;路由 API 来自 @tanstack/react-router);在 beforeLoad 或 loader 中使用 React 钩子(这两者不是 React 组件,应通过 router context 传递状态);遗漏 Scripts 组件(根路由 body 中没有 Scripts,客户端 JavaScript 不会加载,应用无法水合)。
【适用场景与限制】 适用于使用 TanStack Start 构建 React 全栈应用、需要同构 loader、服务端函数、鉴权强制与类型推断的场景。资料未提供该技能的价格、收费、平台限制、性能效果或具体版本号等信息。