TanStack Store Skill / Design

[G3NTs]

I have been using tanstack store now for a few months and I absolutely love it.
I created an devtools tool for it that fits straight into the devtools widget, and have very strict store design for all my components.

THANK U TANSTACK DEVS for creating an amazing tool!

I have basically created an store base class, which my stores now inherits.
There are still some issues with hot reload, but so far this workflow feels so much better then zustand. I very much appreciate I can make classes rather then pure functional declarations.

import { Store } from '@tanstack/react-store'
import type { ID, StoreBase, StoreState, WithID } from './base.types'

export class BaseStore<T extends StoreBase> extends Store<StoreState<T>> {
    readonly #initial: StoreState<T>

    constructor(initial: StoreState<T> = {} as StoreState<T>) {
        super(initial)
        this.#initial = initial
    }

    get(): StoreState<T> {
        return this.state
    }

    set(next: StoreState<T> | ((prev: StoreState<T>) => StoreState<T>)): void {
        this.setState(prev =>
            typeof next === 'function' ? next(prev) : next
        )
    }

    reset(): void {
        this.setState(() => this.#initial)
    }

    insert(item: T): void {
        const { id, ...data } = item
        this.setState(prev => {
            if (prev[id as ID]) return prev
            return { ...prev, [id]: data as Omit<T, 'id'> }
        })
    }

    update(item: WithID<T>): void {
        const { id, ...data } = item
        this.setState(prev => {
            if (!prev[id as ID]) return prev
            return { ...prev, [id]: { ...prev[id as ID], ...data } as Omit<T, 'id'> }
        })
    }

    upsert(item: WithID<T>): void {
        const { id, ...data } = item
        this.setState(prev => ({
            ...prev,
            [id]: { ...prev[id as ID], ...data } as Omit<T, 'id'>,
        }))
    }

    remove(id: ID): void {
        this.setState(prev => {
            if (!prev[id]) return prev
            const { [id]: _, ...rest } = prev
            return rest as StoreState<T>
        })
    }

    insertMany(items: T[]): void {
        this.setState(prev => {
            const next = { ...prev }
            for (const item of items) {
                const { id, ...data } = item
                if (!next[id as ID]) next[id as ID] = data as Omit<T, 'id'>
            }
            return next
        })
    }

    updateMany(items: WithID<T>[]): void {
        this.setState(prev => {
            const next = { ...prev }
            for (const item of items) {
                const { id, ...data } = item
                if (!next[id as ID]) continue
                next[id as ID] = { ...next[id as ID], ...data } as Omit<T, 'id'>
            }
            return next
        })
    }

    upsertMany(items: WithID<T>[]): void {
        this.setState(prev => {
            const next = { ...prev }
            for (const item of items) {
                const { id, ...data } = item
                next[id as ID] = { ...next[id as ID], ...data } as Omit<T, 'id'>
            }
            return next
        })
    }

    removeMany(ids: ID[]): void {
        this.setState(prev => {
            const next = { ...prev }
            for (const id of ids) delete next[id]
            return next
        })
    }
}

I can then inherit it.

import { BaseStore } from '@/stores/base.store'
import type { ID, StoreState, WithID } from '@/stores/base.types'
import type { Activity } from './activity.types'

class ActivityStore extends BaseStore<Activity> {
    constructor() { super() }

    get(): StoreState<Activity> { return super.get() }
    set(next: StoreState<Activity> | ((prev: StoreState<Activity>) => StoreState<Activity>)): void { super.set(next) }
    reset(): void { super.reset() }

    insert(item: Activity): void { super.insert(item) }
    update(item: WithID<Activity>): void { super.update(item) }
    upsert(item: WithID<Activity>): void { super.upsert(item) }
    remove(id: ID): void { super.remove(id) }

