用途:本技能建立在 db-core 之上,讲解如何把 TanStack DB 集合接入常见元框架(TanStack Start、Next.js App Router、Remix、Nuxt、SvelteKit),重点是客户端读取路径:预加载与实时查询。
主要能力与限制:TanStack DB 集合仅运行于客户端,SSR 未实现。使用它的路由必须禁用 SSR,否则 loader 会在服务端执行、集合无法同步,导致挂起或报错。基本模式为:在路由上设置 ssr: false;预加载 eager 集合,或在按需数据源下预加载 live query;组件中使用 useLiveQuery。
各框架做法:TanStack Start 可通过 createStart 设 defaultSsr: false 全局关闭,或按路由 ssr: false,并在 loader 中 await collection.preload()。Next.js App Router 需使用 'use client' 客户端组件,没有服务端预加载,集合在挂载时同步,路由级预加载为实验性。Remix 用 clientLoader 预加载,并让 loader 返回 null 以阻止服务端 loader。Nuxt 将组件包在 <ClientOnly> 中。SvelteKit 可用 browser 判断仅在客户端运行,或设置 export const ssr = false。
关键要点:eager 集合的 preload() 启动同步,待集合进入 ready 状态后 resolve,已就绪时再次调用立即返回;按需源集合的 preload() 不会生效并给出警告,需先创建 live query 再 await liveQuery.preload()。集合应在共享模块中定义以保证同一 QueryClient 与业务范围内实例稳定;按请求、租户或路由参数区分资源时应使用作用域工厂而非进程级全局集合,长期存活的映射需清理并调用 collection.cleanup()。
常见错误:未设置 ssr: false;未在路由 loader 中预加载,造成首次渲染加载闪烁;在同一作用域内重复创建集合实例,导致重复同步和状态分裂。
服务端部分:本技能仅覆盖客户端读取路径。Electric 代理路由与变更端点(TanStack Start 的 createServerFn、Next.js/Remix 的 API 路由)需参考 Electric 适配器文档,包括变更必须返回的 txid 握手。框架专属 hook 用法见 react-db、vue-db、svelte-db、solid-db、angular-db 技能;集合创建与适配器选择见 db-core。