react-best-practices

Name: react-best-practices
Author: 0xbigboss

React patterns for hooks, effects, refs, and component design with escape hatch guidance. Effects synchronize with external systems only (WebSocket, third-party libraries, browser APIs); most component logic should avoid Effects entirely Common anti-patterns: derived state, expensive calculations, prop-change resets, and event handling all belong outside Effects—use render calculations, useMemo, key props, and event handlers instead Effect dependencies must never be suppressed; use updater functions, move objects/functions inside Effects, and useEffectEvent for non-reactive logic to keep dependency lists correct Always clean up subscriptions and event listeners; use ignore flags for data fetching to prevent stale updates Refs store mutable values that don't affect rendering; never read or write ref.current during render, only in event handlers and Effects

INSTALLATION

npx skills add https://github.com/0xbigboss/claude-code --skill react-best-practices

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

$2a

When to Use Effects

Synchronizing with external systems: browser APIs (WebSocket, IntersectionObserver), third-party non-React libraries, window/document event listeners, non-React DOM elements (video, maps).

When NOT to Use Effects

Derived state — calculate during render

Expensive calculations — use useMemo

Resetting state on prop change — use key prop

Responding to user events — use event handlers

Notifying parent of state changes — update both in the same event handler

Chains of effects — calculate derived state and update in one event handler

Refs

Use for values that don't affect rendering (timer IDs, DOM node references)

Never read or write ref.current during render; only in event handlers and effects

Use ref callbacks (not useRef in loops) for dynamic lists

Use useImperativeHandle to limit what parent can access

Custom Hooks

Share logic, not state — each call gets an independent state instance

Name useXxx only if it actually calls other hooks; otherwise use a regular function

Avoid lifecycle hooks (useMount, useEffectOnce) — use useEffect directly so the linter catches missing deps

Keep focused on a single concrete use case

Component Patterns

Controlled: parent owns state; uncontrolled: component owns state

Prefer composition with children over prop drilling

Treat boolean props that switch large component trees (isEditing, isThread, hideAttachments) as a composition smell; prefer separate composed components for distinct use cases

For complex reusable UI, prefer compound components with provider-scoped state/actions over monolithic components with many optional props

Use Context for scoped component families as well as truly global state, when it defines a local interface consumed by descendants

Render JSX directly for UI variation; avoid config-array mini-frameworks unless the config is real domain data

Lift the provider boundary when sibling or external controls need access to the same state/actions

Use flushSync when you need to read the DOM synchronously after a state update

See react-patterns.md for code examples and detailed patterns.