TanStack Store 是一个轻量、框架无关的响应式状态管理库,支持类型安全更新、派生计算、批量变更与副作用管理,是 TanStack 各库的内部核心,也可独立作为状态方案使用,并为 React、Vue、Solid、Angular、Svelte 提供适配器。
核心原语包括:Store(带 setState、订阅和生命周期钩子的响应式容器)、Derived(惰性计算并追踪 Store/Derived 依赖的值)、Effect(依赖变化时触发的副作用执行器)、batch(合并多次更新,使订阅者只触发一次)。
适用场景:组件间共享响应式状态;由多个 store 派生计算值;批量状态更新;可跨 React/Vue/Solid/Angular/Svelte 复用的框架无关状态逻辑;作为 Redux/Zustand/MobX 的轻量替代。不适用场景:服务端状态与缓存(用 TanStack Query)、带中间件的复杂规范化状态(Redux Toolkit)、表单状态管理(TanStack Form)、简单的组件本地状态(useState/useSignal)。
主要特点:体积极小且零依赖;不可变更新模型(setState 始终返回新引用);Derived 惰性求值;Derived 与 Effect 需显式 mount/unmount,无自动清理。
安装:核心用 @tanstack/store;各框架用 @tanstack/react-store、@tanstack/vue-store、@tanstack/solid-store、@tanstack/angular-store、@tanstack/svelte-store。框架包会重新导出核心的 Store、Derived、Effect 和 batch,只装框架包即可,无需两者都装。
常用 API:new Store(initialState, options?) 创建;store.state 读取;store.prevState 取上次 setState 前的值;store.setState((prev) => newState) 更新;store.subscribe(listener) 订阅并返回取消订阅函数;new Derived({ deps, fn }) 创建派生值;derived.mount() 激活依赖追踪;batch(() => { ... }) 批量更新;new Effect({ deps, fn, eager? }) 创建副作用;effect.mount() 开始监听。React 中用 useStore(store, selector?),第三参数传 shallow 可避免结构相等对象的重复渲染。生命周期选项包括 onSubscribe、onUpdate、updateFn。
常见错误与正确做法:读取 derived.state 前需先 mount;派生值/副作用需保存清理函数并在卸载时调用;相关多次 setState 应包在 batch() 中;useStore 选择对象时传 shallow;始终从 setState 返回新对象而非直接修改;React 中优先用 useStore 而非手动订阅;store 应创建在组件外部或 ref/useState 中;Derived 的 deps 要列全所有依赖;先挂载叶子依赖再挂载父级 Derived;在 React 中直接使用 @tanstack/store 应改为安装 @tanstack/react-store。
相关主题可委托:服务端状态与缓存用 tanstack-query 技能,表单状态用 tanstack-form 技能,组件架构与代码审查可交给相应框架技能或评审代理。