Org Skills

react-development

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill react-development
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill react-development -g

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.

Skill contents

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.

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).

References

Deeper material the agent loads only when needed.