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

name, description, when_to_use, tags

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

// 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):

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:

"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:

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.