Write production-quality React 19.2 web code day to day — function components with ref as a prop, hooks and effects done right (useEffectEvent, use, Activity), forms with React Hook Form + Zod or Server Actions with useActionState, data via TanStack Query v5, React Router v8 loaders or Next.js 16 Server Components with use cache, Suspense and error boundaries, accessibility, and the purity rules the React Compiler needs.
When agents use itUse this whenever the user asks to build, implement, refactor or fix a React component, hook, page, form, modal, table or feature; asks "how do I do X in React"; pastes React code with a bug; or asks about useEffect, custom hooks, controlled inputs, keys, context, Suspense, "use client", Server Components or Server Actions. Also use it when generating any new web React code, even a small snippet. For React Native or Expo code use react-native-development; for tests use react-testing.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill react-development -a github-copilot
# or with the org installer (adds .github/skills/react-development):
npx -y github:AGCO-Global/org-skills add skill react-development
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the frontend-react-skills plugin, which bundles all Frontend / React skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install frontend-react-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill react-development -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill react-development -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill react-development -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill react-development -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the react-development folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Write the component so it is correct the first time and boring to read: state lives in one place, effects only sync with the outside world, every UI state is rendered, and the code stays pure so the React Compiler can memoise it. Web only — for React Native or Expo use react-native-development.
1. Decide first
Question
Default
Change when
Where does this value live?
Server data → query/loader/Server Component; URL → search params; form → React Hook Form; UI → useState
Value is needed by unrelated routes → a small store (see react-architecture)
Server or client component? (Next.js)
Server; add 'use client' only at the interaction boundary
Vite SPA or React Router data mode: everything is a client component
New projects: on by default; existing: enable and delete manual memo
3. Components
Function declaration, named export, file = component name. No React.FC, no default exports (except framework route files).
Props typed with type, destructured with defaults in the signature; spread ...rest on the root so callers can pass className, data-*, aria-*. ComponentProps<'input'> already includes ref on React 19 types — no forwardRef.
Derive, don't store. Anything computable from props/state is computed in render.
Early returns per state (isPending, isError, empty), happy path last and unindented. Each state renders designed UI, never null.
Keys from stable ids. Handlers handleX inside, onX as props; children over render props. Over ~150 lines or more than three pieces of state → extract a child or a hook. Full template: references/patterns.md.
4. Hooks and effects
useEffect is only for syncing with something outside React (browser API, widget, socket, timer), one concern per effect, complete deps, cleanup returned. Everything else has a better home — see the table in references/patterns.md.
use(ThemeContext) reads context and, unlike useContext, may be called after an early return or inside a branch; use(promise) suspends on a promise handed down from a Server Component or a cache — never one created in render. https://react.dev/reference/react/use
Custom hook when a state+effect cluster has a name (useDebouncedValue, useOrderFilters). useSyncExternalStore for external stores; useRef for DOM handles and values that must not trigger renders.
5. Data
TanStack Query v5: one hook per query in features/<f>/api/ with a key factory, queryFn: ({ signal }) => … so requests cancel, staleTime set deliberately and placeholderData: keepPreviousData for paginated lists (sample in references/patterns.md); components never call useQuery inline. Mutations invalidate by key prefix; optimistic updates only with rollback.
Next.js 16: async Server Components await data; 'use cache' + cacheLife/cacheTag for anything cacheable; in Server Actions call updateTag(tag) for read-your-writes, elsewhere revalidateTag(tag, 'max') — the one-argument form is deprecated. Details and samples: nextjs-16.md in ../react-architecture/references/.
React Router v8 framework mode:loader/action exports with Route.ComponentProps; imports come from react-router (react-router-dom no longer exists).
6. Forms
React Hook Form + Zod via zodResolver; infer the type from the schema; register for native inputs, Controller only for custom components.
Field errors next to the field with aria-invalid and aria-describedby; a role="alert" summary on submit failure; submit disabled while isSubmitting; server errors mapped with setError.
Server Action path: useActionState(action, initialState), the action validates with the same Zod schema, returns field errors, then updateTag. Sample in references/patterns.md.
7. With the React Compiler on
Components and hooks are pure: no mutation of props, state or refs during render, no reading ref.current in render, hooks called unconditionally. Violations are silently skipped by the compiler, not errors.
Delete useMemo/useCallback/memo in compiled code unless the value crosses into an untyped library that needs referential stability.
8. Suspense, errors and edge cases
One <Suspense> per independently loading region, not per component; fallback dimensions match the final layout (no CLS). Every route segment has an error boundary with a retry; use react-error-boundary instead of writing the class.
Guard first-render undefined data, double submit, and races (signal or query keys). Report unexpected errors to monitoring; never console.error and swallow.
Accessibility (WCAG 2.2 AA): semantic elements, every input labelled, icon buttons with aria-label, visible focus, 4.5:1 contrast, targets at least 24×24 CSS px (2.5.8); async feedback in role="status"/role="alert". Use Radix or React Aria primitives for dialogs and menus.
9. Deliverable format
## Component/hook: <name>
- Lives in: features/<f>/... · state owner: <where> · server/client: <which and why>
- Code (imports included, TypeScript strict)
- States rendered: loading / empty / error / success
- Version notes: <React 19.x APIs used and their minimum version>
- Tests: behaviours to cover (write them with react-testing)
Checklist
No derived value stored in state; no effect that could be a computation or an event handler
Every effect has complete deps and a cleanup; useEffectEvent only for non-reactive reads
Server data through a query hook, loader or Server Component — never fetch in useEffect
All four UI states rendered; Suspense fallback sized; error boundary with retry at the segment
ref passed as a prop (19+); no forwardRef, defaultProps or class components
Component pure; no manual memo unless the lint rule and Profiler justify it
Keyboard operable, labelled, roles correct, hit targets ≥ 24 px
Next.js: revalidateTag(tag, profile) / updateTag, never the one-argument form; 'use client' only at the boundary
Types exported, no any; Zod parses untrusted JSON
Anti-patterns
useEffect(() => setX(f(props)), [props]) → derive in render or reset with key.
useEffect fetch with useState flags → query hook / loader / Server Component.
forwardRef in React 19 code → ref prop.
revalidateTag('tag') one-argument form → revalidateTag('tag', 'max') or updateTag('tag') in the action.
The full shared list with fixes: references/react-anti-patterns.md.
Go deeper
references/patterns.md — full component template, the query hook, the useEffect "use instead" table, Server Action + useActionState form, <Activity> and <ViewTransition> samples, use() streaming.
references/react-anti-patterns.md — the one shared anti-pattern list for React and React Native.
nextjs-16.md and react-router-8.md in ../react-architecture/references/ — use cache, Cache Components, proxy.ts, async params, next/image 16 defaults; route modules, loaders and actions.
Sibling skills: react-architecture (framework and state choices), react-performance (symptoms and measurement), react-testing (tests), frontend-code-review (reviews), react-native-development (mobile).
---
name: react-development
description: >
Write production-quality React 19.2 web code day to day — function components with ref as a prop, hooks and
effects done right (useEffectEvent, use, Activity), forms with React Hook Form + Zod or Server Actions with
useActionState, data via TanStack Query v5, React Router v8 loaders or Next.js 16 Server Components with
use cache, Suspense and error boundaries, accessibility, and the purity rules the React Compiler needs.
Use this whenever the user asks to build, implement, refactor or fix a React component, hook, page, form,
modal, table or feature; asks "how do I do X in React"; pastes React code with a bug; or asks about
useEffect, custom hooks, controlled inputs, keys, context, Suspense, "use client", Server Components or
Server Actions. Also use it when generating any new web React code, even a small snippet. For React Native
or Expo code use react-native-development; for tests use react-testing.
metadata:
technology: React
type: development
---
# React Development
> **Targets:** React 19.2 (19.0 noted where different) · Next.js 16 · React Router v8 · TanStack Query v5 · **Verified:** 2026-09 against https://react.dev, https://nextjs.org, https://reactrouter.com
Write the component so it is correct the first time and boring to read: state lives in one place, effects only sync with the outside world, every UI state is rendered, and the code stays pure so the React Compiler can memoise it. Web only — for React Native or Expo use `react-native-development`.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Where does this value live? | Server data → query/loader/Server Component; URL → search params; form → React Hook Form; UI → `useState` | Value is needed by unrelated routes → a small store (see `react-architecture`) |
| Server or client component? (Next.js) | Server; add `'use client'` only at the interaction boundary | Vite SPA or React Router data mode: everything is a client component |
| How is data fetched? | Next.js App Router → async Server Component (+ `'use cache'`); React Router v8 framework mode → `loader`/`action`; Vite SPA → TanStack Query | Real-time or user-driven refetch in any setup → TanStack Query in a client component |
| Forms | React Hook Form + Zod, uncontrolled inputs | Progressive enhancement or no-JS submit (Next.js) → Server Action + `useActionState`, same Zod schema server-side |
| Memoisation | None by hand; React Compiler on | The compiler lint rule reports a bail-out *and* the Profiler shows the cost |
| Ref forwarding | `ref` is an ordinary prop (React 19.0) | Project pinned below 19 → `forwardRef` |
| Keeping hidden UI alive (tabs, drawers) | Unmount it | State or scroll must survive → `<Activity mode="hidden">` (19.2) |
## 2. React 19.x feature map — cite the version when you use one
Sources: https://react.dev/blog/2025/10/01/react-19-2 · https://react.dev/blog/2025/10/07/react-compiler-1
| Feature | Min version | Use when |
|---|---|---|
| `ref` as prop, `useActionState`, `useOptimistic`, `use(promise \| context)`, `<form action>` | 19.0 | Any new code |
| `useEffectEvent`, `<Activity>`, `cacheSignal`, React Performance Tracks in Chrome DevTools | 19.2 | Latest-value reads in effects; keep-alive UI; RSC cache cleanup |
| `<ViewTransition>` | Canary only (Next.js 16 App Router ships it) | Route/list transitions inside `startTransition`; otherwise CSS |
| React Compiler 1.0 (`babel-plugin-react-compiler`) | React 17+ (`target` + `react-compiler-runtime` below 19) | New projects: on by default; existing: enable and delete manual memo |
## 3. Components
- **Function declaration, named export, file = component name.** No `React.FC`, no default exports (except framework route files).
- **Props typed with `type`**, destructured with defaults in the signature; spread `...rest` on the root so callers can pass `className`, `data-*`, `aria-*`. `ComponentProps<'input'>` already includes `ref` on React 19 types — no `forwardRef`.
- **Derive, don't store.** Anything computable from props/state is computed in render.
- **Early returns per state** (`isPending`, `isError`, empty), happy path last and unindented. Each state renders designed UI, never `null`.
- **Keys from stable ids.** Handlers `handleX` inside, `onX` as props; `children` over render props. Over ~150 lines or more than three pieces of state → extract a child or a hook. Full template: `references/patterns.md`.
## 4. Hooks and effects
`useEffect` is only for syncing with something outside React (browser API, widget, socket, timer), one concern per effect, complete deps, cleanup returned. Everything else has a better home — see the table in `references/patterns.md`.
```tsx
import { useEffect, useEffectEvent } from 'react';
import { createConnection, showNotification } from './chat';
export function ChatRoom({ roomId, theme }: { roomId: string; theme: string }) {
const onConnected = useEffectEvent(() => showNotification('Connected!', theme)); // React 19.2+
useEffect(() => {
const connection = createConnection(roomId);
connection.on('connected', () => onConnected());
connection.connect();
return () => connection.disconnect();
}, [roomId]); // theme changes no longer reconnect
return null;
}
```
- `use(ThemeContext)` reads context and, unlike `useContext`, may be called after an early return or inside a branch; `use(promise)` suspends on a promise handed down from a Server Component or a cache — never one created in render. https://react.dev/reference/react/use
- Custom hook when a state+effect cluster has a name (`useDebouncedValue`, `useOrderFilters`). `useSyncExternalStore` for external stores; `useRef` for DOM handles and values that must not trigger renders.
## 5. Data
- **TanStack Query v5:** one hook per query in `features/<f>/api/` with a key factory, `queryFn: ({ signal }) => …` so requests cancel, `staleTime` set deliberately and `placeholderData: keepPreviousData` for paginated lists (sample in `references/patterns.md`); components never call `useQuery` inline. Mutations invalidate by key prefix; optimistic updates only with rollback.
- **Next.js 16:** async Server Components await data; `'use cache'` + `cacheLife`/`cacheTag` for anything cacheable; in Server Actions call `updateTag(tag)` for read-your-writes, elsewhere `revalidateTag(tag, 'max')` — the one-argument form is deprecated. Details and samples: `nextjs-16.md` in `../react-architecture/references/`.
- **React Router v8 framework mode:** `loader`/`action` exports with `Route.ComponentProps`; imports come from `react-router` (`react-router-dom` no longer exists).
## 6. Forms
- React Hook Form + Zod via `zodResolver`; infer the type from the schema; `register` for native inputs, `Controller` only for custom components.
- Field errors next to the field with `aria-invalid` and `aria-describedby`; a `role="alert"` summary on submit failure; submit disabled while `isSubmitting`; server errors mapped with `setError`.
- Server Action path: `useActionState(action, initialState)`, the action validates with the same Zod schema, returns field errors, then `updateTag`. Sample in `references/patterns.md`.
## 7. With the React Compiler on
- Components and hooks are pure: no mutation of props, state or refs during render, no reading `ref.current` in render, hooks called unconditionally. Violations are silently skipped by the compiler, not errors.
- Lint with `eslint-plugin-react-hooks` preset `recommended-latest` (v6+, flat config); it reports the exact line that stopped a component from compiling. https://react.dev/learn/react-compiler/installation
- Delete `useMemo`/`useCallback`/`memo` in compiled code unless the value crosses into an untyped library that needs referential stability.
## 8. Suspense, errors and edge cases
- One `<Suspense>` per independently loading region, not per component; fallback dimensions match the final layout (no CLS). Every route segment has an error boundary with a retry; use `react-error-boundary` instead of writing the class.
- Guard first-render `undefined` data, double submit, and races (`signal` or query keys). Report unexpected errors to monitoring; never `console.error` and swallow.
- Accessibility (WCAG 2.2 AA): semantic elements, every input labelled, icon buttons with `aria-label`, visible focus, 4.5:1 contrast, targets at least 24×24 CSS px (2.5.8); async feedback in `role="status"`/`role="alert"`. Use Radix or React Aria primitives for dialogs and menus.
## 9. Deliverable format
```
## Component/hook: <name>
- Lives in: features/<f>/... · state owner: <where> · server/client: <which and why>
- Code (imports included, TypeScript strict)
- States rendered: loading / empty / error / success
- Version notes: <React 19.x APIs used and their minimum version>
- Tests: behaviours to cover (write them with react-testing)
```
## Checklist
- [ ] No derived value stored in state; no effect that could be a computation or an event handler
- [ ] Every effect has complete deps and a cleanup; `useEffectEvent` only for non-reactive reads
- [ ] Server data through a query hook, loader or Server Component — never `fetch` in `useEffect`
- [ ] All four UI states rendered; Suspense fallback sized; error boundary with retry at the segment
- [ ] `ref` passed as a prop (19+); no `forwardRef`, `defaultProps` or class components
- [ ] Component pure; no manual memo unless the lint rule and Profiler justify it
- [ ] Keyboard operable, labelled, roles correct, hit targets ≥ 24 px
- [ ] Next.js: `revalidateTag(tag, profile)` / `updateTag`, never the one-argument form; `'use client'` only at the boundary
- [ ] Types exported, no `any`; Zod parses untrusted JSON
## Anti-patterns
- **`useEffect(() => setX(f(props)), [props])`** → derive in render or reset with `key`.
- **`useEffect` fetch with `useState` flags** → query hook / loader / Server Component.
- **`forwardRef` in React 19 code** → `ref` prop.
- **`revalidateTag('tag')` one-argument form** → `revalidateTag('tag', 'max')` or `updateTag('tag')` in the action.
- The full shared list with fixes: `references/react-anti-patterns.md`.
## Go deeper
- `references/patterns.md` — full component template, the query hook, the `useEffect` "use instead" table, Server Action + `useActionState` form, `<Activity>` and `<ViewTransition>` samples, `use()` streaming.
- `references/react-anti-patterns.md` — the one shared anti-pattern list for React and React Native.
- `nextjs-16.md` and `react-router-8.md` in `../react-architecture/references/` — `use cache`, Cache Components, `proxy.ts`, async `params`, `next/image` 16 defaults; route modules, loaders and actions.
- Sibling skills: `react-architecture` (framework and state choices), `react-performance` (symptoms and measurement), `react-testing` (tests), `frontend-code-review` (reviews), `react-native-development` (mobile).