# State Management Standards for Performance

This document outlines the coding standards for state management within Performance applications. It aims to provide a comprehensive guide for developers to ensure maintainable, performant, and scalable code. These standards are designed to work with the latest versions of Performance and integrate seamlessly with modern development practices.

## 1. Architectural Principles for State Management

### 1.1. Centralized vs. Component-Level State

**Standard:** Choose a state management approach that aligns with the application's complexity and size. Favor centralized state management (e.g., with Performance's built-in tools or third-party libraries optimized for Performance) for larger, more interactive applications and component-level state for smaller, simpler ones.

**Why:**

- **Maintainability:** Centralized state makes debugging and reasoning about application behavior easier in complex scenarios.

- **Performance:** Using reactive state libraries optimized for Performance prevents unnecessary re-renders when state changes only affect specific components.

- **Scalability:** Centralized solutions often provide more robust mechanisms for managing state across large application codebases.

**Do This:**

- For small to medium-sized applications or self-contained modules, use component-level state with mechanisms for event emission to notify parents (or listeners) of data changes.

- For large, complex applications, use a global state management solution like Valtio, Jotai, or Performance's Context API when appropriate. These tools are designed to manage data flow and react effectively to changes across the application using reactive patterns.

**Don't Do This:**

- Don't rely solely on prop drilling for deeply nested components in large applications. This reduces maintainability and becomes cumbersome.

- Don't overuse global state for simple component-specific data, as this can lead to unnecessary re-renders and performance bottlenecks.

**Example (Component-Level State):**

"""javascript

// Correct

import React, { useState } from 'react';

function Counter() {

const [count, setCount] = useState(0);

const increment = () => {

setCount(count + 1);

};

return (

Count: {count}

Increment

);

}

export default Counter;

"""

**Example (Centralized State with Valtio - Optimized for Performance):**

"""javascript

// Correct

import { proxy } from 'valtio';

import { useSnapshot } from 'valtio/utils';

const state = proxy({

count: 0,

});

const increment = () => {

state.count += 1;

};

function Counter() {

const snapshot = useSnapshot(state);

return (

Count: {snapshot.count}

Increment

);

}

export default Counter;

"""

### 1.2. Unidirectional Data Flow

**Standard:** Enforce a strict unidirectional data flow in the application architecture. This typically involves components triggering actions or events that update the state, and the updated state then flowing back down to the components as props or via hooks.

**Why:**

- **Predictability:** Unidirectional data flow makes it easier to trace the source of state changes and understand how they propagate through the application.

- **Debuggability:** Simplifies debugging by providing a clear path for state changes.

- **Testability:** Easier to isolate components and test their behavior in response to state changes.

**Do This:**

- Implement a pattern where components dispatch actions/events to update the state.

- Ensure components only receive data through props or state hooks, and do not directly modify the state outside of action/event handlers.

- Consider tools that enforce unidirectional data flow, such as state management libraries that specifically designed for this pattern.

**Don't Do This:**

- Avoid directly mutating state in child components without explicit actions or events.

- Don't pass setState functions directly as props for complex states that need modifications.

**Example (Unidirectional Flow with Performance Context API):**

"""javascript

// Correct

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

const AppContext = createContext();

function AppProvider({ children }) {

const [count, setCount] = useState(0);

const increment = () => {

setCount(count + 1);

};

return (

{children}

);

}

function Counter() {

const { count, increment } = useContext(AppContext);

return (

Count: {count}

Increment

);

}

function App() {

return (

);

}

export default App;

"""

### 1.3. Immutability

**Standard:** Treat state as immutable whenever possible. Instead of modifying the existing state object directly, create a new object with the required changes. This principle extends to array and object properties within the state.

**Why:**

- **Predictability:** Immutable data structures make it easier to track changes and prevent unexpected side effects.

- **Performance:** Facilitates efficient change detection, which is useful for Performance's rendering optimizations.

- **Debugging:** Simplifies debugging by ensuring that past states are preserved.

**Do This:**

- Use the spread operator ("...") to create new objects with the new state.

- Use ".map()" and ".filter()" to create new arrays instead of modifying existing ones.

- Consider using libraries like Immer to simplify immutable updates, especially with nested objects.

**Don't Do This:**

- Avoid direct mutations of state objects: "state.property = newValue".

- Don't use methods that mutate arrays directly, such as "push()", "pop()", "splice()".

**Example (Immutable State Updates):**

