jotai-atom-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

# Jotai Atom Architecture Skill

## When This Skill Applies

Use this skill when:
- Designing new Jotai state architecture for a feature
- Refactoring existing state management to Jotai
- Managing dynamic collections or large objects
- Experiencing unnecessary re-renders
- Setting up atom families for parameterized state
- Implementing async data fetching with atoms
- Debugging memory leaks in atom-based state
- Integrating Jotai with React Three Fiber or other libraries

## Atom Architecture Checklist

Follow this systematic approach when working with Jotai atoms:

### ☐ 1. Identify State Granularity

**Determine atomic units:**

```typescript
// WRONG: Monolithic state
const appStateAtom = atom({
  user: {...},
  todos: [...],
  settings: {...},
  ui: {...}
})

// CORRECT: Atomic granularity
const userAtom = atom({...})
const todosAtom = atom([...])
const settingsAtom = atom({...})
const uiStateAtom = atom({...})
```

**Principle**: "One atom per independent piece of state"

**Ask yourself**:
- Can this state be updated independently?
- Do different components need different parts?
- Will updates to one part affect unrelated components?

### ☐ 2. Choose Appropriate Atom Type

**Match pattern to use case:**

| Use Case | Atom Type | Example |
|----------|-----------|---------|
| Simple value | `atom(initial)` | `atom(0)` |
| Derived/computed | `atom((get) => ...)` | `atom((get) => get(a) + get(b))` |
| Async data | `atom(async (get) => ...)` | `atom(async () => fetch(...))` |
| Resettable | `atomWithReset(initial)` | `atomWithReset(0)` |
| Refreshable async | `atomWithRefresh(async () => ...)` | Pull-to-refresh |
| Persisted | `atomWithStorage('key', initial)` | localStorage sync |
| Reducer-based | `atomWithReducer(initial, reducer)` | Redux-like |
| Parameterized | `atomFamily((param) => atom(...))` | Dynamic collections |

### ☐ 3. Apply Focused Subscriptions for Large Objects

**Prevent unnecessary re-renders:**

```typescript
import { focusAtom } from 'jotai-optics'

const largeObjectAtom = atom({
  users: [...], // 1000 users
  posts: [...], // 5000 posts
  comments: [...] // 10000 comments
})

// WRONG: Component re-renders on ANY property change
const data = useAtomValue(largeObjectAtom)

// CORRECT: Only re-renders when users change
const usersAtom = focusAtom(largeObjectAtom, (optic) => optic.prop('users'))
const users = useAtomValue(usersAtom)
```

**Impact**: Eliminates re-renders from unrelated data changes.

### ☐ 4. Use splitAtom for Array Management

**Enable item-level reactivity:**

```typescript
import { splitAtom } from 'jotai/utils'

const todosAtom = atom([...])
const todoAtomsAtom = splitAtom(todosAtom)

function TodoList() {
  const [todoAtoms, dispatch] = useAtom(todoAtomsAtom)

  return todoAtoms.map(todoAtom => (
    <TodoItem
      key={`${todoAtom}`} // Use atom.toString() as stable key
      todoAtom={todoAtom}
      onRemove={() => dispatch({ type: 'remove', atom: todoAtom })}
    />
  ))
}

function TodoItem({ todoAtom }) {
  const [todo, setTodo] = useAtom(todoAtom)
  // Only THIS item re-renders when updated
  return <div>{todo.text}</div>
}
```

**Benefit**: Updating one item doesn't re-render the list or other items.

### ☐ 5. Implement Atom Families with Memory Management

**For dynamic parameterized state:**

```typescript

From nocksock/superpowers, MIT.

More from nocksock/superpowers