    insertMany(items: Activity[]): void { super.insertMany(items) }
    updateMany(items: WithID<Activity>[]): void { super.updateMany(items) }
    upsertMany(items: WithID<Activity>[]): void { super.upsertMany(items) }
    removeMany(ids: ID[]): void { super.removeMany(ids) }
}

export const activityStore = new ActivityStore()

And then I have all of my businesslogic selectors, and mutations in separate files for them.

here is the skill

---

name: tanstack-store
description: >
Use this skill when working with any state store in this project. Triggers include:
creating a new store, adding or modifying store operations, writing selectors or mutations,
working with the appState aggregation system, or handling stores that wrap non-serializable
refs (e.g. Three.js scene objects). Covers the full file structure, store class pattern,
operation semantics, separation of concerns, and the cache-object pattern for ref-backed stores.

TanStack Store Skill

Stack

• State library: @tanstack/store
• Pattern: OOP class extending BaseStore<T> — not functional
• User settings: appSettings.store
• Aggregation: appState.store (single entry/exit point for save/load)

---

File Structure

Every store lives under src/stores/<storeName>/ and exports through index.ts:

src/stores/<storeName>/
  <storeName>.store.ts        → CRUD primitives only
  <storeName>.mutations.ts    → business logic & orchestration
  <storeName>.selectors.ts    → pure derived state
  <storeName>.io.ts           → input output system, initialization, persistence, external sync
  <storeName>.types.ts        → types & enums
  index.ts                    → re-exports

---

Responsibilities

File	Role	Rules
*.store.ts	Primitive state ops	No business logic, no async, no side effects
*.selectors.ts	Derived / computed data	Pure functions, no mutations
*.mutations.ts	Business logic, orchestration	Use store ops only — never mutate state directly
*.io.ts	Side effects, persistence	Never mutate state directly; go through store ops or mutations

---

Types Pattern

// stores/base.types.ts

export type ID = string & { readonly _brand: 'ID' }

export type StoreBase = {
  id: ID         // id is both the Record key AND an accessible field on the object
  label: string  // human-readable identifier, queryable via selectByLabel
}

export type WithID<T extends StoreBase> = Partial<T> & Pick<T, 'id'>

export type StoreState<T extends StoreBase> = Record<ID, Omit<T, 'id'>>

// stores/<storeName>/<storeName>.types.ts

export type AppSettings = StoreBase & {
  theme: Theme
  language: string
}

export type AppSettingsState = StoreState<AppSettings>

Rules:

• id is always string, stable, and unique. Can be URIs or UUIDs, but must be consistent and never change for the same entity.
• Collections are normalized as Record<ID, Omit<T, 'id'>>
• State must be fully serializable (no class instances, no refs — except cache-object stores, see below)
• Enums live in *.types.ts

---

Store Class Pattern

BaseStore<T> lives in src/stores/base.store.ts and provides all CRUD ops. Every store extends it and scaffolds all methods with super calls — this makes extension points explicit and easy to find.

// <storeName>.store.ts
import { BaseStore } from '@/stores/base.store'
import type { ID, StoreState, WithID } from '@/stores/base.types'
import type { MyEntity } from './<storeName>.types'

class MyEntityStore extends BaseStore<MyEntity> {
  constructor() { super() }

  get(): StoreState<MyEntity> { return super.get() }
  set(next: StoreState<MyEntity> | ((prev: StoreState<MyEntity>) => StoreState<MyEntity>)): void { super.set(next) }
  reset(): void { super.reset() }

  insert(item: MyEntity): void { super.insert(item) }
  update(item: WithID<MyEntity>): void { super.update(item) }
  upsert(item: WithID<MyEntity>): void { super.upsert(item) }
  remove(id: ID): void { super.remove(id) }

