# Performance Optimization Standards for Jotai

This document outlines coding standards focused specifically on performance optimization when developing applications using Jotai. These standards are designed to improve application speed, responsiveness, and efficient resource utilization. We will cover practical techniques, address common anti-patterns, and provide clear "Do This" and "Don't Do This" guidance with illustrative code examples using the latest Jotai features.

## 1. Atom Definition and Scope

### 1.1. Minimize Atom Creation

**Do This:** Reuse atoms whenever logically possible, instead of creating new atoms for similar data.

**Don't Do This:** Create excessive atoms, especially within frequently rendered components, leading to unnecessary subscriptions and re-renders.

**Why:** Each atom you create in Jotai adds to the subscription overhead. Reusing atoms reduces memory consumption and the number of listeners to update.

"""javascript

// Do This: Reuse an atom

import { atom, useAtom } from 'jotai';

const counterAtom = atom(0);

function CounterComponent() {

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

return (

Count: {count}

setCount(count + 1)}>Increment

);

}

// Don't Do This: create a NEW atom on every render

function BadCounterComponent() {

const [count, setCount] = useAtom(atom(0)); // Creates a new atom EVERY render

return (

Count: {count}

setCount(count + 1)}>Increment

);

}

"""

### 1.2. Atom Scope and Provider Usage

**Do This:** Strategically scope atoms using "" components to manage state isolation and prevent unintended side effects. Only use Providers if needed. Default scope is global.

**Don't Do This:** Over-scope atoms globally when component-specific state is sufficient or under-scope resulting in data conflicts or missed updates.

**Why:** Careful scoping controls the atom's lifecycle and visibility, reducing unnecessary updates and simplifying debugging. Over-scoping pollutes the global state, leading to unpredictable behavior.

"""javascript

// Do This: Create a scope and use it.

import { atom, useAtom, Provider } from 'jotai';

import React from 'react';

const countAtom = atom(0);

function Counter() {

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

return (

Count: {count}

setCount(count + 1)}>Increment

);

}

function App() {

return (

{/* Create a new scope */}

{/* Another Scope */}

);

}

// Don't Do This: Implicitly/Incorrectly rely on the global scope. Causes unexpected scope collissions.

const globalCountAtom = atom(0);

function BadCounter() {

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

return (

Count: {count}

setCount(count + 1)}>Increment

);

}

function BadApp() {

return (

{/* This counter now manipulates the SAME global atom, causing unexpected behavior */}

);

}

"""

### 1.3. Derived Atoms and Selectors

**Do This:** Use derived atoms with "selectAtom" or "atom" with "get" to compute values based on other atoms *lazily*. Memoize complex computations within derived atoms to prevent unnecessary recalculations.

**Don't Do This:** Perform expensive calculations directly within components or in setters without memoization. Create unnecessary intermediate atoms.

**Why:** Derived atoms only recompute when their dependencies change. Memoization further optimizes this by caching the result of expensive calculations.

"""javascript

// Do This: Memoize expensive calculation

import { atom, useAtom } from 'jotai';

import { useMemo } from 'react';

const rawDataAtom = atom([1, 2, 3, 4, 5]);

const processedDataAtom = atom((get) => {

const data = get(rawDataAtom);

// Simulate an expensive operation

const processed = useMemo(() => { // useMemo to cache.

console.log('Processing data...'); // only runs if "data" changes!

return data.map(x => x * 2);

}, [data]);

return processed;

});

function DataComponent() {

const [processedData] = useAtom(processedDataAtom);

return (

Processed Data: {processedData.join(', ')}

);

}

// Don't Do This: Recalculate on EVERY render. The useMemo above is critical.

const badProcessedDataAtom = atom((get) => {

const data = get(rawDataAtom);

console.log('Processing data EVERY render...'); // runs always :(

return data.map(x => x * 2);

});

function DataComponent() {

const [processedData] = useAtom(badProcessedDataAtom);

return (

Processed Data: {processedData.join(', ')}

);

}

"""

### 1.4. Immutability

**Do This:** Always update atom values immutably. Use techniques such as the spread operator or "immer" to create new objects/arrays instead of modifying existing ones.

**Don't Do This:** Directly mutate the value stored within an atom.

**Why:** Jotai relies on change detection to trigger updates. Mutable updates bypass this mechanism, leading to inconsistent state and rendering issues.

"""javascript

// Do This: Use the spread operator for immutable updates

import { atom, useAtom } from 'jotai';

const itemsAtom = atom([{ id: 1, name: 'Apple' }]);

function ItemListComponent() {

const [items, setItems] = useAtom(itemsAtom);

const addItem = () => {

setItems([...items, { id: items.length + 1, name: 'Banana' }]);

};

return (

{items.map(item => (

{item.name}

))}

Add Item

);

}

// Do this: Use immer

import { useImmerAtom } from 'jotai/immer'

const itemsAtom = atom([{ id: 1, name: 'Apple' }]);

function ItemListComponent() {

const [items, update] = useImmerAtom(itemsAtom);

const addItem = () => {

update(draft => {

draft.push({ id: items.length + 1, name: 'Banana' })

})

};

return (

{items.map(item => (

{item.name}

))}

Add Item

);

}

// Don't Do This: Mutate the array directly!

function BadItemListComponent() {

const [items, setItems] = useAtom(itemsAtom);

const addItem = () => {

items.push({ id: items.length + 1, name: 'Banana' }); // Direct mutation!

setItems(items); // This MIGHT not trigger a re-render correctly even though it's updating the state

};

return (

{items.map(item => (

{item.name}

))}

Add Item

);

}

"""

