TanStack Store
1. Establish the API generation and state owner
Read the installed core and adapter versions, lockfile resolutions, existing
store definitions, and consumers before choosing an API. This skill's modern
examples target core and React 0.11.1, verified on 2026-09-17. TanStack
still labels Store alpha; resolve newer or intermediate versions against their
installed declarations rather than assuming that all 0.x releases agree.
| Evidence in the project | Path |
|---|---|
| Core 0.11.1, React 0.11.1 | Use the modern examples below. |
| Core 0.9–0.10 | Signals rewrite, but newer adapter hooks may be absent; verify exports. |
Core through 0.8, explicit Derived / Effect |
Read legacy.md before changing code. |
| Multiple core versions, including transitive dependencies | Follow the package resolved by each consumer; retain unrelated library internals. |
Choose ownership before adding a store:
| State | Preferred owner |
|---|---|
| One component's temporary UI state | Framework-local state |
| Shared client-owned state or reactive calculations | TanStack Store |
| Shareable navigation, filters, pagination | Router URL/search state |
| Remote data, freshness, retries, mutations | Existing server-state cache, such as TanStack Query |
| Synchronized collections and relational live queries | Existing data layer, such as TanStack DB |
Finish this step with the resolved API generation, state owner, store lifetime, and affected consumers identified. Preserve the project's existing state layer unless the requested behavior needs a change.
2. Implement the state transition
createStore(value) creates writable state. setState(updater) replaces the
whole value with the updater's return value; it does not merge object fields.
Return new references along changed paths and retain unchanged branches.
import { createStore } from '@tanstack/store'
type Filters = {
query: string
status: 'all' | 'open' | 'closed'
}
export function createFiltersStore() {
const store = createStore<Filters>({ query: '', status: 'all' })
function setQuery(query: string) {
store.setState((state) =>
state.query === query ? state : { ...state, query },
)
}
return { store, setQuery }
}
Keep update functions pure and synchronous. Use an explicit state type for
unions, nullable values, and empty collections. Core change detection uses
Object.is; mutating an object and returning the same reference can suppress
notifications. A direct .state or .get() read returns a snapshot, not a UI
subscription.
Reuse ordinary action functions like the example. When the installed API and
project use createStore(initialValue, actionsFactory), actions are exposed
through .actions; this is optional, not a reason to restructure existing stores.
Finish when each requested transition preserves unrelated state and has one authoritative write path.
3. Derive and observe
createStore(getter) creates a readonly computed store. Reads of other stores
inside its synchronous getter establish dependencies automatically, including
conditional dependencies. Read dependencies inside the getter rather than
closing over snapshots read beforehand.
import { batch, createStore } from '@tanstack/store'
const price = createStore(10)
const quantity = createStore(2)
const total = createStore(() => price.state * quantity.state)
const observedTotals: number[] = []
const subscription = total.subscribe((value) => observedTotals.push(value))
batch(() => {
price.setState(() => 12)
quantity.setState(() => 3)
})
subscription.unsubscribe()
The final total is 36; the subscription receives that update, not an initial
value. Read .state separately when an initial snapshot is needed.
- Modern computed stores need no
.mount(). Keep getters pure: evaluation is lazy and subscription-driven, not an event log. A getter's optional previous value is the previous computation result, not a guarantee to process every write. subscribereceives the new value and returns{ unsubscribe }. Attach its cleanup to the owner's disposal/unmount lifecycle; use it for external effects.batchdelays notifications until the outermost synchronous batch ends. Writes still happen immediately; it is neither rollback nor an async transaction. After awaited work, batch only the synchronous writes that must notify together.- Store computations track Store reads, not arbitrary framework props. Bridge changing inputs explicitly through the existing framework integration.
Finish when derived values have no duplicated writable copy and every manual subscription has a cleanup owner.
4. Connect the framework and lifetime
- React selectors, component-owned stores, context, SSR, or persistence: read react.md. Subscribe to the slice rendered by the component.
- Other frameworks: inspect the adapter's official quick start and installed types. Vue refs, Solid accessors,
Svelte
.current, and Angular signals are different return contracts. - Legacy maintenance or an explicitly requested upgrade: read legacy.md; migrate lifecycle and consumers together.
- Atoms, async atoms, action factories, devtools, or disputed API behavior: inspect the installed implementation and matching official documentation before extending it. Verify exports; custom persistence and request caching are not implicit Store capabilities.
Finish when the store survives the intended renders, is disposed at the right boundary, and cannot leak request-specific state between server requests.
5. Validate the changed contract
Use the project's existing typecheck and nearest tests. Cover the paths changed:
- Consecutive updates use the latest state and preserve unrelated fields.
- A changed nested value gets new references; a no-op preserves its reference.
- Derived results update when active dependencies change, including branch switches.
- Batched writes expose the expected final notification; cleanup stops observation.
- A component reacts to its selected slice, including prop-dependent selectors; unrelated writes do not cause store-driven rerenders when selection is equal.
- Scoped instances remain independent; SSR hydration starts from matching data.
Report the resolved versions, checks run, and any untested runtime boundary.