"""javascript

// Correct

import React, { useState } from 'react';

function ShoppingCart() {

const [items, setItems] = useState([

{ id: 1, name: 'Apple', quantity: 2 },

{ id: 2, name: 'Banana', quantity: 3 },

]);

const addItem = (newItem) => {

setItems([...items, newItem]); // Correct: Create a new array

};

const updateQuantityImmutably = (itemId, newQuantity) => {

setItems(

items.map((item) =>

item.id === itemId ? { ...item, quantity: newQuantity } : item

)

);

};

const removeItem = (itemId) => {

setItems(items.filter((item) => item.id !== itemId));

};

// ... (rest of the component)

return (

addItem({id: 3, name: "Orange", quantity: 1})}>Add Orange

)

}

export default ShoppingCart;

"""

### 1.4. Single Source of Truth

**Standard:** Designate a single, authoritative source of truth for each piece of data in your application. Avoid duplicating state across multiple components.

**Why:**

- **Consistency:** Ensures that data is consistent throughout the application.

- **Maintainability:** Simplifies updates by centralizing state management logic.

- **Avoidance of Conflicts:** Prevents conflicting state updates from different parts of the application.

**Do This:**

- Identify the most appropriate level at which to store a particular piece of data (e.g., global state, parent component, or local component).

- Ensure that components that need access to the same data retrieve it from the same source.

- If state needs to be derived in multiple locations, consider creating derived state using memoization or selectors.

**Don't Do This:**

- Don't maintain duplicate copies of the same data in multiple components.

- Avoid allowing different components to independently update the same shared state.

**Example (Single Source of Truth):**

"""javascript

//Correct

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

// Define an AppContext

const AppContext = createContext();

// Create a Provider component to wrap your app and provide the state

function AppProvider({ children }) {

const [user, setUser] = useState({ name: 'John Doe', email: 'john.doe@example.com' });

// Function to update user details

const updateUser = (newDetails) => {

setUser({ ...user, ...newDetails }); // Updating user state immutably

};

return (

{children}

);

}

// Custom hook to consume the AppContext

function useAppContext() {

return useContext(AppContext);

}

// Component using the global state

function UserProfile() {

const { user } = useAppContext();

return (

Name: {user.name}

Email: {user.email}

);

}

// Component to update the user's email

function UpdateEmail() {

const { updateUser } = useAppContext();

const [newEmail, setNewEmail] = useState('');

const handleSubmit = (e) => {

e.preventDefault();

updateUser({ email: newEmail }); // Dispatching an action to update the email

};

return (

setNewEmail(e.target.value)}

placeholder="New Email"

Update Email

);

}

function App() {

return (

);

}

export default App;

"""

## 2. Implementation Guidelines

### 2.1. State Management Libraries

**Standard:** Select appropriate Performance-optimized state management libraries or tools based on project requirements. Some popular choices include:

- **Valtio:** Simple and unopinionated proxy-based state management, ideal for small to medium-sized applications. It's highly performant and easy to integrate.

- **Jotai:** Atomic state management with derived atoms, useful for complex state dependencies while still preserving Performance.

- **Context API + useReducer:** Built-in Performance solution for moderate complexity. Offers more control than "useState" but requires more boilerplate.

**Why:**

- **Scalability:** Well-chosen libraries provide patterns for managing state across large codebases.

- **Performance:** Libraries optimize state updates and re-rendering through techniques like memoization and selective updates.

- **Developer Experience:** Libraries provide tooling and conventions that simplify state management tasks.

**Do This:**

- Carefully evaluate state management libraries to find the best fit for your projects.

- Consider size, performance characteristics, community support, and integration with the Performance ecosystem.

**Don't Do This:**

- Don't implement custom solutions for state management when mature libraries are available.

- Avoid using libraries that are no longer actively maintained or have known performance issues with the LATEST VERSION of Performance.

**Example (Context API + useReducer):**

"""javascript

// Correct

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

const AppContext = createContext();

const reducer = (state, action) => {

switch (action.type) {

case 'INCREMENT':

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

case 'DECREMENT':

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

default:

return state;

}

};

function AppProvider({ children }) {

const [state, dispatch] = useReducer(reducer, { count: 0 });

return (

{children}

);

}

function Counter() {

const { state, dispatch } = useContext(AppContext);

return (

Count: {state.count}

dispatch({ type: 'INCREMENT' })}>Increment

dispatch({ type: 'DECREMENT' })}>Decrement

);

}

function App() {

return (

);

}

export default App;

"""

### 2.2. Naming Conventions

