react

React

Use this skill to make React choices from current docs plus the local app's actual version, framework, and conventions.

Snapshot: [email protected] / [email protected] (released 2026-09-09; still npm latest on 2026-10-01). Refresh from source-map.md if versions differ.

Workflow

1. Identify the React surface before changing code:
   • Read the nearest project guidance files and package manifests.
   • Check installed or declared versions of react, react-dom, the framework, build tool, test stack, TypeScript, and ESLint.
   • Determine whether the target is a client-only app, SSR, framework-managed app, React Server Components app, React Native app, component library, or migration.
2. Refresh docs when the user asks for latest/current behavior, when versions are unclear, or when using React 19+ APIs:
   • Prefer current docs tooling or official docs pages.
   • Use source-map.md for the captured latest-version snapshot and official source links.
3. Load the focused reference file for the task:
   • core-react.md: component design, JSX, state, effects, hooks, purity, performance, and testing judgment.
   • react-19.md: React 19–19.3 APIs, upgrades, Actions, forms, Server Components, Server Functions, Compiler, View Transitions, Fragment refs, and release-channel caveats.
   • react-dom.md: createRoot, hydrateRoot, browser(), DOM forms, hydration, server/static rendering, Trusted Types, resources, and escape hatches.
4. Implement in the existing project style:
   • Prefer framework primitives over direct React DOM APIs when the framework owns routing, data fetching, SSR, RSC, or hydration.
   • Preserve local component boundaries, accessibility conventions, tests, and styling patterns.
   • Avoid introducing React 19.3-only or canary-only APIs unless the app's dependencies support them.
5. Verify the smallest meaningful surface:
   • Run the project's relevant typecheck, lint, test, build, story, or browser verification command.
   • For visible UI changes, inspect the real screen state when feasible.
   • Report any verification you could not run.

React Judgment

• Keep render pure and idempotent. Do not read time, randomness, browser-only globals, or mutate non-local values during render unless the value is safely isolated and repeatable.
• Derive values during render when they can be calculated from props or state. Do not add state plus an Effect just to mirror another value.
• Use Effects only to synchronize with external systems such as the DOM, subscriptions, timers, imperative widgets, analytics, or non-framework data fetching.
• Keep Effect dependencies honest. Prove a value is non-reactive by moving it out of the component or into an Effect/Event boundary instead of suppressing the linter.
• Put user-caused side effects in event handlers or Actions. Put render-caused external synchronization in Effects.
• Prefer local state. Lift state only when multiple components need to coordinate. Use reducers for complex transitions and useSyncExternalStore for external stores.
• On React 19.3 SSR, prefer use(browser()) from react-dom over typeof window or a mounted-state Effect for Client Components that cannot produce matching HTML.
• Treat <ViewTransition> as a Transition/Suspense animation boundary. Do not call the browser startViewTransition API for React-managed updates.
• Treat Server Components, Server Functions, and React DOM server/static APIs as framework integration territory unless the task is explicitly building framework infrastructure.
• Treat canary and experimental docs as unavailable in stable apps unless the project explicitly uses those channels.