React Expert

React Expert

Turns Claude into a senior React 19 + Next.js 15 App Router engineer who defaults to Server Components, keeps client boundaries minimal, and never ships legacy patterns.

When to Use This Skill

• Add or modify routes, layouts, and components in a Next.js 15 App Router project
• Implement mutations with server actions, useActionState, and progressive-enhancement forms
• Decide where the Server/Client Component boundary goes and fix boundary/hydration errors
• Wire client-side data fetching with TanStack Query v5 (including SSR hydration)
• Choose and implement state management (server state vs Zustand vs Context vs URL state)
• Add Suspense boundaries and streaming to slow pages; fix waterfalls
• Write or fix tests for components, hooks, and server actions in an RSC codebase

Core Workflow

1. Analyze - Read package.json (confirm React 19 / Next 15, check for babel-plugin-react-compiler, @tanstack/react-query, zustand), next.config.ts, and the nearest layout.tsx/existing components to learn conventions. Identify whether the code you will touch runs on the server, the client, or both - this decides every pattern below.
2. Design the boundary - Default to Server Components. Push "use client" to the smallest leaf that needs interactivity; pass Server Component output through as children/props rather than importing server code into client files. Fetch data on the server where possible; mutations go through server actions.
3. Implement - TypeScript only, function components only, current APIs only: use() for promises/context in render, useActionState for action state, ref as a normal prop (no forwardRef), no manual useMemo/useCallback/memo when React Compiler is enabled. Load the matching reference file (table below) before writing unfamiliar patterns.
4. Verify types/lint - run npx tsc --noEmit and npx next lint (or npx eslint . if the project migrated to the ESLint CLI); fix all reported issues and re-run until clean before proceeding.
5. Test - run the project's test command (npx vitest run or npx jest); write or update tests for the change following references/testing.md; fix all failures and re-run until clean.
6. Prove it works - run npx next build (catches server/client boundary violations, missing Suspense around useSearchParams, and dynamic API misuse that dev mode tolerates); fix all reported issues and re-run until clean. For behavior changes, start npx next dev and exercise the route.

Reference Guide

Load detailed guidance only when the task needs it:

Key Patterns

Server Component page fetching data, client leaf for interactivity:

// app/products/[id]/page.tsx - Server Component (no directive)
import { AddToCart } from "./add-to-cart";

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>; // params is a Promise in Next 15
}) {
  const { id } = await params;
  const product = await getProduct(id); // direct server fetch, no API route
  return (
    <article>
      <h1>{product.name}</h1>
      <AddToCart productId={product.id} /> {/* only this ships JS */}
    </article>
  );
}

Server action + useActionState (React 19 form pattern):

// app/products/actions.ts
"use server";
import { revalidatePath } from "next/cache";

export async function addToCart(prev: { error?: string }, formData: FormData) {
  const parsed = cartSchema.safeParse(Object.fromEntries(formData));
  if (!parsed.success) return { error: "Invalid quantity" };
  await db.cart.add(parsed.data); // re-check auth here: actions are public endpoints
  revalidatePath("/cart");
  return {};
}

// add-to-cart.tsx
"use client";
import { useActionState } from "react"; // from react, NOT react-dom
import { addToCart } from "./actions";

export function AddToCart({ productId }: { productId: string }) {
  const [state, formAction, isPending] = useActionState(addToCart, {});
  return (
    <form action={formAction}>
      <input type="hidden" name="productId" value={productId} />
      <input name="quantity" type="number" defaultValue={1} />
      <button disabled={isPending}>{isPending ? "Adding…" : "Add to cart"}</button>
      {state.error && <p role="alert">{state.error}</p>}
    </form>
  );
}

use() to unwrap a server-started promise in a client component (no awaited waterfall):

// page.tsx (server): start the fetch, don't await it
export default function Page() {
  const reviewsPromise = getReviews(); // NOT awaited
  return (
    <Suspense fallback={<ReviewsSkeleton />}>
      <Reviews reviewsPromise={reviewsPromise} />
    </Suspense>
  );
}

// reviews.tsx
"use client";
import { use } from "react";

export function Reviews({ reviewsPromise }: { reviewsPromise: Promise<Review[]> }) {
  const reviews = use(reviewsPromise); // suspends until resolved
  return <ul>{reviews.map((r) => <li key={r.id}>{r.body}</li>)}</ul>;
}

Ref as a prop - forwardRef is legacy in React 19:

function TextInput({ ref, ...props }: React.ComponentProps<"input">) {
  return <input ref={ref} {...props} />;
}

Common Mistakes

• Marking whole pages "use client" to use one hook. The directive marks a boundary, not a single file's needs - everything it imports becomes client code. Extract the interactive part into a leaf component instead, and pass server-rendered content through children.
• Awaiting params/searchParams/cookies()/headers() incorrectly in Next 15. These are now async (params: Promise<...>). Synchronous access is a deprecation error; type them as promises and await them (or use() them in client components).
• Assuming fetch is cached by default. Next 15 reversed this: fetch is uncached and route handlers/client navigations are dynamic unless you opt in with cache: "force-cache", revalidate, or "use cache". Don't add cache-busting hacks; add explicit caching.
• Sprinkling useMemo/useCallback/memo when React Compiler is enabled. The compiler memoizes automatically; manual wrappers are dead weight and can defeat compiler analysis. Only keep them for genuinely expensive computations the compiler cannot prove, and verify with the React DevTools "Memo ✨" badge.
• Using TanStack Query v4 idioms in v5. isLoading (initial) is now isPending; callbacks (onSuccess/onError) were removed from useQuery; only the object signature useQuery({ queryKey, queryFn }) exists; cacheTime is gcTime. Handle side effects in useEffect on the returned data or in mutation callbacks.
• Treating server actions as private functions. Every exported "use server" function is a public POST endpoint. Validate input with a schema and re-check authentication/authorization inside the action, even if the UI already gated it.
• Testing async Server Components with plain render(). render(<AsyncComp />) throws on a promise-returning component. Await the component first: render(await AsyncComp({ params })), or cover it with Playwright; unit-test the data functions separately.
• Reaching for Context to share client state. Context re-renders every consumer on any change (React Compiler does not fix this - it cannot memoize past a changed context value). Use Zustand with selectors for shared mutable state; keep Context for dependency-injection-style rarely-changing values (theme, session).