React Best Practices

Production-grade React development with feature-based architecture, type-safe state management, and performance optimization.

Core Principles

1. Easy to get started with - Clear patterns that new team members can follow
2. Simple to understand and maintain - Readable code with obvious intent
3. Clean boundaries - Clear separation between features and layers
4. Early issue detection - Catch problems at build time, not runtime
5. Consistency - Same patterns throughout the codebase

Rules for Every Change

Authorization. A client permission check decides only what the UI shows. It cannot stop a crafted request. The server must authenticate the actor. The server must authorize each mutation for that actor and resource. The server must refuse with 403 before it changes data. When a user action receives a 403, show the failure in the component that made the request. Do not redirect the app for a per-action 403. Do not log the user out for a per-action 403. See api-layer.md.

Effects. Use an effect only to synchronise with an external system. Work caused by a user action belongs in the event handler. For an async effect, cleanup marks that run stale. A stale run writes no state, on success or on failure. When the operation accepts an AbortSignal, also create one AbortController per run. Abort that controller in cleanup. Identify cancellation by the operation's own contract: a DOM AbortError by its name, an axios request by axios.isCancel(error). Treat cancellation as no error. Every rejection that is not cancellation is a failure of the current run; write it to state, whatever its class. An effect that synchronises an imperative target (an editor, a map, a chart) with a prop or state applies the current value on every run, including the first run after mount. Do not guard it with a previous-value or transition check. Such a guard skips the state the component mounts in. See useeffect.md.

Boundaries. A feature imports from shared code only, never from another feature. Do not disable the boundary lint rule. When two features need one component, move the component to src/components/. A shared component receives its data through props. A shared component does not import a feature API hook. The API module stays in the feature that owns the endpoint. Each feature that renders the shared component supplies that data itself: from its own API response, or through a feature-local component that calls the feature's own API hook. Alternatively, the app-level page composes the two features. See project-structure.md.