Provides architectural patterns and best practices for implementing Zustand stores in React applications.

Install

mkdir -p .claude/skills/zustand && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/626" && unzip -o skill.zip -d .claude/skills/zustand && rm skill.zip

Installs to .claude/skills/zustand

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

LobeHub Zustand store conventions. Use when editing src/store, store slices, public/internal actions, dispatch actions, flattenActions, optimistic updates, selectors, maps, or class action migration.
199 chars✓ has a “when” trigger
Intermediate

Key capabilities

  • →Differentiate between public and internal action logic
  • →Implement optimistic update patterns for UI responsiveness
  • →Organize state into maps and ID arrays for lookup efficiency
  • →Decouple state dispatchers from business logic functions

How it works

Applies a structured hierarchy of public actions, internal logic functions, and dispatchers to maintain separation of concerns within a store.

Inputs & outputs

You give it
State slice definitions and business action requirements
You get back
Zustand store implementation code with typed actions

When to use zustand

  • →Implement complex state slices
  • →Apply optimistic update patterns
  • →Migrate class-based actions to store functions
  • →Define internal versus public dispatch methods

About this skill

LobeHub Zustand State Management

State Shapes and Types

  • Import shared store types from @lobechat/types, not @lobechat/database.
  • Keep lightweight list-item types separate from full detail types; list types must not extend heavy detail types.
  • Key cached details by id (xxxDetailMap: Record<string, Detail>); never hold a single currentDetail object.
  • Read through xxxSelectors aggregates (selectors.ts), not ad-hoc lambdas repeated across components.
  • Before choosing list/detail shapes or type sources, read Data structures.

State-Only Stores (default for new and migrated stores)

Actions stay out of the Zustand state. Reference: src/store/page.

FileOwns
store.tsuseXStore = createWithEqualityFn<XState>()(devtools(() => initialState), shallow): state only, no methods
privateAction.tsXPrivateAction: replica slices, entity links, and write helpers shared by public actions. Not exported from index.ts
action.tsXActionImpl (the public API) and the singleton xActions = new XActionImpl(setState, getState, new XPrivateAction(…))
  • Components read state with useXStore(selector) and call xActions.foo() directly. Never select an action out of the store.
  • Sync hooks live on the public class and are called as xActions.useFetchX(params).
  • Public actions call each other through this.foo(). Private helpers are reached through this.#private. Do not add internal_* methods to the store to share logic between classes.
  • Label every write: this.#set(partial, false, n('actionName')) with const n = setNamespace('x').
  • Put reset() on the public class and register xActions in resetableActions in src/store/utils/userDataStores.ts.
  • Tests drive xActions and assert on useXStore.getState(). To mock in component tests: vi.mock('@/store/x', () => ({ xActions: { foo: vi.fn() }, useXStore: … })).

Replica-Backed Server Data

Server lists and details the UI paints go through @/libs/replica, not a hand-written SWR onSuccess + reducer. The engine owns hydration from IndexedDB, head revalidation, paging, optimistic overlays with rollback, and scope (user + workspace) isolation. API reference: packages/replica/README.md.

  1. Define the resource (defineReplica / definePagedReplica) in the store's projection.ts, converting server rows at the boundary.
  2. Add two state fields per replica: the view (xxxMap: Record<key, TData>) and its bookkeeping (xxxReplica: createReplicaState()).
  3. Bind it in the private class: createReplicaSlice(resource, { get, set, stateKey: 'xxxReplica', view: recordLens('xxxMap'), … }). When the same entity lives in several replicas (list row + detail), link them with linkReplicaEntity([list, detail]).
  4. Read: slice.useSync(params) returns only fetch flags (isHydrated, isValidating, error, revalidate). Data comes from selectors over xxxMap. "Entry is undefined" is the loading signal — do not add xxxInit flags or loadingXxxIds.
  5. Read with no view mounted (hover prefetch, refresh after a mutation): await slice.fetch(params) ({ fresh: true } after a write). Never call the service and slice.replace(...) by hand, because that skips the scope, removal, clear and superseded-request guards. Side effects of every response (not-found maps, seeding another store) go in the slice effects (onApplied / onMissing / onPurge / onError) with isMissing, not in one hook's onSuccess.
  6. Cold start without a skeleton: useSync hydrates only after the component mounts. For a list that must paint from the local copy, add a preHydrate action (ensureScope + hydrate) and call it from the route's loader through a lazy wrapper (src/spa/router/pageListLoader.ts, agentChatTopicListLoader.ts) bounded by PRE_PAINT_HYDRATE_TIMEOUT.
  7. Write: slice.optimistic(key, apply, serverCall) or entity.optimistic(id, fn | 'remove', serverCall). A failed call rolls back to the confirmed value, so deletes are optimistic too. Rows that exist only on the client (temp ids) are declared with isClientOnly and seeded with update(key, fn, { persist: false }).

Outside test seeding, write a replica's view only through its slice. A plain set bypasses the engine's bookkeeping (persistence, rollback base, entity links).

Legacy Stores

Stores that still flatten action classes into state (flattenActions, create*Slice, internal_*, internal_dispatch* + reducers, SWR onSuccess syncing) follow Legacy slices. Use that layout only when editing one of those stores; migrate to the layouts above when moving its data onto a replica.

When not to use it

  • →Managing simple local component state (use React.useState)
  • →High-frequency numerical computation outside of state updates

Prerequisites

Zustand libraryTypeScript environment

Limitations

  • →Strict naming conventions for internal vs public methods
  • →Requires manual state normalization for complex objects

How it compares

It follows specific LobeHub conventions for naming and action structure rather than generic state management patterns.

Compared to similar skills

zustand side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
zustand (this skill)1134moNo flagsIntermediate
react344moNo flagsIntermediate
react-component-patterns33moNo flagsIntermediate
zustand-589moNo flagsBeginner

Try saying

Example prompts that trigger this skill in your AI assistant.

drizzle

lobehub

Drizzle ORM schema and database guide. Use when working with database schemas (src/database/schemas/*), defining tables, creating migrations, or database model code. Triggers on Drizzle schema definition, database migrations, or ORM usage questions.

238873

react

lobehub

React component development guide. Use when working with React components (.tsx files), creating UI, using @lobehub/ui components, implementing routing, or building frontend features. Triggers on React component creation, modification, layout implementation, or navigation tasks.

3480

typescript

lobehub

TypeScript code style and optimization guidelines. Use when writing TypeScript code (.ts, .tsx, .mts files), reviewing code quality, or implementing type-safe patterns. Triggers on TypeScript development, type safety questions, or code style discussions.

2877

project-overview

lobehub

Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.

1548

linear

lobehub

Linear issue management guide. Use when working with Linear issues, creating issues, updating status, or adding comments. Triggers on Linear issue references (LOBE-xxx), issue tracking, or project management tasks. Requires Linear MCP tools to be available.

10117

desktop

lobehub

Electron desktop development guide. Use when implementing desktop features, IPC handlers, controllers, preload scripts, window management, menu configuration, or Electron-specific functionality. Triggers on desktop app development, Electron IPC, or desktop local tools implementation.

941

Search skills

Search the agent skills registry