  insertMany(items: MyEntity[]): void { super.insertMany(items) }
  updateMany(items: WithID<MyEntity>[]): void { super.updateMany(items) }
  upsertMany(items: WithID<MyEntity>[]): void { super.upsertMany(items) }
  removeMany(ids: ID[]): void { super.removeMany(ids) }
}

export const myEntityStore = new MyEntityStore()

Rules:

• Always scaffold all methods with super calls — never leave the class body empty
• read is not defined — use selectors instead
• setState must only be called inside base.store.ts — never in subclasses
• All ops are pure and deterministic
• No validation, no async, no orchestration inside the store class

Operation Semantics

Op	Behaviour
insert	Add new item; no-op if id already exists
update	Shallow-merge into existing item; no-op if id missing
upsert	Insert or shallow-merge; always writes
remove	Delete by id; no-op if missing
*Many	Batched equivalent of each single op, in one setState call

---

Selectors Pattern

When indexing StoreState<T> (which is Record<ID, ...>) with a plain string, cast to ID:

// <storeName>.selectors.ts
import type { ID } from '@/stores/base.types'
import { myEntityStore } from './<storeName>.store'
import type { MyEntity } from './<storeName>.types'

export const selectById = (id: string): MyEntity | undefined => {
  const entry = myEntityStore.state[id as ID]
  return entry ? { id: id as ID, ...entry } : undefined
}

export const selectAll = (): MyEntity[] =>
  Object.entries(myEntityStore.state).map(([id, data]) => ({ id: id as ID, ...data }))

export const selectByLabel = (label: string): MyEntity | undefined =>
  selectAll().find(item => item.label === label)

Rules: Pure functions. No mutations. No side effects. May read from multiple stores.

---

Mutations Pattern

// <storeName>.mutations.ts
import { myEntityStore } from './<storeName>.store'
import type { ID } from '@/stores/base.types'

export const doSomething = (id: ID, value: string): void => {
  myEntityStore.update({ id, someField: value })
  // sync to appState or trigger related stores if needed
}

Rules: Calls store methods only. No direct state mutation. No async / IO.

---

IO Pattern

// <storeName>.io.ts
import type { ID } from '@/stores/base.types'
import { myEntityStore } from './<storeName>.store'
import type { MyEntity } from './<storeName>.types'

export const loadFromAPI = async (): Promise<void> => {
  const data: MyEntity[] = await fetch('/api/<storeName>').then(r => r.json())
  myEntityStore.upsertMany(data)
}

Rules: All side effects and async live here. Parse and validate external data (e.g. with Zod) before passing to the store. Never access setState directly.

---

appState — Aggregation Store

appStateStore is the single entry/exit point for persisting or hydrating all stores.
Every serializable store must be registered here to participate in save/load.

Registering a new store

// appState.mutations.ts
import type { ID } from '@/stores/base.types'
import { myEntityStore } from '../<storeName>'
import { appStateStore } from './appState.store'
import { toStoreRef } from './appState.types'

export const stores = {
  myEntity: myEntityStore,
  // add future stores here — skip non-serializable cache stores
} as const

export const registerStores = (): void => {
  for (const [id, store] of Object.entries(stores)) {
    appStateStore.insert({ id: id as ID, label: id, store: toStoreRef(store) })
  }
}

toStoreRef wraps any object that implements get(): unknown and set(next: any): void — satisfied by all BaseStore instances.

Save / Load (appState.io.ts)

export const saveToCookie = (name: string): void => { ... }
export const loadFromCookie = (name: string): void => { ... }
export const listPresets = (): string[] => { ... }

IO iterates appStateStore.state, calls store.ref.get() for export and store.ref.set(data) for import.

---

Cache-Object Store (Ref-backed Objects)

Use this pattern when a store manages state for anything that lives inside the 3D scene (e.g. Three.js meshes, cameras, WebGL contexts) that should not trigger re-renders on internal property changes.

Cache stores extend CacheStore rather than BaseStore.

How it works

The store holds a cache object — a plain object of values stored by reference. Mutations happen directly on the object in place, bypassing setState and store subscriptions. Only replacing the entire cache object triggers a store update. 3D scene objects access this data by reference, so they see mutations immediately without causing re-renders.

Since the cache object contains only plain values, it is fully serializable and can be registered in appStateStore like any other store.

Types

// base.types.ts (additions)

export type CacheBase<TCache extends object> = StoreBase & {
  cache: TCache
}

export type CacheState<T extends CacheBase<object>> = Record<ID, Omit<T, 'id'>>

export type WithCacheID<T extends CacheBase<object>> = Partial<T> & Pick<T, 'id'>

// <storeName>.types.ts
import type { CacheBase, CacheState } from '@/stores/base.types'

type MyCache = {
  pos: [number, number, number]
  rot: [number, number, number]
  scale: [number, number, number]
}

export type MyEntity = CacheBase<MyCache>

export type MyEntityState = CacheState<MyEntity>

Per-store example

Same scaffolding convention as BaseStore — all methods explicit with super calls:

// <storeName>.store.ts
import { CacheStore } from '@/stores/base.cache-store'
import type { CacheState, ID, WithCacheID } from '@/stores/base.types'
import type { MyEntity } from './<storeName>.types'

class MyEntityStore extends CacheStore<MyEntity> {
  constructor() { super() }

