# State Management Standards for TypeScript

This document outlines the standards for managing application state in TypeScript projects. It emphasizes modern approaches, best practices, and patterns to ensure maintainable, performant, and scalable applications.

## 1. General Principles

### 1.1. Immutability

* **Do This:** Prefer immutable data structures whenever possible.

* **Don't Do This:** Mutate state directly.

**Why:** Immutability simplifies reasoning about state changes, prevents unexpected side effects, and enhances debugging. It also enables techniques like time-travel debugging and optimized rendering in UI frameworks.

**Code Example:**

"""typescript

// Immutable update using the spread operator

interface User {

id: number;

age: number;

}

let user: User = { id: 1, name: "Alice", age: 30 };

// Good: Create a new object with the updated age

let updatedUser: User = { ...user, age: 31 };

// Bad: Mutating the original object directly

// user.age = 31; // Avoid this

"""

### 1.2. Predictable State Transitions

* **Do This:** Use explicit actions or events to trigger state changes.

* **Don't Do This:** Rely on implicit or hidden state mutations.

**Why:** Predictable state transitions make it easier to understand how the application's state evolves over time, leading to increased maintainability and debuggability.

**Code Example (using a Redux-like pattern):**

"""typescript

// Define action types

type Action =

| { type: "INCREMENT" }

| { type: "DECREMENT" };

// Define the reducer function

type CounterState = { count: number };

const initialState: CounterState = { count: 0 };

function counterReducer(state: CounterState = initialState, action: Action): CounterState {

switch (action.type) {

case "INCREMENT":

return { ...state, count: state.count + 1 };

case "DECREMENT":

return { ...state, count: state.count - 1 };

default:

return state;

}

// Example usage (simplified)

let currentState = initialState;

currentState = counterReducer(currentState, { type: "INCREMENT" });

console.log(currentState); // Output: { count: 1 }

"""

### 1.3. Single Source of Truth

* **Do This:** Centralize application state into a single store or context.

* **Don't Do This:** Scatter state across multiple components or services without a clear hierarchy.

**Why:** A single source of truth ensures consistency and avoids data duplication. It makes it easier to manage complex state interactions and provides a clear picture of the application's overall state.

### 1.4. Separation of Concerns

* **Do This:** Separate state management logic from UI components and business logic.

* **Don't Do This:** Mix state updates directly within UI event handlers or business logic functions.

**Why:** Separation of concerns enhances testability, reusability, and maintainability. It allows you to modify state management mechanisms without affecting the rest of the application.

## 2. State Management Libraries and Patterns

### 2.1. Context API with "useReducer" (for simple to moderately complex state)

* **Do This:** Use the "useReducer" hook in conjunction with the Context API for managing localized, moderately complex state in React components.

* **Don't Do This:** Overuse the Context API for global state management in large applications, as it can lead to performance issues due to unnecessary re-renders.

**Why:** Well-suited for managing state that is localized to a specific part of the application. "useReducer" provides a structured way to update state, similar to Redux, but without the overhead of a global store. The Context API provides a means to distribute and consume state across React components.

**Code Example:**

"""typescript

import React, { createContext, useContext, useReducer } from 'react';

// Define the state type and action types

interface AuthState {

isAuthenticated: boolean;

user: { id: number; username: string } | null;

}

type AuthAction =

| { type: 'LOGIN'; payload: { id: number; username: string } }

| { type: 'LOGOUT' };

// Define the reducer function

const authReducer = (state: AuthState, action: AuthAction): AuthState => {

switch (action.type) {

case 'LOGIN':

return { ...state, isAuthenticated: true, user: action.payload };

case 'LOGOUT':

return { ...state, isAuthenticated: false, user: null };

default:

return state;

}

};

// Create the context

interface AuthContextType {

state: AuthState;

dispatch: React.Dispatch;

}

const AuthContext = createContext(undefined);

// Create the provider component

interface AuthProviderProps {

children: React.ReactNode;

}

const AuthProvider: React.FC = ({ children }) => {

const [state, dispatch] = useReducer(authReducer, { isAuthenticated: false, user: null });

return (

{children}

);

};

// Create a custom hook to consume the context

const useAuth = () => {

const context = useContext(AuthContext);

if (!context) {

throw new Error('useAuth must be used within an AuthProvider');

}

return context;

};

export { AuthProvider, useAuth };

// Usage in a component

const LoginComponent: React.FC = () => {

const { dispatch } = useAuth();

const handleLogin = () => {

// Simulate login

dispatch({ type: 'LOGIN', payload: { id: 1, username: 'testuser' } });

};

return (

);

};

"""

### 2.2. Redux (for complex, application-wide state management)

* **Do This:** Use Redux for managing global application state, especially in large, complex applications. Combine with Redux Toolkit to simplify configuration and reduce boilerplate.