**Standard:** Adopt consistent naming conventions for state variables, actions, and reducers to improve code readability and maintainability.

**Why:**

- **Clarity:** Consistent naming makes it easier to understand the purpose of different state variables, actions, and reducers.

- **Maintainability:** Reduces the cognitive load required to work with state management code.

**Do This:**

- Use camelCase for state variable names (e.g., "userData", "isLoading").

- Use descriptive names for actions (e.g., "FETCH_USER_SUCCESS", "UPDATE_CART_ITEM").

- Use verbs for action creators (e.g., "fetchUser", "updateCartItem").

- Prefix reducers with a unique identifier when using multiple reducers (e.g., "userReducer", "cartReducer").

**Don't Do This:**

- Avoid vague or abbreviated names that do not convey the purpose of the state variable, action, or reducer.

- Don't use inconsistent naming conventions throughout the application.

**Example (Naming Conventions):**

"""javascript

// Correct

const initialState = {

userData: null,

isLoading: false,

error: null,

};

const FETCH_USER_REQUEST = 'FETCH_USER_REQUEST';

const FETCH_USER_SUCCESS = 'FETCH_USER_SUCCESS';

const FETCH_USER_FAILURE = 'FETCH_USER_FAILURE';

const fetchUserRequest = () => ({ type: FETCH_USER_REQUEST });

const fetchUserSuccess = (userData) => ({ type: FETCH_USER_SUCCESS, payload: userData });

const fetchUserFailure = (error) => ({ type: FETCH_USER_FAILURE, payload: error });

const userReducer = (state = initialState, action) => {

switch (action.type) {

case FETCH_USER_REQUEST:

return { ...state, isLoading: true, error: null };

case FETCH_USER_SUCCESS:

return { ...state, isLoading: false, userData: action.payload };

case FETCH_USER_FAILURE:

return { ...state, isLoading: false, error: action.payload };

default:

return state;

}

};

export default userReducer;

"""

### 2.3. Optimizing Re-renders

**Standard:** Utilize performance optimization techniques to minimize unnecessary re-renders when state changes.

**Why:**

- **Performance:** Reduces wasted CPU cycles by preventing components from re-rendering when their props or state haven't changed.

- **Responsiveness:** Improves application responsiveness by only updating the parts of the UI that need to change.

**Do This:**

- Use "React.memo" for functional components to memoize the rendered output.

- Use "useMemo" to memoize expensive calculations that depend on state values.

- Implement "shouldComponentUpdate" (or "PureComponent") in class components to prevent re-renders based on prop and state comparisons (although this is less favored in modern Performance).

- Use "useCallback" to memoize functions that are passed as props to child components.

- Explore "valtio/utils" selectors.

**Don't Do This:**

- Avoid blindly applying performance optimizations without first profiling the application to identify performance bottlenecks.

- Don't use "shouldComponentUpdate" or "PureComponent" if the component frequently receives new objects or arrays as props, as the shallow comparison may not be effective.

**Example (using "React.memo" and "useMemo"):**

"""javascript

// Correct

import React, { useState, useMemo, useCallback } from 'react';

const ExpensiveComponent = React.memo(({ data, onClick }) => {

console.log('ExpensiveComponent rendered');

return {data.value};

});

function App() {

const [count, setCount] = useState(0);

const [data, setData] = useState({value: "Initial"});

// Memoize the expensive calculation

const expensiveValue = useMemo(() => {

console.log("Calculating Expensive Value...")

let result = 0;

for (let i = 0; i < 10000000; i++) {

result += i;

}

return result;

}, [count]);

const handleClick = useCallback(() => {

setCount(count + 1);

}, [count]);

return (

Count: {count}

Expensive Value: {expensiveValue}

setData({value: "Updated!"})}>Update Data

);

}

export default App;

"""

## 3. Common Anti-Patterns

### 3.1. Prop Drilling

**Anti-Pattern:** Passing props through multiple layers of nested components that don't directly use them.

**Why:**

- **Maintainability:** Makes code harder to refactor and maintain.

- **Readability:** Obscures the relationship between data consumers and producers.

**Solution:**

- Use Context API or other state management libraries to provide data to deeply nested components.

- Consider component composition to reduce nesting.

### 3.2. Mutating State Directly

**Anti-Pattern:** Directly modifying state objects or arrays instead of creating new ones.

**Why:**

- **Predictability:** Can lead to unexpected side effects and bugs.

- **Performance:** Prevents Performance from efficiently detecting changes and optimizing rendering.

**Solution:**

