--- name: react-expert description: Use when building React 18+ applications in .jsx or .tsx files, Next.js App Router projects, or create-react-app setups. Creates components, implements custom hooks, debugs rendering issues, migrates class components to functional, and implements state management. Invoke for Server Components, Suspense boundaries, useActionState forms, performance optimization, React 19 features, accessibility (WCAG 2.1 AA), or design system adherence. license: MIT metadata: author: https://github.com/vinhio version: "1.2.0" domain: frontend role: specialist scope: implementation output-format: code related-skills: fullstack-guardian, playwright-expert, test-master autoInvoke: true priority: high triggers: - "react" - "jsx" - "hooks" - "useState" - "useEffect" - "useContext" - "server components" - "react 19" - "suspense" - "tanstack query" - "redux" - "zustand" - "component" - "frontend" - "accessibility" - "wcag" - "aria" - "design system" allowed-tools: Read, Grep, Glob, Edit, Write --- # React Expert Senior React specialist with deep expertise in React 19, Server Components, and production-grade application architecture. ## Table of Contents - [When to Use This Skill](#when-to-use-this-skill) - [Core Workflow](#core-workflow) - [Reference Guide](#reference-guide) - [Key Patterns](#key-patterns) - [Constraints](#constraints) - [Output Templates](#output-templates) - [Knowledge Reference](#knowledge-reference) ## When to Use This Skill - Building new React components or features - Implementing state management (local, Context, Redux, Zustand) - Optimizing React performance - Setting up React project architecture - Working with React 19 Server Components - Implementing forms with React 19 actions - Data fetching patterns with TanStack Query or `use()` ## Core Workflow 1. **Analyze requirements** - Identify component hierarchy, state needs, data flow 2. **Choose patterns** - Select appropriate state management, data fetching approach 3. **Implement** - Write TypeScript components with proper types 4. **Validate** - Run `tsc --noEmit`; if it fails, review reported errors, fix all type issues, and re-run until clean before proceeding 5. **Optimize** - Apply memoization where needed, ensure accessibility; if new type errors are introduced, return to step 4 6. **Test** - Write tests with React Testing Library; if any assertions fail, debug and fix before submitting ## Reference Guide Load detailed guidance based on context: | Topic | Reference | Load When | | --------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Server Components | `references/server-components.md` | RSC patterns, Next.js App Router | | React 19 | `references/react-19-features.md` | use() hook, useActionState, forms | | State Management | `references/state-management.md` | Context, Zustand, Redux, TanStack | | Hooks | `references/hooks-patterns.md` | Custom hooks, useEffect, useCallback | | Performance | `references/performance.md` | memo, lazy, virtualization | | Testing | `references/testing-react.md` | Testing Library, mocking | | Class Migration | `references/migration-class-to-modern.md` | Converting class components to hooks/RSC | | Coding Guide | `references/coding-guide.md` | Providers, routing/guards, store, layouts, screens, components, hooks, styles/assets, naming conventions, region markers/JSX annotations, domain models | | Refactoring Large Files | `references/refactoring-large-files.md` | Splitting an oversized component/hook/file, grouping a feature directory into folders, ref-ownership rules, verifying a split didn't change behavior | | Component Design Principles | `references/component-design-principles.md` | Feature-based folder organization, file colocation, pure rendering, no side effects in render, rules of hooks, single layer of abstraction, props/forwardRef, compound components, state hoisting | | Accessibility | `references/accessibility.md` | Keyboard navigation, ARIA labels, focus management, empty/error states, WCAG verification checklist | | Forms & Error Handling | `references/forms-and-error-handling.md` | Controlled forms, React Hook Form + Zod, error boundaries, safe conditional rendering, list-key pitfalls | | Design System Adherence | `references/design-system-adherence.md` | Avoiding the generic "AI aesthetic", spacing/typography/color tokens, responsive breakpoints, skeleton loading, optimistic updates | ## Key Patterns ### Server Component (Next.js App Router) ```tsx // app/users/page.tsx — Server Component, no "use client" import { db } from "@/lib/db"; interface User { id: string; name: string; } export default async function UsersPage() { const users: User[] = await db.user.findMany(); return ( ); } ``` ### React 19 Form with `useActionState` ```tsx "use client"; import { useActionState } from "react"; async function submitForm(_prev: string, formData: FormData): Promise { const name = formData.get("name") as string; // perform server action or fetch return `Hello, ${name}!`; } export function GreetForm() { const [message, action, isPending] = useActionState(submitForm, ""); return (
{message &&

{message}

}
); } ``` ### Custom Hook with Cleanup ```tsx import { useState, useEffect } from "react"; function useWindowWidth(): number { const [width, setWidth] = useState(() => window.innerWidth); useEffect(() => { const handler = () => setWidth(window.innerWidth); window.addEventListener("resize", handler); return () => window.removeEventListener("resize", handler); // cleanup }, []); return width; } ``` ## Constraints ### MUST DO - Use TypeScript with strict mode - Implement error boundaries for graceful failures - Use `key` props correctly (stable, unique identifiers) - Clean up effects (return cleanup function) - Use semantic HTML and meet WCAG 2.1 AA: keyboard navigation, ARIA labels, focus management, and non-blank empty/error states (see `references/accessibility.md`) - Memoize when passing callbacks/objects to memoized children - Use Suspense boundaries for async operations - Follow the project's design system for spacing, typography, and color tokens instead of generic defaults (see `references/design-system-adherence.md`) - Partition non-trivial component files with region marker comments (see `references/coding-guide.md`) - Target ~50-150 lines per component/hook file; split files that grow well past that once a clean seam exists (see `references/refactoring-large-files.md`) - When splitting a large file, verify lint/type/test/build against a `git stash -u` baseline before trusting the diff (see `references/refactoring-large-files.md`) - Once a component splits into 2+ sub-components, give the parent a folder (`Parent.tsx` + `index.ts` + `components/`), recursing the same shape for any child that itself needs splitting (see `references/refactoring-large-files.md#sub-component-folder-shape-components-per-split-parent`) - Organize `src/` by feature/domain (`features/auth/`, `features/user/`); reserve top-level `components/` for UI genuinely shared across features (see `references/component-design-principles.md#organize-by-feature-not-by-technology`) - Keep render pure and idempotent — same props always produce the same JSX (see `references/component-design-principles.md#pure-rendering-idempotency`) - Wrap stateful/lifecycle logic in a custom hook; call hooks only at the top level of a component or another hook (see `references/component-design-principles.md#rules-of-hooks`) - Give a component a single layer of abstraction — extract nested sub-components/hooks once it juggles more than one concern (see `references/component-design-principles.md#single-layer-of-abstraction`) - Hoist state out of presentational/leaf components into the nearest common ancestor (see `references/component-design-principles.md#state-hoisting`) - Switch config-heavy boolean/string props to compound components once a component's prop list is just toggling which children render (see `references/component-design-principles.md#composition-over-configuration`) ### MUST NOT DO - Mutate state directly - Use array index as key for dynamic lists - Create functions inside JSX (causes re-renders) - Forget useEffect cleanup (memory leaks) - Ignore React strict mode warnings - Skip error boundaries in production - Return a raw mutable `ref` from a custom hook (see `references/hooks-patterns.md#never-return-a-raw-ref-from-a-hook`) - Generate random values, read `new Date()`, or fetch data directly in the render body (see `references/component-design-principles.md#pure-rendering-idempotency`) - Mutate variables/objects or touch the DOM during render — side effects belong in `useEffect` or event handlers (see `references/component-design-principles.md#no-side-effects-during-render`) - Call a hook conditionally, in a loop, or outside a component/custom hook (see `references/component-design-principles.md#rules-of-hooks`) - Use color as the sole indicator of state — pair it with an icon or text (see `references/accessibility.md`) ## Output Templates When implementing React features, provide: 1. Component file with TypeScript types 2. Test file if non-trivial logic 3. Brief explanation of key decisions ## Knowledge Reference React 19, Server Components, use() hook, Suspense, TypeScript, TanStack Query, Zustand, Redux Toolkit, React Router, React Testing Library, Vitest/Jest, Next.js App Router, accessibility (WCAG) [Documentation](https://jeffallan.github.io/claude-skills/skills/frontend/react-expert/)