TanStack Query Svelte v6 迁移指南：从 Stores 到 Runes 的完整升级实践-北京尧图网络

TanStack Query Svelte v6 迁移指南从 Stores 到 Runes 的完整升级实践【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query在 Svelte v5 中tanstack/svelte-queryv5 适配器仍然依赖 v3/v4 时代遗留的 stores 语法这在该适配器中一直存在不稳定与 bug。tanstack/svelte-queryv6 将适配器完全重写为基于 signals 的 Svelte 5 runes 语法同时把查询输入options统一改为 thunk() options形式彻底解决了响应式输入的历史难题。读完本文你将掌握从 v5 升级到 v6 的全部改动点安装与版本约束、函数签名变化、模板属性访问方式、响应式写法重构以及如何分文件或项目级地关闭 legacy 模式并理解这些 API 变化背后的 runes 源码实现原理。为什么要迁移Stores 兼容层的历史包袱Svelte v5 对 v3/v4 的 stores 语法提供了 legacy 兼容但这种兼容对tanstack/svelte-query这类需要精细控制订阅与响应式的适配器而言并不理想——文档明确指出它在该适配器中somewhat buggy and unreliable。因此 v6 适配器做出了两个关键决定全面迁移到 runes 语法所有内部实现基于$state、$derived、$effect等 runes底层依赖 Svelte 5 的 signals 机制。统一采用 thunk 形式接收 options与 Angular、Solid 适配器的模式保持一致用() options包裹配置让查询输入天然具备响应式。这次重写还简化了保证查询输入保持响应式所需的代码——在 v5 时代你往往需要derived甚至是writable与derived的组合来喂给createQuery而在 v6 中一个 thunk 即可。安装与版本要求在开始迁移前请先确认环境满足以下约束Svelte 版本项目必须使用 Sveltev5.25.0 或更新版本。这一点同时体现在 packages/svelte-query/package.json 的peerDependencies声明中svelte: ^5.25.0。安装命令执行pnpm add tanstack/svelte-querylatest或你使用的包管理器对应的等价命令。依赖关系注意tanstack/svelte-queryv6 依赖tanstack/query-corev5而非 v6。在当前仓库中这一依赖通过 packages/svelte-query/package.json 的dependencies字段tanstack/query-core: workspace:*声明包版本为6.1.48。函数输入全部改为 Thunk 形式v6 中适配器的大多数函数createQuery、createInfiniteQuery、createMutation、createQueries等都要求 options 以thunk即() options的形式传入。TypeScript 会在你遗漏这种写法时给出类型警告——类型系统中已把第一个参数明确为AccessorT。在 packages/svelte-query/src/types.ts 中可以看到这一核心类型定义export type AccessorT () T而 packages/svelte-query/src/createQuery.ts 的函数签名即采用该类型export function createQuery TQueryFnData unknown, TError DefaultError, TData TQueryFnData, TQueryKey extends QueryKey QueryKey, ( options: Accessor UndefinedInitialDataOptionsTQueryFnData, TError, TData, TQueryKey , queryClient?: AccessorQueryClient, ): CreateQueryResultTData, TErrorcreateInfiniteQuery、createMutation、createQueries的签名同样遵循此约定分别见 packages/svelte-query/src/createInfiniteQuery.ts、packages/svelte-query/src/createMutation.svelte.ts 与 packages/svelte-query/src/createQueries.svelte.ts。最基本的迁移改动如下-为旧写法为新写法- const query createQuery({ // 旧直接传对象 const query createQuery(() ({ // 新用 thunk 包裹 queryKey: [todos], queryFn: () fetchTodos(), - }) // 旧 })) // 新queryClient参数当你想覆盖最近 context 中的 QueryClient 时同样以AccessorQueryClient形式传递。仓库的测试 fixture 也印证了这一用法例如 packages/svelte-query/tests/createQuery/Base.svelte 中把options: AccessorCreateQueryOptions作为 props 传入并直接交给createQuery(options)。访问属性告别$前缀由于适配器不再基于 stores 暴露查询结果模板中不再需要对查询结果加$前缀。迁移时只需把模板里的$todos改为todos- {#if $todos.isSuccess} // 旧 {#if todos.isSuccess} // 新 ul - {#each $todos.data.items as item} // 旧 {#each todos.data.items as item} // 新 li{item}/li {/each} /ul {/if}查询结果对象本身仍然完整保留了 TanStack Query 惯用的字段如status、fetchStatus、data、error、isPending、isSuccess、isError、isFetching、isPlaceholderData等可在 packages/svelte-query/tests/createQuery/Base.svelte 中看到这些属性的实际渲染用法只是不再需要$解引用。从源码结构看结果是一个响应式引用createRawRef创建的容器见下文源码解析模板中直接读取其属性即可获得细粒度的响应式更新。响应式抛弃 derived / writable 的复杂包装这是本次迁移收益最大的部分。v5 时代为了让refetchInterval、queryKey等输入随状态变化你不得不做类似下面这种花式操作- const intervalMs writable(1000) // 旧writable store let intervalMs $state(1000) // 新runes 的 state - const query createQuery(derived(intervalMs, ($intervalMs) ({ // 旧derived 包装 const query createQuery(() ({ // 新直接 thunk queryKey: [refetch], queryFn: async () await fetch(/api/data).then((r) r.json()), - refetchInterval: $intervalMs, // 旧 refetchInterval: intervalMs, // 新 - }))) // 旧 })) // 新现在你甚至不需要把查询包在$derived里。thunk 内部会跟踪读取的所有响应式状态intervalMs这类$state变量、$props()传入的属性等当它们变化时适配器内部会自动重新计算 options 并通知 observer 更新。这也让代码从围绕 stores 打转回归到声明式地描述查询。在源码层面这一行为由 packages/svelte-query/src/createBaseQuery.svelte.ts 支撑它用$derived.by包裹options()的调用将 thunk 执行结果与响应式依赖绑定并在依赖变化时通过watchChanges见 packages/svelte-query/src/utils.svelte.ts以pre时机调用observer.setOptions(resolvedOptions)同步给底层 observer。确保启用 runes 模式禁用 Legacy 模式如果你的组件中还残留任何 stores 语法如writable、derived、$store引用Svelte 编译器可能不会把该组件切换到 runes 模式导致新写法无法生效。可以通过两种方式强制使用 runes按文件开启适合大型应用渐进式迁移在每一个已经完成迁移的.svelte文件顶部加上svelte:options runes{true} /这种方式允许你一个文件一个文件地迁移未迁移的文件仍可暂时使用旧语法。项目级全局开启适合彻底移除 stores 后当应用里已经 100% 消除了 stores 语法后在项目根目录的svelte.config.js中加入编译器选项export default { compilerOptions: { runes: true, }, // ...其余配置 }这样整个项目强制运行在 runes 模式下后续新代码无需再逐文件声明。源码深挖Runes 是如何支撑 v6 适配器的理解迁移背后的实现能让你在遇到边界情况时更快定位问题。createQuery与createInfiniteQuery都汇聚到 packages/svelte-query/src/createBaseQuery.svelte.ts 的createBaseQuery其核心流程如下获取 QueryClientconst client $derived(useQueryClient(queryClient?.()))其中useQueryClient见 packages/svelte-query/src/useQueryClient.ts在未显式传入时从 context 中取出最近的QueryClient。解析并追踪 optionsconst resolvedOptions $derived.by(() client.defaultQueryOptions(options()))——每次 thunk 读取的响应式依赖变化都会重新执行得到新 options。创建并维护 observerobserver 实例存放在$state中当client变化时通过watchChanges重建 observer。订阅与结果更新在$effect中订阅 observer用observer.subscribe(() update(createResult()))把新的查询结果写入由createRawRef见 packages/svelte-query/src/containers.svelte.ts创建的响应式容器中。options 热更新watchChanges(() resolvedOptions, pre, () observer.setOptions(resolvedOptions))在 DOM 更新前把新 options 推送给 observer保证重取/去重等逻辑基于最新配置执行。createMutationpackages/svelte-query/src/createMutation.svelte.ts走的是类似的 runes 路线用$state持有MutationObserver与结果$effect.pre同步 options并通过一个$derived的 Proxy 把mutate/mutateAsync暴露给结果对象同时兼容读取结果属性与result.value两种方式。createQueriespackages/svelte-query/src/createQueries.svelte.ts则用QueriesObserver批量管理多个查询同样接受 thunk 形式的{ queries, combine }输入并支持combine把结果合并为单一值。这些实现都建立在 packages/svelte-query/src/utils.svelte.ts 的watchChanges辅助函数之上——它内部用$effect/$effect.pre监听 getter 序列并在首次执行后、依赖变化时以untrack包裹回调实现只在变化时触发副作用的效果。整套机制不再涉及任何 Svelte store 的subscribe/set这正是 v6 稳定性的来源。迁移速查清单关注点v5Stores 时代v6Runes 时代options 传入方式直接传对象或derived(...)包装() ({ ... })thunk响应式状态writable(...)derived$state(...)无需$derived包裹查询模板访问$query.dataquery.data查询对象来源store 订阅响应式引用createRawRef容器运行模式legacy 兼容需启用 runes按文件或项目级底层依赖query-core v5query-core v5保持不变迁移完成后建议用 TypeScript 全程把关任何漏掉 thunk 包裹的调用都会在编译期收到Accessor类型不匹配的报错让迁移过程有据可依、可渐进推进。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

TanStack Query Svelte v6 迁移指南：从 Stores 到 Runes 的完整升级实践

相关推荐

数据中心废热回收全解析：从PUE到ERF的能源效率跃迁

CANN/GE UDF日志接口指南

上下文编排三要素：预算控制、结构化笔记与语义检索

更多资讯

T3 Code：面向AI编程Agent的统一控制台

TelegramBots终极版本迁移指南：从旧版本平滑升级到最新9.2.1

嵌入式开发入门指南：方向选择、学习路线与面试要点

CANN/GE DataFlow映射输入函数

TelegramBots未来展望：AI集成与智能对话的发展方向

GPT-6 Astra幻觉率2%仍被老招数绕过：大模型概率生成边界与工程防御指南

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？