# Component Design Standards for Zustand

This document outlines the coding standards for component design when using Zustand for state management in React applications. These standards promote reusability, maintainability, and performance, and are tailored for the latest Zustand features and best practices.

## 1. General Principles

### 1.1. Single Responsibility Principle (SRP)

* **Do This:** Design components so each has only one reason to change. For example, a component rendering user data shouldn't also handle authentication. Separate concerns into distinct components (some of which internally use zustand stores).

* **Don't Do This:** Create monolithic components handling multiple unrelated functionalities. This makes debugging and maintenance difficult.

* **Why:** SRP leads to more modular, testable, and understandable code. Changes in one area are less likely to impact unrelated parts of the application.

* **Example:**

"""jsx

// Good: Separate components for user data and profile update

const UserData = () => {

const userData = useStore(state => state.user);

return (

{userData.name}

{userData.email}

);

};

const UpdateProfile = () => {

const updateUser = useStore(state => state.updateUser);

const [name, setName] = React.useState('');

const handleSubmit = (e) => {

e.preventDefault();

updateUser({name});

}

return (

setName(e.target.value)} />

Update Name

);

};

"""

"""jsx

// Bad: A single component doing too much

const UserProfile = () => {

const userData = useStore(state => state.user);

const updateUser = useStore(state => state.updateUser);

const [name, setName] = React.useState('');

const handleSubmit = (e) => {

e.preventDefault();

//Also handles OTHER unrelated operations here. BAD.

updateUser({name});

}

return (

{userData.name}

{userData.email}

setName(e.target.value)} />

Update Name

);

};

"""

### 1.2. Separation of Concerns (SoC)

* **Do This:** Isolate distinct parts of your application (UI, state management, data fetching) into separate modules. Use custom hooks to abstract Zustand logic from components, promoting better SoC - especially for reading data. For mutations write discrete reusable setters in the zustand store.

* **Don't Do This:** Mix UI rendering logic directly with state management or data fetching within a single component.

* **Why:** SoC improves maintainability, testability, and reusability. It also makes it easier to understand and modify specific parts of the application.

* **Example:**

"""jsx

// Good: Custom hook for fetching and exposing user data

import create from 'zustand'; // Ensure you import create from zustand

const useUserStore = create((set) => ({

user: null,

fetchUser: async (id) => {

const response = await fetch("/api/users/${id}");

const data = await response.json();

set({ user: data });

updateUser: (newUserData) => set(state => ({ ...state, user: { ...state.user, ...newUserData } })),

}));

// User component consuming the hook

const UserProfile = () => {

const user = useUserStore(state => state.user);

const fetchUser = useUserStore(state => state.fetchUser);

React.useEffect(() => {

fetchUser(123); // Example user ID

}, [fetchUser]);

if (!user) {

return Loading user data...;

}

return (

{user.name}

{user.email}

);

};

"""

"""jsx

// Bad: Mixing data fetching and UI rendering

const UserProfileBad = () => {

const [user, setUser] = React.useState(null);

React.useEffect(() => {

const fetchUser = async (id) => {

const response = await fetch("/api/users/${id}");

const data = await response.json();

setUser(data);

};

fetchUser(123);

}, []);

if (!user) {

return Loading user data...;

}

return (

{user.name}

{user.email}

);

};

"""

### 1.3. Component Composition

* **Do This:** Favor composition over inheritance. Create smaller, focused components and combine them to build more complex UIs.

* **Don't Do This:** Create deep inheritance hierarchies, leading to inflexible and hard-to-understand code.

* **Why:** Composition provides more flexibility and reusability. It allows you to easily combine and rearrange components to create diverse UIs.

* **Example:**

"""jsx

// Good: Composing smaller components

const Button = ({ children, onClick }) => (

{children}

);

const Input = ({ type, value, onChange }) => (

);

const Form = () => {

const [email, setEmail] = React.useState('');

const handleSubmit = (e) => {

e.preventDefault();

alert("Email submitted: ${email}");

};

return (

setEmail(e.target.value)} />

Submit

);

};

"""

## 2. Zustand-Specific Component Design

### 2.1. Selective Subscriptions with "useStore"

* **Do This:** Use the selector function in "useStore" to subscribe only to the parts of the store that a component actually needs. This minimizes re-renders, boosting performance. Leverage "useShallow" and "equalityFn" options when appropriate.

* **Don't Do This:** Subscribe to the entire store if the component only needs a small piece of data. This leads to unnecessary re-renders.

* **Why:** Selective subscriptions prevent components from re-rendering when unrelated parts of the store change. This significantly improves performance, especially in complex applications.

* **Example:**