## 2. Component Rendering and Subscriptions

### 2.1. Selective Atom Usage

**Do This:** Only subscribe to the atoms whose values are actually used within a component.

**Don't Do This:** Subscribe to atoms that a component doesn't directly need, leading to unnecessary re-renders.

**Why:** Minimizing subscriptions reduces the number of components that re-render when an atom changes.

"""javascript

// Do This: Use only necessary atom values

import { atom, useAtom } from 'jotai';

const userAtom = atom({ id: 1, name: 'John Doe', email: 'john.doe@example.com' });

function UserNameComponent() {

// Only subscribe to the 'name' property

const [userName] = useAtom(atom(get => get(userAtom).name));

return User Name: {userName};

}

// Don't Do This: Subscribe to the entire atom when only name is needed

function BadUserNameComponent() {

const [user] = useAtom(userAtom);

return User Name: {user.name}; // Re-renders if ANY property of user changes

}

"""

### 2.2. Batched Updates

**Do This:** Utilize "batch" to group multiple atom updates into a single re-render cycle.

**Don't Do This:** Trigger multiple atom updates without batching, leading to excessive re-renders.

**Why:** Batching significantly reduces the number of re-renders, especially when performing related state updates.

"""javascript

//Do This: Use explicit batching

import { atom, useAtom, batch } from 'jotai';

const atomA = atom(0);

const atomB = atom(0);

function BatchedUpdateComponent() {

const [a, setA] = useAtom(atomA);

const [b, setB] = useAtom(atomB);

const updateBoth = () => {

batch(() => {

setA(a + 1);

setB(b + 1);

});

};

return (

A: {a}, B: {b}

Update Both

);

}

// Don't Do This: Update both without batching, leading to two re-renders!

function BadBatchedUpdateComponent() {

const [a, setA] = useAtom(atomA);

const [b, setB] = useAtom(atomB);

const updateBoth = () => {

setA(a + 1);

setB(b + 1);

};

return (

A: {a}, B: {b}

Update Both

);

}

"""

### 2.3. Debouncing and Throttling Updates

**Do This:** Debounce or throttle updates to atoms that are frequently updated, such as values from input fields. Use libraries like "lodash" or implement custom logic.

**Don't Do This:** Immediately update atoms on every input change, especially for expensive operations.

**Why:** Debouncing and throttling limit the frequency of updates, preventing performance bottlenecks caused by rapid state changes.

"""javascript

// Do This: Debounce input updates

import { atom, useAtom } from 'jotai';

import { useDebounce } from 'use-debounce';

const searchInputAtom = atom('');

function SearchInputComponent() {

const [searchInput, setSearchInput] = useAtom(searchInputAtom);

const [debouncedSearchInput] = useDebounce(searchInput, 500); // Debounce for 500ms

// Simulate a search function (expensive operation)

React.useEffect(() => {

console.log('Performing search for:', debouncedSearchInput);

// Replace with actual search logic

}, [debouncedSearchInput]);

return (

setSearchInput(e.target.value)}

);

}

// Don't Do This: Perform the search on every key stroke.

function BadSearchInputComponent() {

const [searchInput, setSearchInput] = useAtom(searchInputAtom);

React.useEffect(() => {

console.log('Performing search for:', searchInput); // This is called a LOT.

}, [searchInput]);

return (

setSearchInput(e.target.value)}

);

}

"""

## 3. Asynchronous Operations

### 3.1. Atom-Based Caching

**Do This:** Use atoms to cache results from asynchronous operations to avoid redundant API calls. Implement appropriate cache invalidation strategies.

**Don't Do This:** Repeatedly fetch data from APIs without caching, especially within frequently rendered components.

**Why:** Caching reduces network traffic and improves application responsiveness by serving data from memory.

"""javascript

// Do This: Implement atom-based caching for API calls

import { atom, useAtom } from 'jotai';

const usersAtom = atom(async () => {

const response = await fetch('https://jsonplaceholder.typicode.com/users');

return await response.json();

});

function UserListComponent() {

const [users] = useAtom(usersAtom);

if (users instanceof Promise) {

return Loading users...;

}

return (

{users.map(user => (

{user.name}

))}

);

}

// Don't Do This: Fetch users on EVERY render (very bad)!

function BadUserListComponent() {

const [users, setUsers] = React.useState([]);

React.useEffect(() => {

const fetchUsers = async () => {

const response = await fetch('https://jsonplaceholder.typicode.com/users');

setUsers(await response.json());

}

fetchUsers();

}, [])

return (

{users.map(user => (

{user.name}

))}

);

}

"""

### 3.2. Suspendable Atoms

