React — Skills Reference

React — Skills Reference

Overview

No vendor certification exists for React. This playbook encodes the working competence applied when building, reviewing, or debugging a React application — anchored entirely on official React documentation (react.dev) and broadly accepted community best practices. Anchor all claims to react.dev; verify against it before acting.

Scope of this skill: React itself — components, hooks, state, rendering, data-fetching patterns, accessibility, and testing. Framework concerns (Next.js App Router, Server Components, Expo) are deferred to the nextjs and react-native sibling skills.

Load this skill when… writing or reviewing React components, hooks, or state architecture; debugging re-renders, stale closures, or effect dependencies; auditing accessibility (ARIA, focus management); writing or fixing React Testing Library tests. Not this skill: Next.js App Router, Server/Client Components, Server Actions → see nextjs; React Native / Expo mobile apps → see react-native.

Study resources and data-fetching library links live in references/study-resources.md.

Verify steps assume nothing about your tooling — use your project's own scripts and the language toolchain (tsc, node, the test runner, the package manager), in that order of preference.

Uncertainty & Escalation

• Always re-verify live: React evolves rapidly — hooks, concurrent features, and the React Compiler change behavior across minor versions. [volatile — verify live] marks apply to: React Compiler availability and defaults (production-ready late 2025 — check the project's babel-plugin-react-compiler version before assuming it is active); compiler lint rules — eslint-plugin-react-compiler is superseded by eslint-plugin-react-hooks v6, which folds in the compiler rules (React 19.2, Oct 2025); useActionState and useOptimistic (React 19+ only); React 18 batching behavior in non-React-managed event handlers (verify with React 18+); TanStack Query and SWR API surface (major-version breaking changes — always check installed version). Check react in package.json — React 18 and 19 differ on form actions, optimistic updates, and compiler support.
• Live wins: the installed React version's actual behavior and react.dev are authoritative over this file → log discrepancies via Feedback protocol below.
• Escalate to a human: upgrading from React 17→18 or 18→19 in a production app (concurrent mode and batching changes can surface latent bugs); removing StrictMode from a production app; major data-fetching library upgrades (TanStack Query v4→v5 API changes); production deploys.
• Confidence taxonomy: facts in this file are stable unless tagged [volatile — verify live] or [opinion — house style].

1. Components, Hooks & State

Component fundamentals

• Every component must be a pure function of its inputs (props + state). Same inputs → same JSX output, every time. Side effects in the render body (mutations, subscriptions, timers) are bugs waiting to surface under Strict Mode's double-invoke or the React Compiler.
• Never define a component inside another component. Each render call creates a new function reference; React sees it as a different component type, unmounts the inner component, and resets its state. Define all components at module top level.
• Key correctness. Keys tell React which items in a list are the same across renders. Use stable IDs (database id, slug); never use array index as a key on a list that can be reordered, filtered, or have items inserted — React will misapply state and DOM attributes.

Rules of hooks (non-negotiable)

1. Call hooks only at the top level of a React function — never inside loops, conditionals, or early returns.
2. Call hooks only from React function components or from other custom hooks, never from plain functions.

Violating either rule makes hook call order unstable across renders; React will corrupt state. ESLint's eslint-plugin-react-hooks (v6+ in React 19.2 projects, which folds in the former eslint-plugin-react-compiler rules) enforces both rules automatically — enable and trust it. See react.dev/blog/2025/10/01/react-19-2.