"""jsx

// Good: Selecting only the "todos" array

import create from 'zustand';

import { shallow } from 'zustand/shallow';

const useTodoStore = create((set) => ({

todos: [],

addTodo: (text) => set((state) => ({ todos: [...state.todos, { id: Date.now(), text, completed: false }] })),

toggleTodo: (id) => set((state) => ({

todos: state.todos.map(todo =>

todo.id === id ? { ...todo, completed: !todo.completed } : todo

)

})),

filter: 'all',

setFilter: (filter) => set({ filter }),

}));

const TodoList = () => {

//Selects only the todos and toggleTodo from the zustand store.

const [todos, toggleTodo] = useTodoStore(state => [state.todos, state.toggleTodo], shallow);

return (

{todos.map(todo => (

toggleTodo(todo.id)} />

{todo.text}

))}

);

};

"""

"""jsx

// Bad: Subscribing to the entire store (BAD PRACTICE)

const TodoListBad = () => {

const { todos, toggleTodo } = useTodoStore(); // Gets EVERYTHING

return (

{todos.map(todo => (

toggleTodo(todo.id)} />

{todo.text}

))}

);

};

"""

### 2.2. Derived State with Selectors

* **Do This:** Use selectors within "useStore" to derive new state values from the store's state. Avoid performing calculations directly within the component if that derived value is needed in multiple components or could be memoized for performance gains.

* **Don't Do This:** Recompute derived state within components on every render, especially if the calculations are expensive.

* **Why:** Selectors allow you to efficiently compute derived state and only trigger re-renders when the relevant parts of the store change.

* **Example:**

"""jsx

import create from 'zustand';

const useCartStore = create((set) => ({

items: [],

addItem: (item) => set((state) => ({ items: [...state.items, item] })),

removeItem: (itemId) => set((state) => ({ items: state.items.filter(item => item.id !== itemId) })),

}));

const CartTotal = () => {

// Selector to calculate the total price

const total = useCartStore(state =>

state.items.reduce((sum, item) => sum + item.price, 0)

);

return (

Total: ${total}

);

};

"""

### 2.3. Using "useStore.getState" Sparingly

* **Do This:** Primarily use "useStore(selector)" for accessing state within components. Reserve "useStore.getState()" for cases where you need to access the store's value outside of the component lifecycle (ex: event handlers, testing, or directly interacting with the store).

* **Don't Do This:** Rely heavily on "useStore.getState()" inside React component render functions; this bypasses subscriptions and can lead to stale data and performance issues.

* **Why:** "useStore(selector)" drives efficient component re-renders and reactivity based on zustand store changes. "useStore.getState()" is a snapshot, and does not cause functional components using reactiveness to re-render..

* **Example:**

"""jsx

import create from 'zustand';

const useCounterStore = create((set) => ({

increment: () => set((state) => ({ count: state.count + 1 })),

decrement: () => set((state) => ({ count: state.count - 1 })),

}));

const CounterComponent = () => {

const count = useCounterStore((state) => state.count); // Use selector for reactivity

const increment = useCounterStore(state => state.increment);

//Example of getState usage.

const logCount = () => {

//This is fine because it's not in the render function directly.

const currentCount = useCounterStore.getState().count;

console.log('Current count:', currentCount);

};

return (

Count: {count}

Increment

Log count

);

};

"""

### 2.4 Local vs global state

* **Do This:** Use local state for presentational and UI concerns. Use Zustand to reflect your data model.

* **Don't Do This:** Put EVERYTHING into Zustand. Components should continue to manage transient UI-related state (form input values, active tab state, etc) without involving Zustand, unless that state needs to be shared or persisted.

* **Why:** Over-using Zustand can lead to unnecessary complexity and performance overhead. Local state can be more efficient for component-specific concerns with limited scope.

* **Example:**

"""jsx

// Good: Local state for input value, Zustand for user data

import create from 'zustand';

const useUserStore = create((set) => ({

user: { name: '', email: '' },

updateUser: (userData) => set({ user: userData }),

}));

const UserForm = () => {

const [name, setName] = React.useState(''); // Local state for input

const [email, setEmail] = React.useState(''); // Local state

const updateUser = useUserStore(state => state.updateUser);

const handleSubmit = (e) => {

e.preventDefault();

updateUser({ name, email }); // Update Zustand store

};

return (

Name: setName(e.target.value)} />

Email: setEmail(e.target.value)} />

Update Profile

);

};

"""

### 2.5 Managing Asynchronous Actions

* **Do This:** Define async actions (like data fetching) within your Zustand store. Use "try...catch" blocks to handle potential errors and update the store's state accordingly (e.g., setting an "error" flag). If possible, isolate your data access logic using custom hooks to help with SoC and reusability.

* **Don't Do This:** Perform data fetching directly within your components without using any error handling and proper state management. Avoid mutating store values directly within the components.

* **Why:** Keep your code clean, maintainable, and testable. Centralized async actions are easier to manage and provide a single source of truth.

* **Example:**

