该技能整理 FixMyBerlin/FMC 组织内 TanStack Start 应用的技术约定,适用于搭建或重构 app/src 目录结构、拆分 .server.ts 与 .functions.ts 代码、使用 createServerFn 与服务器变更、设置路由 ssr 或调试 SSR/水合、使用服务端组件(renderServerComponent、createCompositeComponent),以及 routes/api/ 下的 API 路由。作为前置条件,需先安装并遵循 tanstack-router-conventions(搜索参数、美化 URL、loader + Query、TypeScript、devtools);涉及认证与会话布局时配合 tanstack-start-auth。
必守规则:服务器专用模块用 *.server.ts,禁止被路由或组件导入,内部用 createServerOnlyFn;可被客户端调用的逻辑放 .functions.ts,导出名以 Fn 结尾;公开服务端函数放 public.functions.ts,不加全局认证中间件,限流/令牌校验放 .server.ts;API 路由文件不加 server-only 导入标记,服务端逻辑放处理函数内或使用 tree-shaking 导入;API 路由不使用 validateSearch,改为在 GET 中从 request.url 用 safeParse 并返回明确的 4xx JSON;每条路由显式设置 ssr,UI 默认完整 SSR(true),纯处理函数的 API 路由用 false,地图类重度 UI 用 data-only;本地 Vite dev 与 Nitro start/preview 使用 bun --bun,使 SSR 与生产 Bun 预设一致。
快速决策:重定向、认证、轻量上下文放 beforeLoad(非中间件),数据获取/Query 预取放 loader;注意 beforeLoad 不受 loaderDeps 控制,每次导航都会重跑(含搜索参数变化),对于含纯客户端搜索参数(如地图视口、图层开关)的热路由,应把重定向/认证/区域往返移入 loader 并让这些参数留在客户端。Start 中路由服务端 I/O 通过 createServerFn,变更的 mutationFn 调用对应 *Fn。服务端组件为实验性可选 RSC 层,并非默认数据路径。项目专有路径请参考仓库本地 docs/ 文件。