React Frontend
Verify before implementing: For App Router patterns, React 19 APIs, or version-specific behavior, look up current docs (Context7 query-docs if available, else the framework's official docs via web search) before writing code. Training data may lag current releases.
Working rules
- Keep derived state in render and user actions in event handlers; use effects for external synchronization.
- Give async work a lifecycle and cancellation policy; represent failure separately from pending and empty data.
- Preserve focus when hiding interactive regions and exercise keyboard navigation in a real browser.
- Validate and authorize every public server action; send only needed fields across server/client boundaries.
- Measure performance changes and test user-visible behavior, not type-checking alone.
Effects Decision Tree
Effects are escape hatches -- most logic should NOT use effects.
| Need |
Solution |
| Derived value from props/state |
Calculate during render (useMemo if expensive) |
| Reset state on prop change |
key prop on component |
| Respond to user event |
Event handler |
| Notify parent of state change |
Call onChange in event handler, or fully controlled component |
| Chain of state updates |
Calculate all next state in one event handler |
| Sync with external system |
Effect with cleanup |
Effect rules:
- Never suppress the linter -- fix the code instead
- Use updater functions (
setItems(prev => [...prev, item])) to remove state dependencies
- Move objects/functions inside effects to stabilize dependencies
useEffectEvent for non-reactive values (e.g., theme in a connection effect)- Always return cleanup for subscriptions, connections, listeners
- Data fetching cancellation (pick by situation):
AbortController for fetch; ignore flag for non-cancellable promises; React Query handles both automatically
Discipline
- Simplicity first -- every change as simple as possible, impact minimal code
- Only touch what's necessary -- avoid introducing unrelated changes
- No hacky workarounds -- if a fix feels wrong, step back and implement the clean solution
- Before adding a new abstraction, verify it appears in 3+ places
References
Verify
- TypeScript compiles with zero errors
- No suppressed lint rules (
eslint-disable, @ts-ignore) in new code
useEffect dependency arrays not manually overridden- No
forwardRef usage in React 19+ projects (use ref prop directly)
Task-specific references
Read the relevant reference before implementing or reviewing the matching behavior:
- For component types, state ownership, async races, focus, or cached query behavior: components-and-state.md.
- For performance, React APIs, Next.js boundaries, caching, or Tailwind integration: rendering-and-frameworks.md.
- For component, hook, browser, or integration test changes: test-selection.md.
Existing specialized references, when the corresponding topic applies:
1---2name: react-frontend3description: React architecture patterns, TypeScript, Next.js, hooks, and testing. Use when working with React component structure, state management, Next.js routing, Vitest, React Testing Library, or reviewing React code. For visual design and aesthetic direction, use frontend-design instead.4---56# React Frontend78**Verify before implementing**: For App Router patterns, React 19 APIs, or version-specific behavior, look up current docs (Context7 `query-docs` if available, else the framework's official docs via web search) before writing code. Training data may lag current releases.910## Working rules1112- Keep derived state in render and user actions in event handlers; use effects for external synchronization.13- Give async work a lifecycle and cancellation policy; represent failure separately from pending and empty data.14- Preserve focus when hiding interactive regions and exercise keyboard navigation in a real browser.15- Validate and authorize every public server action; send only needed fields across server/client boundaries.16- Measure performance changes and test user-visible behavior, not type-checking alone.1718## Effects Decision Tree1920Effects are escape hatches -- most logic should NOT use effects.2122| Need | Solution |23|------|----------|24| Derived value from props/state | Calculate during render (useMemo if expensive) |25| Reset state on prop change | `key` prop on component |26| Respond to user event | Event handler |27| Notify parent of state change | Call onChange in event handler, or fully controlled component |28| Chain of state updates | Calculate all next state in one event handler |29| Sync with external system | Effect with cleanup |3031**Effect rules:**32- Never suppress the linter -- fix the code instead33- Use updater functions (`setItems(prev => [...prev, item])`) to remove state dependencies34- Move objects/functions inside effects to stabilize dependencies35- `useEffectEvent` for non-reactive values (e.g., theme in a connection effect)36- Always return cleanup for subscriptions, connections, listeners37- Data fetching cancellation (pick by situation): `AbortController` for fetch; `ignore` flag for non-cancellable promises; React Query handles both automatically383940## Discipline4142- Simplicity first -- every change as simple as possible, impact minimal code43- Only touch what's necessary -- avoid introducing unrelated changes44- No hacky workarounds -- if a fix feels wrong, step back and implement the clean solution45- Before adding a new abstraction, verify it appears in 3+ places464748## References4950- [testing.md](./references/testing.md) -- Component, hook, and mocking test examples51- [e2e-testing.md](./references/e2e-testing.md) -- Playwright E2E patterns525354## Verify5556- TypeScript compiles with zero errors57- No suppressed lint rules (`eslint-disable`, `@ts-ignore`) in new code58- `useEffect` dependency arrays not manually overridden59- No `forwardRef` usage in React 19+ projects (use `ref` prop directly)6061## Task-specific references6263Read the relevant reference before implementing or reviewing the matching behavior:6465- For component types, state ownership, async races, focus, or cached query behavior: [components-and-state.md](./references/components-and-state.md).66- For performance, React APIs, Next.js boundaries, caching, or Tailwind integration: [rendering-and-frameworks.md](./references/rendering-and-frameworks.md).67- For component, hook, browser, or integration test changes: [test-selection.md](./references/test-selection.md).6869Existing specialized references, when the corresponding topic applies:
iliaal