"""jsx

import create from 'zustand';

const useProductsStore = create((set) => ({

products: [],

loading: false,

error: null,

fetchProducts: async () => {

set({ loading: true, error: null });

try {

const response = await fetch('/api/products');

if (!response.ok) {

throw new Error("HTTP error! status: ${response.status}");

}

const data = await response.json();

set({ products: data, loading: false });

} catch (e) {

set({ error: e.message, loading: false });

}

}));

const ProductsList = () => {

const {products, loading, error, fetchProducts} = useProductsStore();

useEffect(() => {

fetchProducts();

}, [fetchProducts]);

if (loading) return Loading products...;

if (error) return Error: {error};

return (

{products.map(product => (

{product.name} - ${product.price}

))}

);

};

"""

## 3. Advanced Patterns and Considerations

### 3.1. Zustand Middleware

* **Do This:** Leverage Zustand's middleware features (e.g., "persist", "devtools", "immer") to add cross-cutting concerns to your state management without cluttering component logic.

* **Don't Do This:** Implement persistence, debugging, or immutable updates manually in components.

* **Why:** Middleware provides a clean and composable way to enhance Zustand stores with features like persistence, debugging, and immutable updates.

* **Example:**

"""jsx

import create from 'zustand';

import { persist } from 'zustand/middleware';

import { devtools } from 'zustand/middleware';

import produce from 'immer';

const useStore = create(devtools(persist(

(set) => ({

todos: [],

addTodo: (text) => set(produce((state) => {

state.todos.push({ id: Date.now(), text, completed: false });

})),

}),

{

getStorage: () => localStorage,

}

)));

"""

### 3.2. Testing Components with Zustand

* **Do This:** Mock the Zustand store in your component tests to isolate the component and make tests predictable. Consider using a testing library (e.g., Jest, React Testing Library) and mock the Zustand store using "jest.mock". Use "act" when updating the Zustand store within tests.

* **Don't Do This:** Directly manipulate the Zustand store in tests without using mocking, leading to unpredictable test results and potential interference between tests.

* **Why:** Mocking allows you to control the store's state and actions during testing, ensuring consistent and reliable test results and preventing interference between tests.

* **Example:**

"""jsx

// __mocks__/zustand.js

const actualZustand = jest.requireActual('zustand');

let storeValues = {};

const mockSet = (fn) => {

storeValues = typeof fn === "function" ? fn(storeValues) : fn;

};

const useStore = () => ({

getState: () => storeValues,

setState: mockSet,

subscribe: () => {},

destroy: () => {}

});

useStore.setState = mockSet;

useStore.getState = () => storeValues;

useStore.subscribe = () => {};

useStore.destroy = () => {};

module.exports = actualZustand;

module.exports.create = () => useStore

module.exports.useStore = useStore

// Component.test.jsx

import React from 'react';

import { render, screen, fireEvent } from '@testing-library/react';

import { act } from 'react-dom/test-utils';

import TodoList from './TodoList';

import * as zustand from 'zustand';

jest.mock('zustand');

describe('TodoList Component', () => {

it('allows adding a todo to the list', () => {

const mockStore = {

todos: [],

addTodo: jest.fn()

};

const { useStore } = zustand;

useStore.mockReturnValue(mockStore);

render();

const inputElement = screen.getByPlaceholderText('Add todo');

const addButtonElement = screen.getByText('Add');

act(() => {

fireEvent.change(inputElement, { target: { value: 'Buy milk' } });

fireEvent.click(addButtonElement);

});

expect(mockStore.addTodo).toHaveBeenCalledWith('Buy milk');

});

"""

### 3.3. Performance Optimization Strategies

* **Do This:** Use "React.memo" and "useCallback" in conjunction with Zustand selectors to prevent unnecessary re-renders of components. Make sure your custom hook returns a stable reference of the store or selector.

* **Don't Do This:** Rely solely on Zustand to optimize performance, without considering React's own optimization techniques.

* **Why:** "React.memo" memoizes components based on their props. Using useCallback on the state management actions passed as props can drastically eliminate rerenders when props are exactly the same.

### 3.4 Type Safety with TypeScript

* **Do This:** Use TypeScript to define the shape of your Zustand store's state and actions. This provides compile-time type checking and helps prevent runtime errors.

* **Example:**

"""typescript

import create from 'zustand';

interface UserState {

id: number;

email: string;

}

interface UserActions {

updateName: (newName: string) => void;

updateEmail: (newEmail: string) => void;

}

type UserStore = UserState & UserActions;

const useUserStore = create((set) => ({

id: 1,

email: 'john.doe@example.com',

updateName: (newName) => set({ name: newName }),

updateEmail: (newEmail) => set({ email: newEmail }),

}));

"""

These coding standards for Zustand component design will help you write maintainable, performant, and testable React applications. By following these guidelines, your team can contribute to a codebase that is easy to understand, modify, and extend.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Component Design Standards for Zustand

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Code Style and Conventions Standards for Zustand

Deployment and DevOps Standards for Zustand

Testing Methodologies Standards for Zustand

State Management Standards for Zustand

API Integration Standards for Zustand