CLAUDE.md for React -Make Claude Write Your React
React has too many ways to do the same thing. CLAUDE.md is where you pick one and commit -so Claude stops making the choice for you.
The React inconsistency problem
React's flexibility is its greatest strength and its biggest AI-coding liability. Claude will write class components, functional components, HOCs, render props -whatever it thinks fits. Without CLAUDE.md, you get a codebase that looks like five different developers made different choices in the same file.
Component structure conventions
The highest-value rules to include: one component per file, named exports only (no default exports), props typed with interfaces, no anonymous function callbacks as props (they break memoization), and a consistent internal file order. These decisions compound -getting them into CLAUDE.md early saves thousands of lines of future refactoring.
React CLAUDE.md template
Add this section to your project's CLAUDE.md.
# React Conventions
## Components
- Functional components only. No class components.
- One component per file. File name is kebab-case matching the component.
- Named exports ONLY. Never use default exports for components.
✓ export function UserCard() {}
✗ export default function UserCard() {}
- Props typed with an interface above the component:
interface UserCardProps { name: string; avatarUrl: string }
- Internal component order: imports → interface → component function → helpers → export statement.
## Hooks
- Custom hooks live in src/hooks/ with the use prefix.
- Never call hooks conditionally.
- useEffect dependencies must be complete. Add a comment for non-obvious dependencies.
- Prefer extracting logic into custom hooks over inline useEffect chains.
## State
- useState: local UI state only (open/closed, current tab, form value).
- Context: low-frequency global state (theme, locale, auth user object).
- Zustand: complex shared client state. Only if already in the project stack.
- Never store server data in React state -use React Query or SWR cache.
## Event Handlers
- Named functions only. Never inline arrow functions as event handlers in JSX.
✓ const handleSubmit = () => { ... }; return <button onClick={handleSubmit}>
✗ return <button onClick={() => { ... }}>
## Testing
- Unit tests for all utility functions and hooks.
- Integration tests for user flows using React Testing Library.
- Test file colocated with component: UserCard.test.tsx next to UserCard.tsx.