clawmates/skills/frontend/react-19-server-components.md

---
name: react-19-server-components
description: React 19.2 patterns — RSC by default, `use()` hook, Actions + useActionState, `use client` boundaries.
when_to_use: You're writing React components in a Next.js 15+ app on React 19. Rust_sdlc + frontend teams pin this.
tags: [frontend, react, versioned]
---

# React 19 patterns (as of 19.2.7)

## Server Components by default

- **Every new component is a Server Component unless it needs interactivity.** `use client` opts in.
- **Why**: no JS ships to the browser for pure-display components, data fetching happens at the source, secrets stay server-side.
- **When to `use client`**:
  - Hooks (`useState`, `useEffect`, `useReducer`, custom hooks that use them).
  - Event handlers (`onClick`, `onChange`).
  - Browser-only APIs (`window`, `document`, `IntersectionObserver`).
  - Third-party libs that call `useLayoutEffect` internally.

Pattern: keep the parent server, extract the interactive leaf as client:

```tsx
// list.tsx (server component)
export async function List() {
  const items = await db.items.findMany();
  return (
    <div>
      {items.map((i) => <Row key={i.id} item={i} />)}
      <RefreshButton />          {/* client leaf */}
    </div>
  );
}

// refresh-button.tsx
"use client";
export function RefreshButton() {
  return <button onClick={() => router.refresh()}>Refresh</button>;
}
```

## The `use()` hook

Read a promise or context inside a component (server OR client):

```tsx
import { use } from "react";
export function User({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise);          // suspends until resolved
  return <div>{user.name}</div>;
}
```

- Wrap in `<Suspense fallback={...}>` at the boundary you want to loading-state.
- Works with context: `const theme = use(ThemeContext)` — can be called conditionally, unlike `useContext`.

## Actions + `useActionState`

Server actions handle mutations without an API route:

```tsx
"use client";
import { useActionState } from "react";

async function submit(prev: State, formData: FormData) {
  "use server";
  await db.thing.create({ data: formData });
  return { ok: true };
}

export function Form() {
  const [state, action, pending] = useActionState(submit, { ok: false });
  return (
    <form action={action}>
      <input name="title" />
      <button disabled={pending}>Save</button>
      {state.ok && <p>Saved!</p>}
    </form>
  );
}
```

## `useOptimistic`

For instant UI feedback on mutations:

```tsx
const [optimistic, addOptimistic] = useOptimistic(items, (state, next) => [...state, next]);
```

## What changed vs React 18

- **`forwardRef` is optional** — regular components accept `ref` as a prop (19.0+).
- **`use client` boundary is enforced** — you can't `useState` in a Server Component. Fails at build.
- **Removed**: `React.createRef` in functional components (was already deprecated), string refs.

## Common bugs

- **Passing a function from a Server Component to a Client Component prop** — fails serialization. Solution: define the function inside the client component or pass a Server Action.
- **`useState` in an async Server Component** — build error. Extract the interactive part to a `"use client"` leaf.
- **`document` accessed in the top level of a client component file** — SSR runs the top level, blows up. Guard with `if (typeof window !== "undefined")` or move into an effect.