用途:说明如何把 TanStack DB 接入各类元框架(TanStack Start、Next.js、Remix、Nuxt、SvelteKit),属于客户端读取路径的集成指南,需先阅读 db-core 了解集合创建与查询构建器。
主要能力与用法:TanStack DB 集合仅限客户端,未实现 SSR,使用它的路由必须禁用 SSR。通用模式为:在路由上设置 ssr: false;在路由 loader 中调用 collection.preload();在组件中使用 useLiveQuery。TanStack Start 可全局关闭 SSR(defaultSsr: false)或按路由关闭,并可在 loader 中用 Promise.all 预加载多个集合。Next.js App Router 组件须为客户端组件('use client'),无服务端预加载,集合在挂载时同步,也可在模块加载时触发 preload。Remix 使用 clientLoader 预加载并让 loader 返回 null。Nuxt 用 <ClientOnly> 包裹组件。SvelteKit 可判断 browser 环境或设置 ssr = false。
preload() 会启动同步,返回在集合就绪时解析的 Promise;已就绪的集合再次调用会立即返回。集合应定义在共享模块中作为单例,供 loader 与组件共用。
限制:本技能只覆盖客户端读取路径;服务端相关(Electric 代理路由、变更端点与 txid 握手)需参考 Electric 适配器文档。常见错误包括:启用 SSR 导致 loader 在服务端运行而挂起或报错;忘记在 loader 中预加载导致加载闪烁;为同一数据创建多个集合实例造成重复同步与状态不一致。框架专属 hook 用法见各框架 DB 技能文档。