- Always create new state objects and arrays using immutable update patterns (e.g., spread operator, ".map()", ".filter()").

### 3.3. Overusing Global State

**Anti-Pattern:** Storing data in global state that is only needed by a small number of components.

**Why:**

- **Performance:** Can trigger unnecessary re-renders in unrelated parts of the application.

- **Complexity:** Makes it harder to reason about the application's state.

**Solution:**

- Store data at the lowest level possible where it is needed.

- Use component-level state or Context API for localized data.

### 3.4. Neglecting Performance Profiling

**Anti-Pattern:** Making performance optimizations without first identifying bottlenecks through profiling.

**Why:**

- **Waste of Time:** Can spend time optimizing the wrong parts of the application.

- **Ineffective:** May not result in any measurable performance improvement.

**Solution:**

- Use Performance's profiling tools to identify components that are slow to render or update.

- Prioritize optimizations based on profiling results.

## 4. Security Considerations

### 4.1. Sensitive Data

**Standard:** Avoid storing sensitive data (e.g., passwords, API keys) directly in application state, especially in client-side storage.

**Why:**

- **Security Risk:** Exposes sensitive data to potential attackers.

**Do This:**

- Store sensitive data on the server and only expose it through secure APIs.

- Use encrypted storage mechanisms if sensitive data must be stored locally.

- When handling user authentication tokens retrieved from APIs, store them securely using "httpOnly" cookies or mechanisms provided by secure authentication libraries.

**Don't Do This:**

- Never store passwords or API keys in plain text in application state or local storage.

- Avoid directly exposing sensitive information in URLs that can be saved in browser history or server logs.

### 4.2. Input Validation

**Standard:** Validate all user inputs before updating the application state to prevent malicious data from corrupting the application or causing security vulnerabilities.

**Why:**

- **Security:** Prevents cross-site scripting (XSS) and other injection attacks.

- **Integrity:** Ensures that the state contains valid data.

**Do This:**

- Implement robust input validation on all forms and data entry points including API calls to avoid accepting data that does not match the expected type, length, or format. For example, sanitize user inputs to prevent XSS attacks:

"""javascript

// Correct

import React, { useState } from 'react';

import DOMPurify from 'dompurify';

function CommentForm() {

const [comment, setComment] = useState('');

const handleCommentChange = (e) => {

setComment(e.target.value);

};

const handleSubmit = (e) => {

e.preventDefault();

const cleanComment = DOMPurify.sanitize(comment);

// Update state with the sanitized comment

console.log('Sanitized comment:', cleanComment);

};

return (

<button type="submit">Submit Comment</button>

</form>

);

}

export default CommentForm;

"""

- Use libraries like "Joi" or "Yup" to define schemas for validating data.

**Don't Do This:**

- Don't trust user inputs without sanitization and validation.

- Avoid directly rendering raw user inputs in the UI without escaping or sanitizing them first.

## 5. Testing State Management

### 5.1 Unit Testing

**Standard:** Write unit tests for state reducers, action creators, and selectors to ensure they function correctly.

**Why:**

- **Reliability:** Verifies that state management logic behaves as expected.

- **Maintainability:** Makes it easier to refactor state management code without introducing regressions.

**Do This:**

- Use testing frameworks like Jest or Mocha.

- Mock external dependencies (e.g., API calls) to isolate state management logic.

- Test all possible state transitions and edge cases.

- Use tools like Performance Testing Library for UI integration testing.

**Don't Do This:**

- Don't skip unit testing of state management logic.

- Avoid writing brittle tests that are tightly coupled to implementation details. Focus on testing public APIs and state transitions.

### 5.2 Integration Testing

**Standard:** Write integration tests to verify that components interact correctly with state management logic.

**Why:**

- **Correctness:** Ensures that components render the correct data and dispatch the correct actions.

- **Confidence:** Provides confidence that the application's UI is working as expected.

**Do This:**

- Use testing libraries that allow you to simulate user interactions and assert on the rendered output.

- Test the integration between components and state management libraries (e.g., Context API, Valtio, Jotai).

- Test the end-to-end flow of data through the application.

By adhering to these state management standards, Performance developers can create applications that are maintainable, performant, scalable, and secure. This document should be regarded as a living guide, with updates and additions reflecting the ever-evolving landscape of Performance development.

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 Performance

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

Deployment and DevOps Standards for Performance

Performance Optimization Standards for Performance

Core Architecture Standards for Performance

Tooling and Ecosystem Standards for Performance

API Integration Standards for Performance