SuperAPI AI 工具集

react-start/server-components

前端与建站

查看项目

更新于 10-16 09:44

技能介绍

用途:在 React 19 应用中实现、审查、调试和重构 TanStack Start React Server Components(RSC)。把 RSC 视为可获取的 React Flight 载荷,而非框架自有的服务端树;先确定数据与缓存归属,再选择最小的 RSC 原语。

主要能力:检查 vite.config.* 中的 tanstackStart({ rsc: { enabled: true } })、rsc()、viteReact();检查路由文件的 loader、loaderDeps、staleTime、ssr、errorComponent;检查服务端边界 createServerFn、createServerOnlyFn、.server.* 及 @tanstack/react-start/server 导入;识别缓存归属(Router loader 缓存、TanStack Query、HTTP/服务端缓存)与刷新路径(router.invalidate()、invalidateQueries、refetchQueries、GET 缓存头)。

使用方式:按三步决策——传输/组合原语(无需客户端插槽用 renderServerComponent;需在服务端渲染标记内插入客户端交互用 createCompositeComponent + <CompositeComponent src={...} />;需自定义 Flight 流、API 路由或非标准传输用 renderToReadableStream、createFromReadableStream、createFromFetch);缓存归属;刷新归属。默认实现顺序:服务端专属逻辑放入 createServerFn 或 createServerOnlyFn,从服务端函数返回 RSC,经路由 loader 消费,添加满足新鲜度的最小缓存策略,在真实缓存归属处只接一次失效,仅在客户端需填充插槽时升级到 Composite Components,仅在高阶辅助无法表达传输时使用低层 Flight API。

限制与不变量:路由 loader 是同构的,不得直接放数据库访问、密钥或仅 Node 可用 API;若 loader 本身需浏览器 API,则该路由设 ssr: false。renderServerComponent 返回可渲染片段,不支持插槽。Query 缓存的 RSC 值需 structuralSharing: false。插槽载荷在服务端不透明,不得检查、映射或克隆 props.children。render prop 与组件插槽参数须保持 Flight 可序列化。当前服务端函数校验 API 为 .validator(...)。TanStack 自定义序列化暂不适用于 RSC,须使用原生 Flight 支持的值。若要在服务端使用 Children.map、cloneElement 或检查 children,应改为 render prop。

适用场景:路由 loader 中的简单服务端片段、服务端标记内的交互插槽、需浏览器 API 但 loader 可服务端预取(ssr: 'data-only')、loader 本身需浏览器 API(ssr: false)、缓存键需含搜索参数(loaderDeps)、Query 管理的 RSC(useSuspenseQuery + SSR ensureQueryData)、多个独立 RSC(分开的服务端函数 + Promise.all)、共享数据或一起失效的多个 RSC(一个服务端函数返回多个可渲染项或源)、需隔离组件失败或错峰显示(loader 返回 promise,在 Suspense 内用 use() 解析)。

调试参考:安装/导出/文档不匹配看 docs/current-api-notes.md;Composite Component 设计或插槽问题看 docs/composite-components.md;数据陈旧、重取、loader 键、Query 与 Router 归属或 SSR 模式看 docs/caching-refresh-ssr.md;审查、重构、导入泄漏、错误边界或序列化问题看 docs/debugging-review.md;架构与 Next/App Router 迁移看 docs/architecture.md。示例文件包括 examples/01-renderable-route-loader.tsx 至 examples/06-low-level-flight-api-route.tsx。