SuperAPI AI 工具集

nextjs-tanstack-query

前端与建站

查看项目

更新于 10-16 05:48

技能介绍

用途:该技能面向 Next.js 16 与 TanStack Query v5 的集成,专注客户端缓存层,处理客户端数据获取与缓存重验证、服务端预取并注水到客户端、变更的乐观更新、无限滚动与分页、实时数据同步。不覆盖 Server Component 边界本身,也不涉及 Next.js 核心缓存原语(如 use cache)。

主要能力:服务端预取让首屏即有数据、避免加载闪烁;自动缓存去重与 stale-while-revalidate;变更支持乐观更新与出错回滚;DevTools 可视化缓存检查;TypeScript 类型推断。

关键规则:每个请求一个 QueryClient,在 Server Component 中创建并通过 context 共享;在 Server Component 中用 prefetchQuery 预取;必须用 HydrationBoundary 包裹客户端树以传递服务端缓存;查询键必须可序列化,仅用字符串/数字数组;预取的查询要设置 staleTime 以避免挂载后立即重新获取;客户端组件中不要直接使用 queryClient,改用 hooks。

安装:bun add @tanstack/react-query @tanstack/react-query-devtools

最佳实践:服务端预取关键数据;设置 staleTime;查询键就近定义;写入后用 invalidateQueries 失效缓存;关键查询用 throwOnError 配合错误边界;DevTools 仅在开发环境启用,用 process.env.NODE_ENV 判断。

工作流要求:实现前并行启动三个 agent(探索代码库、核对最新 v5 文档、查询 TanStack Query 与 Next.js 模式),实现后运行验证。

限制:资料未提供具体版本兼容细节、性能数据或收费信息。