Imported from tankpkg/packages (skills/react/SKILL.md). Install upstream with npx skills add tankpkg/packages --skill react. Copyright stays with the author.

React

Core Philosophy

• Composition over configuration: shape APIs with children, slots, and small props.
• Colocation principle: keep state, view, and data fetching near the consumer.
• Derive, don't sync: compute from source of truth, avoid mirror state.
• Make invalid states unrepresentable: model state transitions explicitly.
• Optimize for change: prefer patterns that localize edits.
• Keep effects reactive: side effects follow data, not events.
• Name state by intent, not by UI widget.

Component Decision Tree

State Management Decision Tree

Hooks Rules of Thumb

• Start with state local; lift only when 2+ siblings depend on it.
• Prefer useReducer when updates depend on the previous state in many places.
• Put async data in a server-state tool; don't mirror it in useState.
• Make effects about synchronization, not computation.
• Stabilize callbacks only when you pass them to memoized children.
• Store derived values with useMemo only when recomputation is expensive.
• Avoid useEffect for DOM reads; reach for refs and layout effects intentionally.
• If a hook returns both data and actions, keep the action names stable.
• Minimize hook parameters; prefer passing config objects.

React 19 Features Quick Reference

Modern React Stack (2026)

-> See references/modern-react-2026.md for setup guides and detailed patterns.

Anti-Patterns

Component API Checklist

• Expose the minimum props needed to express intent.
• Prefer boolean props for mode switches; prefer enums for variants.
• Use children for structure and provide slots for customization.
• Keep side-effecting props explicit (onOpen, onClose, onSubmit).
• Return primitive data from hooks, not JSX.
• If a prop can be derived, remove it from the public API.
• Keep controlled and uncontrolled modes separate and obvious.
• Document default behavior with tests.

Effect Design Checklist

• Identify the external system being synchronized.
• Keep the dependency list aligned with the system inputs.
• Use AbortController for fetch cancellation.
• Prefer useLayoutEffect only for layout reads or measurement.
• Cleanup always mirrors setup; avoid conditional cleanup.
• Avoid setState in effects when value can be derived.
• Never wire effects to user events; use event handlers.
• Promote repeated effect patterns into a custom hook.

Suspense and Data Boundaries

• Add Suspense at product-level latency points, not every component.
• Keep fallback UI representative of the final layout.
• Isolate error boundaries per feature area.
• Avoid shared mutable state across server and client components.
• Use data loaders at route boundaries to avoid waterfalls.
• Prefer streaming for long-tail data, keep critical path small.
• Avoid hiding errors by catching promises without rendering.

Testing Heuristics

• Test the user-visible output, not internal state.
• Prefer React Testing Library queries that match user intent.
• Avoid snapshot tests for dynamic content; assert specific UI.
• Use MSW or a query cache to model server responses.
• Separate unit tests for hooks from integration tests for screens.
• Assert optimistic updates and rollback behavior explicitly.
• Keep test data realistic to catch rendering edge cases.
• When in doubt, test the boundary between components.

TypeScript Integration

• Model props with discriminated unions for variant-driven UIs.
• Type children explicitly when slots are required.
• Use ComponentPropsWithoutRef<"button"> for pass-through props.
• Prefer satisfies to keep config objects narrow.
• Keep hooks generic only when the type pays for itself.
• Treat as polymorphism as part of the public API contract.

Operational Workflow

• Start by modeling state transitions in a reducer or state chart.
• Build the smallest component tree that expresses the intent.
• Add composition points only after usage shows friction.
• Introduce Suspense and streaming after data paths are stable.
• Profile before memoization to avoid premature tuning.
• Document invariants with tests instead of comments.

Performance Posture

• Prefer fewer renders over cheaper renders when possible.
• Avoid re-render cascades by splitting context providers.
• Use virtualization when list size > 200 or rendering cost is high.
• Treat memo and useCallback as opt-in tools, not defaults.
• When React Compiler is active, remove redundant manual memoization.
• Split bundles by route first, then by heavy widget.
• Inspect bundle output to validate tree-shaking.
• Defer non-critical work with useTransition or Actions.
• Use stable keys and stable item identity for lists.

Migration Notes

• Prefer incremental refactors; wrap new components under old API.
• Introduce adapters for legacy props; deprecate in types.
• Use codemods for prop renames and hook replacements.
• Keep fallback UI identical during data-layer changes.
• Add feature flags for high-risk UI rewrites.
• Gate server component adoption per route.
• Keep a clear rollback path for Actions adoption.
• Remove dead code after two releases.

Refactor Triggers

• Prop lists exceed 8-10 items or include derived values.
• Effects contain more than one external resource.
• A component has more than 2 responsibilities.
• A hook has side effects and state but no cleanup.
• Re-render time dominates in the profiler.
• Teams repeatedly add exceptions to the API.

Linting with React Doctor

React Doctor scans for anti-patterns and outputs a 0-100 health score. Run npx -y react-doctor@latest . to scan. Use --diff main for CI, --fix to auto-fix, --score for CI-friendly numeric output. -> See references/react-doctor.md for the full rule reference, CI integration, and configuration.

Reference Index