  get(): CacheState<MyEntity> { return super.get() }
  set(next: CacheState<MyEntity> | ((prev: CacheState<MyEntity>) => CacheState<MyEntity>)): void { super.set(next) }
  reset(): void { super.reset() }
  getCache(id: ID): Omit<MyEntity, 'id'> | undefined { return super.getCache(id) }

  insert(item: MyEntity): void { super.insert(item) }
  replace(item: MyEntity): void { super.replace(item) }
  remove(id: ID): void { super.remove(id) }

  insertMany(items: MyEntity[]): void { super.insertMany(items) }
  replaceMany(items: MyEntity[]): void { super.replaceMany(items) }
  removeMany(ids: ID[]): void { super.removeMany(ids) }

  update(item: WithCacheID<MyEntity>): void { super.update(item) }
  upsert(item: WithCacheID<MyEntity>): void { super.upsert(item) }
  updateMany(items: WithCacheID<MyEntity>[]): void { super.updateMany(items) }
  upsertMany(items: WithCacheID<MyEntity>[]): void { super.upsertMany(items) }
}

export const myEntityStore = new MyEntityStore()

When to use each op

Op	Re-render?	Behaviour
insert	✅ Yes	Adds new entry; no-op if id exists
replace	✅ Yes	Swaps entire cache object; no-op if id missing
remove	✅ Yes	Removes entry; no-op if id missing
update	❌ No	Shallow-merges into cache in place; no-op if id missing
upsert	❌ / ✅	Mutates in place if exists; inserts (re-render) if not
getCache	❌ No	Returns cache object for direct mutation
*Many	same as single	Batched equivalent of each op

---

Checklist: Adding a New Store

Standard store:

• Create src/stores/<storeName>/ with all 6 files
• *.types.ts — extend StoreBase, define state type via StoreState<T>, add enums
• *.store.ts — extend BaseStore<T>; scaffold all methods with super calls
• *.selectors.ts — pure derived data; always include selectById, selectAll, selectByLabel; cast string to ID when indexing state
• *.mutations.ts — business logic; call store methods only, no async
• *.io.ts — async, persistence, external sync; validate external data before passing to store; cast string IDs to ID before calling store ops
• index.ts — re-export store instance, selectors, mutations, IO
• Register in appState.mutations.ts → stores
• Register store to the dev-tools

Cache store:

• Create src/stores/<storeName>/ with all 6 files
• *.types.ts — define cache shape, extend CacheBase<TCache>, define state type via CacheState<T>
• *.store.ts — extend CacheStore<T>; scaffold all methods with super calls
• *.selectors.ts — pure derived data; always include selectById, selectAll, selectByLabel; cast string to ID when indexing state
• *.mutations.ts — use getCache(id) for in-place mutations; use store ops for structural changes
• *.io.ts — async, persistence, external sync; validate external data before passing to store
• index.ts — re-export store instance, selectors, mutations, IO
• Register in appState.mutations.ts → stores
• Register store to the dev-tools