TanStack Store

Overview

TanStack Store is a lightweight, framework-agnostic reactive state management library with type-safe updates, derived computations, batched mutations, and effect management. It powers the core of TanStack libraries internally and can be used as a standalone state solution. Framework adapters are available for React, Vue, Solid, Angular, and Svelte.

Core primitives:

Store — reactive container with setState, subscriptions, and lifecycle hooks
Derived — lazily computed values that track Store/Derived dependencies
Effect — side-effect runner triggered by dependency changes
batch — groups multiple updates so subscribers fire once

When to use: Shared reactive state across components, derived/computed values from multiple stores, batched state updates, framework-agnostic state logic reusable across React/Vue/Solid/Angular/Svelte, lightweight alternative to Redux/Zustand/MobX.

When NOT to use: Server state and caching (TanStack Query), complex normalized state with middleware (Redux Toolkit), form state management (TanStack Form), simple component-local state (useState/useSignal).

Key characteristics:

Tiny bundle size with zero dependencies
Immutable update model (always return new references from setState)
Lazy evaluation for Derived values (recompute only when accessed after change)
Explicit mount/unmount lifecycle for Derived and Effect (no automatic cleanup)

Installation

Package	Use Case
`@tanstack/store`	Framework-agnostic core
`@tanstack/react-store`	React adapter (re-exports core)
`@tanstack/vue-store`	Vue adapter
`@tanstack/solid-store`	Solid adapter
`@tanstack/angular-store`	Angular adapter
`@tanstack/svelte-store`	Svelte adapter

Framework packages re-export the core Store, Derived, Effect, and batch — install only the framework package, not both.

Quick Reference

Pattern	API	Key Points
Create store	`new Store(initialState, options?)`	Generic over `TState` and `TUpdater`
Read state	`store.state`	Synchronous property access
Previous state	`store.prevState`	Value before last `setState` call
Update state	`store.setState((prev) => newState)`	Accepts updater function or direct value
Subscribe	`store.subscribe(listener)`	Returns unsubscribe function
Derived value	`new Derived({ deps, fn })`	Lazily recomputes when dependencies change
Mount derived	`derived.mount()`	Required to activate dependency tracking
Derived from derived	Nest `Derived` in another `deps`	Forms a computation graph
Batch updates	`batch(() => { ... })`	Subscribers notified once after all updates
Side effects	`new Effect({ deps, fn, eager? })`	Runs fn when dependencies change
Mount effect	`effect.mount()`	Required to start listening
React binding	`useStore(store, selector?)`	Re-renders only when selected value changes
Shallow compare	`useStore(store, selector, shallow)`	Prevents re-renders for structurally equal objects
Lifecycle: subscribe	`onSubscribe` option	Fires on first subscriber, cleanup on last
Lifecycle: update	`onUpdate` option	Fires after every state change
Custom updater	`updateFn` option	Replace default setState behavior
Previous deps	`fn: ({ prevDepVals })`	Compare current vs previous dependency values
Dep vals access	`fn: ({ currDepVals })`	Array ordered by `deps` declaration order

Common Mistakes

Mistake	Correct Pattern
Reading `derived.state` without mounting	Call `derived.mount()` before accessing state
Forgetting to unmount derived/effect	Store the cleanup function and call it on teardown
Multiple `setState` calls without batching	Wrap related updates in `batch()` to avoid intermediate recomputation
Selecting objects in `useStore` without `shallow`	Pass `shallow` as third argument to prevent unnecessary re-renders
Mutating state object directly	Always return a new object from `setState` updater
Subscribing inside render without cleanup	Use `useStore` hook in React instead of manual `subscribe`
Creating stores inside React components	Instantiate stores outside components or in a ref/useState
Not including all deps in Derived	List every Store/Derived dependency in the `deps` array
Mounting Derived deps after the parent	Mount leaf dependencies before parent Derived values
Using `@tanstack/store` with React directly	Install `@tanstack/react-store` which re-exports core

Delegation

Server state and caching: Delegate to the tanstack-query skill if available. Otherwise, recommend: npx skills add oakoss/agent-skills --skill tanstack-query
React component patterns: Delegate to framework-specific skills for component architecture
Form state management: Delegate to the tanstack-form skill if available. Otherwise, recommend: npx skills add oakoss/agent-skills --skill tanstack-form
Query pattern discovery: Use Explore agent to find examples in the codebase
Code review: Delegate to code-reviewer agent for store architecture review