**Do This:** Leverage Jotai's "suspense" feature for asynchronous data fetching using "atom.unstable_enableSuspense = true". Wrap components accessing these atoms with "". This allows for cleaner data fetching logic and automatic handling of loading states.

**Don't Do This:** Manually manage loading states with boolean flags when using asynchronous operations, leading to more verbose and error-prone code.

**Why:** Suspense provides a declarative way to handle asynchronous operations, improving code readability and simplifying data fetching in React components.

"""javascript

// Do This: Use suspendable atoms for cleaner async fetching

import { atom, useAtom } from 'jotai';

import React from 'react';

atom.unstable_enableSuspense = true;

const userAtom = atom(async () => {

const response = await fetch('https://jsonplaceholder.typicode.com/users/1');

if (!response.ok) {

throw new Error('Failed to fetch user');

}

return await response.json();

});

function UserProfile() {

const [user] = useAtom(userAtom);

return (

{user.name}

Email: {user.email}

);

}

function App() {

return (

Loading user profile...}>

);

}

// Don't Do This: Manual loading states + error state is complex

const badUserAtom = atom({ loading: false, data: null, error: null });

function BadUserProfile() {

const [state, setState] = useAtom(badUserAtom);

React.useEffect(() => {

setState(prev => ({ ...prev, loading: true, error: null }));

fetch('https://jsonplaceholder.typicode.com/users/1')

.then(response => response.json())

.then(data => setState({ loading: false, data, error: null }))

.catch(err => setState({ loading: false, error: err, data: null }));

}, []);

if (state.loading) return Loading user...;

if (state.error) return Error: {state.error.message};

if (!state.data) return No user data; // Initial state

return (

{state.data.name}

Email: {state.data.email}

);

}

"""

### 3.3. Atom Families for Dynamic Data Fetching

**Do This:** Employ atom families ("atomFamily") to manage state for collections of related data, such as fetching data based on IDs.

**Don't Do This:** Create individual atoms for each piece of data in a collection, resulting in a large number of atoms and inefficient updates.

**Why:** Atom families provide a structured way to create and manage atoms dynamically, facilitating efficient data fetching and caching for collections.

"""javascript

// Do This: Use atom families for data fetching based on ID

import { atomFamily, useAtom } from 'jotai';

const userAtomFamily = atomFamily(async (userId: number) => {

const response = await fetch("https://jsonplaceholder.typicode.com/users/${userId}");

if (!response.ok) {

throw new Error('Failed to fetch user');

}

return await response.json();

});

function UserProfile({ userId }: { userId: number }) {

const [user] = useAtom(userAtomFamily(userId));

if (user instanceof Promise) {

return Loading user {userId}...;

}

return (

{user.name}

Email: {user.email}

);

}

// Don't Do This: Create multiple atoms for each user ID.

function BadUserProfile({ userId }: { userId: number }) {

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

React.useEffect(() => {

fetch("https://jsonplaceholder.typicode.com/users/${userId}")

.then(response => response.json())

.then(data => setUser(data));

},[userId]);

if (!user){

return Loading user {userId}...;

}

return (

{user.name}

Email: {user.email}

);

}

"""

## 4. Miscellaneous Optimizations

### 4.1. Proper use of Provider to avoid re-renders

**Do This:** Keep the Provider as low in the tree as possible that still allows access to all relevant components. In other words, scope the provider as closely as possible to the atom usage in your components.

**Don't Do This:** Over-scope a provider at the highest level, causing full app re-renders for state changes only needed in a small section.

**Why:** Jotai relies on React context providers. The documentation says "It’s important to note that whenever the Provider’s value prop is changed, all consumers that are descendants of the Provider will re-render." To address this we want to move providers as low as possible so that we dont change the Provider's value unnecessarily.

"""javascript

// Do This: Low scoped Providers

import { atom, useAtom, Provider } from 'jotai';

import React from 'react';

const countAtom = atom(0);

function Counter() {

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

return (

Count: {count}

setCount(count + 1)}>Increment

);

}

function App() {

return (

{/* Provider is low as possible */}

);

}

// Don't Do This: High scoped Provider. Changes here cause massive changes

const globalValueAtom = atom(123);

function BadCounter() {

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

return (

Count: {count}

setCount(count + 1)}>Increment

);

}

function BadApp() {

const [globalValue, setGlobalValue] = useAtom(globalValueAtom);

return (

setGlobalValue(parseInt(e.target.value))} />

);

}

"""

### 4.2. Use Jotai Devtools for Profiling

**Do This:** Use the Jotai Devtools chrome extension (or similar) to understand atom updates, render cycles, and dependencies for performance tuning.

**Don't Do This:** Blindly optimize without insights from profilers

By adhering to these performance optimization standards, you can build highly performant and responsive applications with Jotai, ensuring a smooth user experience and efficient resource utilization. This document provides a solid foundation for developing optimized Jotai code and promotes a consistent approach across your team.

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'

Performance Optimization Standards for Jotai

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 Jotai

Component Design Standards for Jotai

Core Architecture Standards for Jotai

Code Style and Conventions Standards for Jotai

Testing Methodologies Standards for Jotai