* **Don't Do This:** Use Redux for simple, component-local state. Opt for "useState" or "useReducer" in those cases. Avoid overly complex or deeply nested state structures that can hurt performance.

**Why:** Redux provides a centralized store, predictable state transitions, and a rich ecosystem of middleware and tools. Redux Toolkit provides conventions and utilities which make Redux easier to use.

**Code Example (using Redux Toolkit):**

"""typescript

import { configureStore, createSlice, PayloadAction } from '@reduxjs/toolkit';

import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux';

// Define the state type

interface CounterState {

value: number;

}

// Define the initial state

const initialState: CounterState = {

value: 0,

};

// Create a slice

const counterSlice = createSlice({

initialState,

reducers: {

increment: (state) => {

state.value += 1;

decrement: (state) => {

state.value -= 1;

incrementByAmount: (state, action: PayloadAction) => {

state.value += action.payload;

});

// Export actions and reducer

export const { increment, decrement, incrementByAmount } = counterSlice.actions;

export const counterReducer = counterSlice.reducer;

// Configure the store

const store = configureStore({

reducer: {

counter: counterReducer,

});

export default store;

// Define RootState type

export type RootState = ReturnType;

export type AppDispatch = typeof store.dispatch;

// Custom hooks for useSelector and useDispatch with proper typing

export const useAppDispatch: () => AppDispatch = useDispatch;

export const useAppSelector: TypedUseSelectorHook = useSelector;

// Usage in a component

import { useAppDispatch, useAppSelector } from './store';

const Counter: React.FC = () => {

const count = useAppSelector((state) => state.counter.value);

const dispatch = useAppDispatch();

return (

<p>Count: {count}</p>

dispatch(increment())}>Increment

dispatch(decrement())}>Decrement

dispatch(incrementByAmount(5))}>Increment by 5

);

};

export default Counter;

"""

### 2.3. Zustand (for manageable complexity and performance)

* **Do This:** Consider Zustand as a simple, unopinionated state management solution. Suitable for applications where Redux might be overkill but "useReducer" is insufficient. Leverage selectors to optimize component re-renders.

* **Don't Do This:** Use Zustand for highly complex global state scenarios requiring advanced features (e.g., time travel debugging, middleware). Over-rely on global state when component-local state is more appropriate.

**Why:** Zustand is known for its simplicity and ease of use. It combines the benefits of mutable state with controlled updates, leading to good performance. It's an excellent middle-ground option. Selectors ensure components can subscribe to specific parts of the store, reducing unnecessary re-renders.

**Code Example:**

"""typescript

import { create } from 'zustand';

interface BearState {

bears: number;

increasePopulation: () => void;

removeAllBears: () => void;

}

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

bears: 0,

increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),

removeAllBears: () => set({ bears: 0 }),

}));

// Example consumer

import useBearStore from './store';

const BearCounter = () => {

const bears = useBearStore((state) => state.bears); // Select only what is needed

return {bears} around here ...;

};

const Controls = () => {

const increasePopulation = useBearStore((state) => state.increasePopulation);

const removeAllBears = useBearStore((state) => state.removeAllBears);

return (

one up

remove all

)

}

"""

### 2.4. Jotai (for atomic state management)

* **Do This:** Explore Jotai for its approach to state management based on atomic, derived state. It is valuable when needing fine-grained control over state dependencies.

* **Don't Do This:** Attempt to port large Redux codebases to Jotai without careful consideration. Avoid creating excessively granular atoms that lead to performance bottlenecks.

**Why:** Jotai is particularly well-suited for scenarios where components need to subscribe to very specific parts of the state, minimizing re-renders and improving performance. It promotes composition and code reuse.

**Code Example:**

"""typescript

import { atom, useAtom } from 'jotai';

// Create an atom

const countAtom = atom(0);

// Example consumer

const CounterComponent = () => {

const [count, setCount] = useAtom(countAtom);

return (

Count: {count}

setCount(count + 1)}>Increment

);

};

export default CounterComponent;

"""

### 2.5. XState (for managing complex state machines)

* **Do This:** Use XState for orchestrating complex, stateful logic, like multi-step forms, workflows, or UI interactions with clearly defined states and transitions. Leverage TypeScript's type system to fully define state structures and events.

* **Don't Do This:** Overuse XState for simple UI element state. Avoid creating state machines that are excessively complex or difficult to understand.

**Why:** XState helps to manage complexity by providing a visual and declarative way to define states and transitions. TypeScript integration further enhances the development experience and ensures type safety.

**Code Example:**

