Cursor rule

1---
2description: # Guidelines for Zustand Store
3globs: 
4alwaysApply: false
5---
6# Guidelines for Zustand Stores
7 
8## Purpose and Overview
9Zustand stores provide centralized state management with a simple API that doesn't require providers or complex setup. They are used to manage application state that needs to be accessed by multiple components, especially across different parts of the component tree. The stores in this project follow a consistent pattern using immer middleware for immutable state updates.
10 
11## Structure and Organization
12 
13### Store Module Structure
14```
15src/
16├── stores/                 # Shared stores module
17│   └── use-[entity]-store.ts  # Store for specific entity
18└── features/
19    └── [feature-name]/
20        └── _stores/        # Feature-specific stores
21            └── use-[entity]-store.ts  # Feature-specific store
22```
23 
24## Naming Conventions
25 
26### Files
27- `use-[entity]-store.ts`: For store files, use kebab-case
28 
29### Types
30- `[Entity]StoreState`: Type for store state
31- `[Entity]StoreActions`: Type for store actions
32- `[Entity]Store`: Combined type for state and actions
33- `DEFAULT_[ENTITY]_STORE_STATE`: Constant for default store state
34 
35### Functions
36- `use[Entity]Store`: The zustand hook for accessing the store
37 
38## Implementation Guidelines
39 
40### Store Creation
41- Use zustand with immer middleware for immutable updates
42- Separate state and actions with explicit types
43- Define a default state constant
44- Export the combined store type and hook
45 
46### State Management
47- Keep state minimal and focused on a specific domain
48- Use immer's state mutation syntax in actions
49- Avoid storing derived state that can be computed
50 
51### Example Store Implementation
52```typescript
53import { create } from 'zustand';
54import { immer } from 'zustand/middleware/immer';
55 
56// Define the state type
57export type CounterStoreState = {
58  count: number;
59};
60 
61// Define the actions type
62export type CounterStoreActions = {
63  increment: () => void;
64  decrement: () => void;
65  reset: () => void;
66  setCount: (count: number) => void;
67};
68 
69// Default state constant
70export const DEFAULT_COUNTER_STORE_STATE: CounterStoreState = {
71  count: 0,
72};
73 
74// Combined store type
75export type CounterStore = CounterStoreState & CounterStoreActions;
76 
77// Create and export the store hook
78export const useCounterStore = create(
79  immer<CounterStore>(set => ({
80    ...DEFAULT_COUNTER_STORE_STATE,
81 
82    /* Actions */
83    increment: () => {
84      set(state => {
85        state.count += 1;
86      });
87    },
88    decrement: () => {
89      set(state => {
90        state.count -= 1;
91      });
92    },
93    reset: () => {
94      set(state => {
95        state.count = DEFAULT_COUNTER_STORE_STATE.count;
96      });
97    },
98    setCount: (count) => {
99      set(state => {
100        state.count = count;
101      });
102    },
103  }))
104);
105```
106 
107### Example Store Test
108```typescript
109import { describe, it, expect, beforeEach } from 'vitest';
110import { useCounterStore, DEFAULT_COUNTER_STORE_STATE } from './use-counter-store';
111 
112describe('useCounterStore', () => {
113  beforeEach(() => {
114    useCounterStore.setState(DEFAULT_COUNTER_STORE_STATE);
115  });
116 
117  it('should initialize with default state', () => {
118    expect(useCounterStore.getState().count).toBe(0);
119  });
120 
121  it('should increment the count', () => {
122    useCounterStore.getState().increment();
123    expect(useCounterStore.getState().count).toBe(1);
124  });
125 
126  it('should decrement the count', () => {
127    useCounterStore.getState().increment();
128    useCounterStore.getState().decrement();
129    expect(useCounterStore.getState().count).toBe(0);
130  });
131 
132  it('should reset the count', () => {
133    useCounterStore.getState().increment();
134    useCounterStore.getState().reset();
135    expect(useCounterStore.getState().count).toBe(0);
136  });
137 
138  it('should set the count to a specific value', () => {
139    useCounterStore.getState().setCount(10);
140    expect(useCounterStore.getState().count).toBe(10);
141  });
142});
143```
144 
145## Best Practices
146 
147### Performance Considerations
148- Use selectors when accessing store values to prevent unnecessary re-renders
149- Keep the state structure flat when possible
150- Use multiple small, focused stores instead of one large store
151 
152### Accessing Stores in Components
153- Use selectors to extract only the state needed by a component
154```typescript
155// Good: Using a selector
156const count = useCounterStore(state => state.count);
157 
158// Avoid: Grabbing the entire state
159const { count } = useCounterStore();
160```
161 
162### Store Composition
163- For complex state management, consider composing multiple stores
164- Use separate stores for unrelated parts of the application state
165- Consider creating a store factory for related but separate instances
166 
167### Persistence
168- For persistent state, consider using zustand/middleware/persist
169- Define clear strategies for state rehydration
170- Handle loading states during rehydration
171 
172### TypeScript Integration
173- Always define explicit types for state and actions
174- Use discriminated unions for complex state transitions
175- Leverage TypeScript to ensure type safety throughout the application