用途:为 TanStack Router 应用提供手动服务端渲染能力,适用于需要与既有服务器集成的场景。资料明确说明 SSR API 处于实验阶段,与 TanStack Start 共享内部实现,可能变更;生产环境推荐使用 TanStack Start,仅在集成现有服务器时才手动搭建 SSR。
主要能力:支持两种 SSR 形态——非流式(服务端渲染完整页面后作为单个 HTML 响应发送,客户端再水合)与流式(优先发送首屏关键内容,其余内容随解析逐步流式输出)。服务端自动使用内存历史(无 window),loader 数据自动脱水/水合,序列化原生支持 Date、Error、FormData 和 undefined。提供 createRequestHandler、defaultRenderHandler、defaultStreamHandler、renderRouterToString、renderRouterToStream、RouterServer、RouterClient 等 API 与组件,以及用于文档 head 管理(title、meta、link、style)的 head 路由选项、HeadContent、Scripts 和 ScriptOnce。
使用方式:需在服务端与客户端导出同一个路由工厂函数;服务端入口用 createRequestHandler 配合 defaultRenderHandler 或 renderRouterToString,客户端入口用 hydrateRoot 搭配 RouterClient。流式场景使用 defaultStreamHandler 或 renderRouterToStream,延迟数据与流式标记会自动处理。根路由通过 head 配置标签,在 head 渲染 HeadContent、在 body 渲染 Scripts;SPA 可在组件树顶部渲染 HeadContent。Express 集成需在 Web API Request/Response 与 Express 请求响应之间做格式转换。
限制:TanStack Router 是客户端优先的,loader 默认在客户端运行,启用 SSR 后在客户端和服务端都会运行,并非服务端专属;因此不应在 loader 中直接访问数据库,也不应使用未做环境判断的浏览器 API;基于 hash 的条件渲染会造成水合不匹配;文档特别提醒不要套用 Next.js、Remix 或 react-router-dom 的写法与文件结构。其余具体配置细节资料未完整提供。