"""typescript

import { createMachine, assign } from 'xstate';

import { useMachine } from '@xstate/react';

// Define the state machine context

interface ContextType {

}

// Define the state machine events

type EventType =

| { type: 'INCREMENT' }

| { type: 'DECREMENT' };

// Create the state machine

const counterMachine = createMachine(

{

id: 'counter',

initial: 'idle',

context: {

states: {

idle: {

on: {

INCREMENT: {

actions: assign({ count: (context) => context.count + 1 }),

DECREMENT: {

actions: assign({ count: (context) => context.count - 1 }),

}

);

// React component using the state machine

const CounterComponent = () => {

const [state, send] = useMachine(counterMachine);

return (

Count: {state.context.count}

send('INCREMENT')}>Increment

send('DECREMENT')}>Decrement

);

};

export default CounterComponent;

"""

## 3. Reactive Programming with RxJS

### 3.1. Observables for Asynchronous Data Streams

* **Do This:** Use RxJS Observables to handle asynchronous data streams, user input, and event-driven interactions.

* **Don't Do This:** Use RxJS for simple, synchronous operations that can be handled with standard JavaScript methods. Overuse or abuse Subjects, leading to uncontrolled side effects.

**Why:** Observables provide a powerful and flexible way to manage asynchronous data over time. RxJS offers a wide range of operators for transforming, filtering, and combining streams of data.

**Code Example:**

"""typescript

import { fromEvent, interval } from 'rxjs';

import { map, filter, take, scan } from 'rxjs/operators';

// Create an observable from a DOM event

const button = document.getElementById('myButton');

if (button) {

const click$ = fromEvent(button, 'click'); // Ensure button isn't null

click$.pipe(

map(() => 1),

scan((acc, val) => acc + val, 0)

).subscribe(count => {

console.log("Button clicked ${count} times");

});

}

// Create an observable from an interval

const interval$ = interval(1000);

interval$.pipe(

filter(value => value % 2 === 0),

map(value => "Tick: ${value}"),

take(5)

).subscribe(message => {

console.log(message);

});

"""

### 3.2. Subjects for Multicasting

* **Do This:** Use RxJS Subjects to multicast values to multiple observers. Use "BehaviorSubject" or "ReplaySubject" when you need to provide an initial value or replay past values, respectively.

* **Don't Do This:** Expose Subjects directly to components. Encapsulate them within services or state management solutions to control the flow of data.

**Why:** Subjects act as both an Observable and an Observer, allowing you to push values to multiple subscribers. They are useful for creating shared data streams or event buses.

**Code Example:**

"""typescript

import { Subject } from 'rxjs';

// Create a Subject

const mySubject = new Subject();

// Subscribe to the Subject

mySubject.subscribe(value => {

console.log("Observer 1: ${value}");

});

mySubject.subscribe(value => {

console.log("Observer 2: ${value}");

});

// Push values to the Subject

mySubject.next('Hello');

mySubject.next('World');

"""

## 4. Practical Implementation Considerations

### 4.1. TypeScript Typing

* **Do This:** Use strong typing to define the shape of your state, actions, and reducers.

* **Don't Do This:** Use "any" or "unknown" types excessively, which defeats the purpose of using TypeScript.

**Why:** Strong typing improves code maintainability, prevents runtime errors, and enhances code completion in IDEs.

**Code Example:**

"""typescript

interface Product {

id: number;

price: number;

}

type ProductAction =

| { type: "ADD_PRODUCT"; payload: Product }

| { type: "REMOVE_PRODUCT"; payload: number };

interface ProductState {

products: Product[];

}

"""

### 4.2. Performance Optimization

* **Do This:** Use memoization techniques (e.g., "useMemo", "useCallback", "React.memo") to prevent unnecessary re-renders. Select only the necessary data from the state to avoid triggering updates when unrelated data changes.

* **Don't Do This:** Neglect performance optimization, especially in large applications with frequent state updates. Deeply nested state often triggers expensive rerenders.

**Why:** Optimizing performance ensures a smooth user experience and reduces resource consumption. Memoization and selective updates can significantly improve rendering performance.

### 4.3. Testing

* **Do This:** Write unit tests for your reducers, selectors, and effects to ensure they behave as expected.

* **Don't Do This:** Neglect testing state management logic, which can lead to unexpected behavior and difficult-to-debug issues.

**Why:** Thorough testing is essential for maintaining the integrity of your state management system. Unit tests provide confidence that your code is working correctly and prevent regressions when making changes.

### 4.4. Error Handling

* **Do This:** Properly handle errors that may occur during state updates, asynchronous operations, or API calls. Display user-friendly error messages and provide mechanisms for recovering from errors.

* **Don't Do This:** Ignore errors or allow them to propagate silently, which can lead to a poor user experience and data corruption.

**Why:** Robust error handling ensures that your application can gracefully recover from unexpected errors and prevents data loss or corruption.

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'

State Management Standards for TypeScript

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

TypeScript Performance Optimization Standards: Best Practices for Efficient Applications

pnpm over npm

Storybook (v9.0.18+) Guidelines for Angular (v18+)

Code Style and Conventions Standards for TypeScript

Core Architecture Standards for TypeScript