zustand_skill

Overview

This skill is a practical guide for implementing and maintaining Zustand stores in a TypeScript codebase. It focuses on clear action hierarchies, naming conventions, optimistic updates, and when to use reducers versus simple set operations. Use it to standardize state logic across store files and slices under src/store/**.

How this skill works

The guide defines three action layers: public actions for UI-facing flows, internal actions for core business logic and optimistic updates, and dispatch methods that perform reducers and direct state mutations. It explains patterns for optimistic creation, when to avoid optimistic deletes, and how to organize state as maps, ID arrays, and flags. Concrete naming rules and examples help you implement consistent, testable store code.

When to use it

• When creating or updating Zustand stores and slices under src/store/**
• When implementing UI-facing actions that require validation or orchestration
• When writing internal business logic that needs optimistic updates or service calls
• When deciding whether to use reducer patterns for lists/maps or simple set for primitives
• When adding loading or editing state tracked by ID arrays or maps

Best practices

• Split actions into public (UI), internal (business logic), and dispatch (state mutations)
• Use reducer pattern for lists/maps and optimistic updates; use set for booleans and single fields
• Prefix internal methods with internal_ and dispatch handlers with internal_dispatch for clarity
• Avoid optimistic deletes; perform server-confirmed deletions and then refresh state
• Track transient states with ID arrays (e.g., messageLoadingIds) and maps (e.g., messagesMap)

Example use cases

• Implementing createTopic: perform optimistic add with tmpId, call backend, then refresh
• Sending a message: public sendMessage validates input, internal action handles optimistic UI and error recovery
• Toggling loading state for a message using internal_toggleMessageLoading and messageLoadingIds
• Managing topic lists with topicMaps and topicsInit using reducer-style dispatches
• Updating message content via internal_updateMessageContent with a reducer-driven update