Rwsdk Rsc

Add "use client" directive for interactivity. These hydrate in the browser.

"use client";

export default function MyClientComponent() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

Use client components when:

• Handling clicks, input, or other browser events
• Using React hooks (useState, useEffect, useRef, etc.)
• Accessing browser APIs (localStorage, window, etc.)

Data Fetching Pattern

Server components fetch data directly. Wrap async components in Suspense for loading states.

// src/app/pages/todos/TodoPage.tsx
import { Suspense } from "react";

async function Todos({ ctx }) {
  const todos = await db.todo.findMany({ where: { userId: ctx.user.id } });
  return (
    <ol>
      {todos.map((todo) => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ol>
  );
}

export async function TodoPage({ ctx }) {
  return (
    <div>
      <h1>Todos</h1>
      <Suspense fallback={<div>Loading...</div>}>
        <Todos ctx={ctx} />
      </Suspense>
    </div>
  );
}

Key points:

• Route components receive ctx object
• Pass ctx to child server components that need it
• Suspense boundaries show loading state during async operations
• We can import server functions from handlers and fetch data

Server Functions

Execute server code from client components using the "use server" directive.

Define Server Function

// @/pages/todos/functions.tsx
"use server";

import { requestInfo } from "rwsdk/worker";

export async function addTodo(formData: FormData) {
  const { ctx } = requestInfo;
  const title = formData.get("title");
  await db.todo.create({ data: { title, userId: ctx.user.id } });
}

Use in Client Component

// @/pages/todos/AddTodo.tsx
"use client";

import { addTodo } from "./functions";

export default function AddTodo() {
  return (
    <form action={addTodo}>
      <input type="text" name="title" />
      <button type="submit">Add</button>
    </form>
  );
}

How it works:

1. Form submits from client
2. Form data sent to server
3. Server function executes
4. Result streams back, React updates view

RSC vs API Calls: When to Use Each

Use RSC Direct Data Access When:

• Initial page render — Data needed before the page displays
• SEO-critical content — Search engines see server-rendered HTML
• Request-scoped data — User-specific content that won't change during the session
• Avoiding waterfalls — Fetch data where it's needed, not in a parent component

// Good: Direct DB access in server component
async function ProductPage({ ctx }) {
  const product = await db.product.findUnique({ where: { id: ctx.params.id } });
  return <ProductDetails product={product} />;
}

Use Server Functions ("use server") When:

• Mutations — Create, update, delete operations
• Form submissions — Native form handling with progressive enhancement
• User-triggered actions — Button clicks that modify server state

// Good: Server function for mutations
'use server';
export async function updateProduct(formData: FormData) {
  const { ctx } = requestInfo;
  await db.product.update({ where: { id: formData.get('id') }, data: { ... } });
}

Use API Routes / fetch() When:

• Polling or real-time updates — Data that changes after initial render
• Infinite scroll / pagination — Loading more content client-side
• Shared endpoints — Same API consumed by web, mobile, or third parties
• Client-side caching — SWR/React Query patterns for stale-while-revalidate
• Non-React consumers — Webhooks, external services, CLI tools

// API route for polling/shared access
// src/app/api/notifications/route.ts
export async function GET(request: Request) {
  const notifications = await db.notification.findMany({ ... });
  return Response.json(notifications);
}

// Client component polling
'use client';
function Notifications() {
  const [data, setData] = useState([]);
  useEffect(() => {
    const poll = () => fetch('/api/notifications').then(r => r.json()).then(setData);
    const interval = setInterval(poll, 5000);
    return () => clearInterval(interval);
  }, []);
  return <NotificationList items={data} />;
}

Decision Matrix

Anti-patterns to Avoid

❌ Don't create API routes just to fetch in RSC — Access DB directly

// Bad: Unnecessary API hop
async function Page() {
  const res = await fetch("/api/products"); // Why?
  const products = await res.json();
}

// Good: Direct access
async function Page({ ctx }) {
  const products = await db.product.findMany();
}

❌ Don't use RSC for frequently-changing data — Use client-side fetching

// Bad: Stock price in RSC (stale immediately)
async function StockTicker() {
  const price = await getStockPrice(); // Stale after render
  return <span>{price}</span>;
}

// Good: Client component with polling
("use client");
function StockTicker() {
  const { data } = useSWR("/api/stock", fetcher, { refreshInterval: 1000 });
  return <span>{data?.price}</span>;
}

Context

Context shares data globally between server components per-request. Populated by middleware, accessible via:

• ctx prop in Page components
• requestInfo.ctx in server functions

Manual Rendering

For advanced use cases, render components imperatively.

renderToStream

Returns a ReadableStream that decodes to HTML.

const stream = await renderToStream(<NotFound />, { Document });

const response = new Response(stream, {
  status: 404,
});

Options:

• Document: Wrapper component for the rendered element
• injectRSCPayload = false: Inject RSC payload for client hydration
• onError: Error callback during rendering

renderToString

Returns an HTML string.

const html = await renderToString(<NotFound />, { Document });

const response = new Response(html, {
  status: 404,
});

Limitation: renderToStream and renderToString generate HTML only. They don't handle Server Actions or client-side transitions. For fully interactive routes, use render() from defineApp.

Component Decision Guide

File Organization

src/app/pages/todos/
├── TodoPage.tsx      # Server component (page)
├── AddTodo.tsx       # Client component
└── functions.tsx     # Server functions