react

React Best Practices

Directives for React development. Use Australian English spelling (organisation, behaviour, etc.).

---

Directory Structure

src/
├── components/
│   ├── ui/           # Reusable UI (Button/, Input/, Modal/)
│   ├── features/     # Feature-specific (auth/, dashboard/)
│   └── layouts/      # MainLayout, Sidebar
├── hooks/
├── contexts/
├── services/api/
├── utils/
├── types/
├── pages/
├── App.tsx
└── main.tsx

• Co-locate component, styles, and tests in the same directory.
• Each module has a single responsibility.
• Avoid circular dependencies.

---

File Naming Conventions

• Components: PascalCase (MyComponent.tsx)
• Hooks: camelCase prefixed with use (useAuth.ts)
• Contexts: PascalCase + Context (ThemeContext.tsx)
• Services/Utils: camelCase (apiClient.ts)
• CSS Modules: .module.css or .module.scss

---

Component Patterns

• Use functional components only; no class components.
• Define TypeScript props interfaces; extend BaseComponentProps for shared props (className, children).
• Prefer composition over inheritance.
• Use compound components (e.g. Tabs + Tab) for related UI.
• Prefer custom hooks over HOCs and render props.
• Use barrel exports (index.ts) for component directories.
• Always provide a unique, stable key when rendering lists.

---

Custom Hooks Patterns

• Name hooks with use prefix; return a tuple or object.
• Return [value, setter] as const for useState-like APIs.
• Include cleanup in useEffect (event listeners, timers, subscriptions).
• Use useCallback for returned callbacks to avoid unnecessary re-renders.
• Document dependencies correctly in useEffect arrays.

---

Modern React 18+

• useTransition: Mark non-urgent updates (e.g. search results) so the UI stays responsive.
• useDeferredValue: Defer expensive children when input changes rapidly.
• Server Components (React 18.3+): Use for data fetching and static content; mark client components with 'use client'.
• Automatic batching: State updates are batched; no need for unstable_batchedUpdates.