# rsc-kit

> React Server Components as a Vite plugin — deploy to Bun, Node, Workers, Vercel or Deno.

Index: https://docs.rsc-kit.dev/llms.txt

# Coming from Next.js

> What carries over unchanged, what to rename, and what is different on purpose.

Source: https://docs.rsc-kit.dev/coming-from-next/ · Markdown: https://docs.rsc-kit.dev/coming-from-next/index.md

Most of a Next.js app directory moves over as it is. This page is the rest,
in the order a port meets it.

## What is the same

The `app/` conventions are the same conventions: `layout.tsx`, `page.tsx`,
`loading.tsx`, `error.tsx`, `not-found.tsx`, `route.ts`, `[slug]`,
`[...path]`, `(group)`, `@slot` and `(.)intercept`. `"use client"` and
`"use server"` mean what they mean in React. `cookies()` and `headers()` are
async and have the same names. `redirect()`, `notFound()`,
`generateStaticParams()` and `export const metadata` all exist. Streaming
through `<Suspense>` works the same way, because it is React doing it.

Copy `src/app` across first and fix imports second. Most files need only the
imports.

## Imports

| Next.js | here |
| --- | --- |
| `next/link` | `@rsc-kit/core/Link` — `href` is typed to your routes, and `search` to the page's schema |
| `useRouter().push(url)` | `visit(url)` from `@rsc-kit/core/router`; `replace: true` for `.replace()` |
| `useRouter().refresh()` | `refresh()` from `@rsc-kit/core/router` — or better, `revalidate()` from the action |
| `usePathname()` | `@rsc-kit/core/usePathname` |
| `useSearchParams()` | `@rsc-kit/core/useSearchParams`, or [nuqs](/guides/routing#search-params-as-state) with our adapter |
| `useParams()` | the page's `params` prop, passed down |
| `cookies()`, `headers()` from `next/headers` | the same names from `@rsc-kit/core/request` |
| `redirect()` from `next/navigation` | `@rsc-kit/core/redirect` |
| `notFound()` | `@rsc-kit/core/not-found` |
| `revalidatePath()`, `revalidateTag()` | `revalidate('tag')` from `@rsc-kit/core/revalidate` — see below, it is narrower |
| `Metadata` from `next` | `@rsc-kit/core/metadata` — `metadataBase`, `openGraph`, `twitter`, `icons` as you had them |
| `next/font` | [Fontsource](/guides/fonts): install the font, import its CSS |
| `next/image` | [unpic](/guides/images) for a CDN, `vite-imagetools` for files in the repo |
| `next/script` | [a `<script>` tag](/guides/third-party-scripts): React 19 hoists and dedupes `async` scripts itself |
| `NEXT_PUBLIC_*` | `VITE_*`, read through `import.meta.env`; everything else stays `process.env` on the server |
| `next.config.js` | `vite.config.ts` — Tailwind, aliases and plugins are Vite's |
| `next-safe-action` | `createActionClient()` — same shape, [below](#actions) |

## Different on purpose

### Nothing is dynamic by declaration

There is no `export const dynamic = 'force-dynamic'` and no `revalidate = 60`.
A page is frozen at build time unless it **reads the request** — `cookies()`,
`headers()`, `searchParams`, `await connection()` — and then it renders per
request, or as a shell with the reading part streamed in. The build prints
which, and why:

```
  ○  /about               no js
  ◐  /orders              85 kB
 dynamic — called cookies()
```

`await connection()` is the one explicit mark, for a page that must render per
visitor and does not happen to read anything. Time-based ISR does not exist:
a frozen page changes when you build, a dynamic one on every request, and
[edge caching](/guides/edge-caching) covers the middle.

### Middleware is per directory, not one file at the edge

Next has one `middleware.ts` that runs on a matcher, on the edge runtime, with
a restricted API. Here a `middleware.ts` sits in the directory it protects,
runs on the server with the full API, and covers everything below it:

```ts title="src/app/admin/middleware.ts"
export default async function middleware() {
  if (!(await currentUser())?.isAdmin) redirect('/login');
}
```

It does not run for actions — an action renders no route — which is why the
check for an action belongs in the action. See [Authorization](/guides/authorization).

### Actions

`next-safe-action` users will find the same shape under a different name.
`createActionClient()` chains middleware, validates with any Standard Schema,
and **returns** failures as `{ validationErrors }` or `{ serverError }` rather
than throwing them across the wire:

```ts
export const client = createActionClient().use(async ({ next }) => {
  const user = await currentUser();
  if (!user) throw new ServerAuthenticationError();
  return next({ ctx: { user } });
});

export const createPost = client.input(schema).handler(async ({ input, ctx, fieldErrors }) => {
  if (await slugTaken(input.slug)) return fieldErrors({ slug: 'Already taken' });
  return save(input, ctx.user);
});
```

`returnValidationErrors(schema, { email: { _errors: [...] } })` becomes
`return fieldErrors({ email: 'Account not found' })`. `useAction` from
next-safe-action is `useActionState`, or a `<Form action={createPost}>` that
reads the returned errors on its own. The build lists any action not built
from a client, because nothing checks who calls those.

### Revalidation is targeted

`revalidatePath('/orders')` re-renders the page. `revalidate('orders')`
re-renders the [section](/guides/sections) registered under that name and
sends it back **with the action's own response** — one request, the rest of
the page untouched, a half-typed input elsewhere on it still typed. Wrap the
region in `section('orders', Orders)` and name it from the action.

### Forms

`<Form>` from `@rsc-kit/core/form` submits to an action, shows pending state,
places field errors, and works before hydration. It is uncontrolled by
default like React Hook Form's `register`, with `field()` for a controlled
binding and `useField()` for a value read anywhere. shadcn's `Field`
components fit as they are. See [Forms](/guides/forms).

### Query strings are typed

Export a schema beside the page and the values arrive parsed; the same schema
types every `<Link search={…}>` to it. `Number(searchParams.get('page'))` is
not a thing you write here. See [URL validation](/guides/url-validation).

### There is no image optimizer, and no `opengraph-image.tsx`

Both are processes Next runs for you at request time. Put `opengraph-image.png`
in `src/app` and it is picked up; generate one at build time if it has to be
generated. Images: [unpic or imagetools](/guides/images).

### Testing does not need a browser

`createTestApp()` hands back the deployed `Request → Response` handler.
Actions, queries and api routes are plain functions. There is no equivalent
in Next; see [Testing](/guides/testing).

## The porting order that worked

1. `bun create rsc-kit@latest` and copy `src/app` over the scaffold's.
2. Fix imports from the table. `bun run typecheck` finds the rest.
3. `bun run build` and **read the output**: every route that is not `○` says
   why. Most surprises are a `cookies()` in a layout making everything
   dynamic — the build says so under the summary.
4. Actions not built from a client are listed. Decide for each.
5. `bun run check`. Then a browser, for the parts that are a browser's.

An agent doing the port has all of this: the `.mcp.json` in the scaffold
answers `how_to({ topic })` and `read_guide({ slug })` from the installed
version, and the build report is what it reads instead of guessing.

# Getting started

> Serve React Server Components from any JavaScript backend.

Source: https://docs.rsc-kit.dev/getting-started/ · Markdown: https://docs.rsc-kit.dev/getting-started/index.md

import CodeFromFile from "@/components/CodeFromFile.astro";

A host is a `Request` in and a `Response` out. You do not normally write the
server that calls it: [Nitro](https://nitro.build) builds one around your route
tree, and where it runs is a preset in `vite.config.ts`.

## Building

Three steps, and only the first is required:

```bash
npm run dev         # vite — serves from source, no build step
npm run build       # bundles, renders every route once, then Nitro assembles .output/
npm run start       # runs .output/server/index.mjs
```

`dev` is Vite's own dev server, and edits reach the browser without a reload:

| you edit | what happens |
| --- | --- |
| a client component | Fast Refresh — the code updates and its state survives |
| a page or layout | the payload is re-fetched and the tree re-rendered |
| adding or deleting a page | the server restarts to pick up the new route table |

The browser never holds a server component, so Vite cannot hot-swap it. Instead
the client re-fetches the page — which remounts any client component below, so
their state resets.

Edit a client component directly and its state does survive; that is Fast
Refresh.

The restart on a new page is because the route tree is read when the server
starts: a page that appears later would otherwise 404 while sitting right there
on disk.

`build` ends by rendering every route once and storing what it can, which is
what turns a route into a file on disk instead of a render per request.

It is part of `build` rather than a separate command because forgetting it costs
you everything and looks like nothing — every page still works, each one just
renders again for every visitor.

Turn it off with `rscKit({ prerender: false })` when the build machine
cannot do what the pages need. See [Static
generation](/guides/static-generation).

> **There is no NODE_ENV to set**
>
> React picks its build from it, and getting it wrong gives you a page that
> renders perfectly and never hydrates. The build stamps the mode it ran in
> into the server bundles, so a server is production because it was built that
> way — `npm run start` needs no environment at all.

## Compiling to a single binary

With the Bun preset the whole application ends up in one file:

```bash
npm run compile   # builds, then bun build --compile
./dist/app
```

That works because the generated config sets `serveStatic: 'inline'`. Without
it the binary compiles, starts, serves pages, and 404s every asset — the static
path resolves into Bun's virtual filesystem, where the files on disk are not.

### What it costs

Measured on the example — eleven routes, 240 KB of assets, 164 KB of stored
pages:

| | compiled | run from `.output/` |
| --- | --- | --- |
| Cold start | 45 ms | 56–65 ms |
| Resident, idle | 18 MB | 19 MB |
| Resident, after 300 requests | 27 MB | 32 MB |
| On disk | 62 MB | 240 KB + a runtime |

Memory is flat between the two: the binary holds its assets as `Response`
objects built at boot, which for 240 KB is nothing, and both settle in the high
twenties once React has warmed up. A live render is what moves it — 40 MB after
200 of them — and that is the renderer, not the packaging.

> **What compiling is actually for**
>
> Deployment shape, not speed. One file, no `node_modules`, no runtime to
> install. Throughput between the two is inside the noise of any benchmark I
> could run on one machine — the only differences I can defend are the ~15 ms
> of cold start and the shape of what you ship.

> **What embedding costs**
>
> Every asset goes in whole. Three files is nothing; a media-heavy app is
> hundreds of megabytes of executable, with no CDN in front and no streaming
> from disk. Keep large or rarely-read files outside the binary and serve them
> from wherever they already live.
>
> Frozen pages are not embedded either. The build writes them to
> `.output/server/rsc-static` and the server reads them from beside itself; a
> binary has no filesystem to read, so it renders those pages live. Everything
> still answers — what you lose is the stored render, not the page.

## If you work with an AI agent

The scaffold writes an `AGENTS.md` beside your `README.md`. Claude Code, Cursor
and the rest read it, and it covers the things an agent otherwise gets wrong
from React or Next habits — `"use client"` versus `"use server"`, where an
authorisation check belongs, which props are async, and that the build output is
worth reading rather than ignoring.

Beside it is `.mcp.json`, which connects the [MCP server](/guides/mcp): Claude
Code asks you to approve it on first use, and from then on an agent can read
what your last build actually did instead of guessing.

And there is a test to extend, `tests/app.test.ts`, which goes through the
real build: `bun run check` runs typecheck, lint and tests together, and is
the one command an agent — or you — runs before calling something done.

Edit it as your project grows. It is yours; nothing regenerates it.

There is also an MCP server, which answers from your actual build rather than
from memory:

```sh
claude mcp add rsc-kit -- npx -y @rsc-kit/mcp
```

It can say why a particular page is not static, what each route ships to the
browser, and how to build a form or an api route the way this framework
expects. See [Working with an AI agent](/guides/mcp/).

# API routes

> Web-standard endpoints, colocated with your pages, with no configuration.

Source: https://docs.rsc-kit.dev/guides/api-routes/ · Markdown: https://docs.rsc-kit.dev/guides/api-routes/index.md

Server actions and [queries](/guides/queries/) cover your own client. An API
route is for everyone else: a webhook, an OAuth callback, a health check, a
mobile app, a third party.

`src/app/api/health/route.ts` answers `/api/health`:

```ts title="src/app/api/health/route.ts"
export function GET(request: Request): Response {
  return Response.json({ ok: true, at: new Date().toISOString() })
}
```

The export name is the method. The argument is an ordinary `Request` and a
`Response` goes back — no event object, no adapter, no handler wrapper.

Nothing to configure. `route.ts` lives in the same `src/app` tree as your
pages, and the url comes from the directory the same way a page's does.

It also runs everywhere the pages do. A route is answered by the same handler
that answers a page, not by a separate server, so a Worker, a Node process and a
Bun binary all get the identical behaviour from the identical code — verified on
Cloudflare Workers, which is the one with no Node apis to fall back on.

## One export per method

```ts title="src/app/api/echo/route.ts"
export async function POST(request: Request): Promise<Response> {
  const body = (await request.json()) as { name?: string }

  if (!body.name) return Response.json({ error: 'name is required' }, { status: 422 })

  return Response.json({ greeting: `Hello, ${body.name}` }, { status: 201 })
}

export function GET(): Response {
  return Response.json({ usage: 'POST { "name": "…" }' })
}
```

```
POST /api/echo  {"name":"Ada"} → 201 {"greeting":"Hello, Ada"}
POST /api/echo  {}               → 422 {"error":"name is required"}
GET  /api/echo                   → 200 {"usage":"POST { \"name\": \"…\" }"}
PUT  /api/echo                   → 405  Allow: GET, POST, HEAD
```

`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` and `OPTIONS`. Two you do not
have to write:

- **The 405.** A method you did not export is refused, with an `Allow` header
  naming the ones you did — without which a client cannot tell what would have
  worked.
- **`HEAD`.** Answered by your `GET`, with the body stripped, which is what the
  spec says `HEAD` is. Refusing it breaks link checkers and anything that probes
  before it fetches.

Reading a body is the web api: `request.json()`, `.formData()`, `.text()`.

A route that exports no method at all fails the build rather than becoming a url
that answers 405 to everything.

## Dynamic segments

`[name]` and `[...rest]` work as they do for pages, and bind into the second
argument:

```ts title="src/app/api/greet/[name]/route.ts"
export function GET(request: Request, { params }: { params: { name: string } }): Response {
  return Response.json({ greeting: `Hello, ${params.name}` })
}
```

```
GET /api/greet/ada → {"greeting":"Hello, ada"}
```

It is the same router pages use, so a static segment beats a dynamic one —
`/api/user/me` is answered by `me/route.ts` rather than `[id]/route.ts`,
whichever was declared first.

## Guarding one

A route runs whatever `middleware.ts` files sit above it, exactly as a page in
that directory would — so an endpoint under a guarded path is guarded without
writing the check twice. A refusal is a `401` or `403` rather than a redirect,
because a `fetch` would follow the redirect and hand back a login page as
though it were your data.

See [Authorization](/guides/authorization/#protect-an-api-route).

## The build answers what it can

A route is frozen by default, exactly the way a page is, and for the same
reason — so there is one model to learn rather than two.

At build time every `GET` is called once with no request behind it. A route
that answers without reading anything is stored, headers and status and all,
and served from disk afterwards:

```text
  ○  /api/health
  ○  /api/pricing
  ƒ  /api/me
 reads the request — headers
  ƒ  /api/posts/_id_
 one url per param value, and none are listed
```

Nothing to configure and nothing to opt into. Read the request and the route
opts itself out, because with no request to read the accessors never resolve:

```ts
export async function GET(request: Request) {
  const who = request.headers.get('Authorization')  // ƒ — per request
}
```

`cookies()`, `headers()` and `await connection()` do the same, and
`connection()` is how you say it deliberately when nothing else in the route
happens to give it away.

A route is left to run per request when it:

- **reads the request** — headers, the body, the signal
- **takes a parameter**, since the build does not know which values exist
- **sits under a `middleware.ts`**, because a guarded route answers differently
  per caller and one stored answer served to everyone is how a guard disappears
- **sets a cookie**, which is an answer for one visitor whatever the route
  read to decide on it — stored, the build's cookie would be handed to everyone
- **answers with bytes rather than text**, which is a file and wants serving as
  one
- **does not finish**, which with no request behind it usually means it was
  waiting on one

And one thing it stores with a warning, the same one a page gets: a route
that froze `Date.now()` or `Math.random()` keeps whatever that returned at
build time, and a json body has no browser to move the value to. Read the
request — `await connection()` is enough — and it runs on demand.

### What is never stored

Only `GET`. A `POST`, `PUT`, `PATCH` or `DELETE` is something meant to happen,
and an answer kept on disk is an answer to something that already did.

A request carrying a **query string** runs the route only when the route reads
one. `searchParams` is awaited rather than handed over resolved, so a route that
never reaches for it provably does not vary by the query — and its stored answer
is served for `?utm_source=anything`, which is most of the links people actually
follow. Await it, or export a `searchParams` schema, and the stored answer is
kept for the bare url alone.

## What to use when

| | |
| --- | --- |
| your client reads data | a [query](/guides/queries/) — typed, no endpoint to write |
| your client writes data | a [server action](/guides/server-actions/) |
| something that is not your client | an API route |

Reach for an API route when the caller cannot import your functions. If it can,
the typed call is better than a url both sides have to agree on.

:::note[Not prerendered]
An api route runs per request. A page that is the same for everyone is
[frozen at build time](/guides/static-generation/); a route is not, because the
build has no request to give it — no method, no body, no headers.

For data that never changes and is read by outsiders, a
[query](/guides/queries/) with `cache: "public"` gets you a cacheable answer
without giving up the type.
:::

# Authorization

> Protecting pages, server actions and API routes.

Source: https://docs.rsc-kit.dev/guides/authorization/ · Markdown: https://docs.rsc-kit.dev/guides/authorization/index.md

import CodeFromFile from "@/components/CodeFromFile.astro";

There are three ways into your app — a page, a server action, an API route —
and each needs its own check. Guarding one does not guard the others.

## Protect a page

Put a `middleware.ts` in the directory you want to protect:

```ts title="src/app/admin/middleware.ts"
import { redirect } from '@rsc-kit/core/redirect';
import { currentUser } from '../../auth';

export default async function middleware() {
  const user = await currentUser();

  if (!user?.isAdmin) redirect('/login');
}
```

It runs before anything in that directory or below it renders. Return nothing
to allow; redirect or throw to refuse.

Middleware compose up the tree like layouts — outermost first — and **every**
request runs the whole chain: a full page load, a navigation, a prefetch, a
revalidation. There is no flag to remember; the file is the declaration.

> **Do not put the check in a layout**
>
> It looks like it works, and it does on a full page load. But a navigation
> tells the server which layouts the browser already has, and the server skips
> them — that is what makes navigation fast. A request can claim to have your
> layout, and then the check never runs.
>
> `middleware.ts` is never skipped.

## Protect a server action

An action is a public endpoint. Anyone can call it directly:

```bash
curl -X POST /_rsc/action \
  -H 'X-RSC-Action: 0339292364be#placeOrder' \
  -H 'X-RSC-Content-Type: text/plain;charset=UTF-8' \
  --data-binary '["a rubber duck"]'
```

That is not a hole to plug — an action *is* an RPC endpoint and its id is not a
secret. It means the check goes **inside the action**, not in the component that
renders the button:

```ts title="src/actions.ts"
'use server'

import { currentUser } from './auth';

export async function placeOrder(item: string) {
  const user = await currentUser();

  if (!user) throw new Error('Not signed in');

  // …
}
```

> **Middleware does not cover actions**
>
> Middleware runs when a route renders. An action renders no route, so none of
> them run. Each entry point defends itself.

### Write the check once

One action is fine. Twenty is twenty chances to forget, and the one you forget
is the one that matters. Put the check on a client and build every action from
it:

```ts title="src/server/client.ts"
'use server'

import { createActionClient } from '@rsc-kit/core/action'

export const client = createActionClient()
  .use(async ({ next }) => {
const user = await currentUser()

if (!user) throw new ServerAuthenticationError()

return next({ ctx: { user } })
  })
```

```ts title="src/server/orders.ts"
'use server'

import { client } from './client'

export const placeOrder = client.input(schema).handler(async ({ input, ctx }) =>
  orders.create(ctx.user.id, input),
)

export const listOrders = client.query(async ({ ctx }) => orders.forUser(ctx.user.id))
```

`ctx.user` is typed and non-null inside the handler, because the only way to get
there was through the middleware that put it in. **An action cannot be added
without the check** — not because a rule says so, but because there is no other
constructor to reach for.

`.handler()` makes an action, `.query()` makes a [read](/guides/queries/), and
both run the same chain. Add a second `.use()` for a role check and it applies
to everything built from that client:

```ts
export const admin = client.use(async ({ ctx, next }) => {
  if (!ctx.user.isAdmin) throw new ServerAuthorizationError()

  return next({ ctx })
})
```

Authorise on **identity, not arguments**. `cancelOrder(id)` that trusts the id
is the whole of an IDOR — the caller chooses the id, so the handler has to check
the row belongs to `ctx.user`.

## Protect an API route

A [route](/guides/api-routes/) runs the same middleware a page in that directory
would. Put it under a guarded path and it is guarded:

```text
src/app/admin/
  middleware.ts          ← guards everything below
  page.tsx               ← guarded
  api/export/route.ts    ← guarded too
```

A refused route answers **401** or **403** rather than redirecting, and names
the destination in `X-RSC-Redirect` if the middleware wanted one. A `fetch`
would follow a redirect and hand back a login page as though it were your data.

For a route with no middleware above it, check inside the handler:

```ts title="src/app/api/orders/route.ts"
import { currentUser } from '../../../auth';

export async function GET(): Promise<Response> {
  const user = await currentUser();

  if (!user) return new Response('Unauthorized', { status: 401 });

  return Response.json(await orders(user.id));
}
```

## Read the session

There is no request object. `headers()` and `cookies()` read the one in flight:

```ts title="src/app/[locale]/middleware.ts"
import { redirect } from '@rsc-kit/core/redirect';
import { cookies, headers } from '@rsc-kit/core/request';

export default async function middleware() {
  const jar = await cookies();
  const locale = jar.get('locale') ?? negotiate((await headers()).get('accept-language'));

  if (!locale) redirect('/en');
}
```

They work anywhere a request is in flight — middleware, server components,
actions, API routes — so whatever you already use for locale, feature flags or
tenants works inside a plain async function. `request()` gives you the whole
`Request` for anything the two do not cover.

They are async for a reason worth knowing: at build time there is no request, so
a read *suspends*. React freezes the shell above it and only the part that
wanted a header renders per visitor. A synchronous read would force the whole
page to re-render for everyone.

### Ask once

Middleware wants to know who you are; the layout wants their name; the page
wants their permissions. Wrap the lookup in `cache()` and that is one query:

```ts title="src/session.ts"
import { cache } from '@rsc-kit/core/cache';

export const currentUser = cache(async () => {
  const id = await sessionId();

  return db.user(id);
});
```

The scope is one request. Two requests never see each other's answers, and
nothing survives between them. Outside a request it just calls through, so
shared code does not need to know where it is running.

## Set a cookie

Middleware runs before the response exists, which makes it the place to put a
header or a cookie on it:

Actions can write too, which is the case that matters — signing someone in is a
mutation that has to leave a cookie behind:

```ts title="src/app/login/actions.ts"
'use server';

import { action } from '@rsc-kit/core/action';
import { cookies } from '@rsc-kit/core/request';

export const login = action.input(credentials).handler(async ({ input }) => {
  const session = await authenticate(input);

  (await cookies()).set('session', session.token, {
httpOnly: true,
secure: true,
sameSite: 'lax',
maxAge: 60 * 60 * 24 * 7,
  });
});
```

`get`, `set` and `delete` over the request in flight is the whole surface an
auth library needs, so you can wire in whichever one you use.

> **A component is too late**
>
> By the time a page renders, the status and headers are already on the wire.
> Writing from a component throws and tells you to move it to middleware —
> rather than accepting the call and quietly dropping it.

## A guarded page can still be frozen

Whether the content is the same for everyone, and whether *you* may see it, are
different questions. The build answers the first; middleware answers the second,
per request. So an internal page whose bytes never vary is frozen at build time
and the middleware decides who gets the file:

| Route | Navigation |
| --- | --- |
| Guarded and frozen — check, then serve from disk | 6.7 ms |
| Guarded, rendered on demand | 2626.7 ms |
| Unguarded, frozen | 0.6 ms |

The check runs before the file is read, so a refusal never touches it.

> **Two places this does not hold**
>
> **A static export cannot guard anything.** A static host serves files without
> running code, so exporting a guarded route publishes it to whoever asks.
>
> **Do not put a guarded page in a shared cache.** Your origin runs the check; a
> CDN holding the response serves it to the next caller without asking.

## Where each check goes

| Question | Where it goes |
| --- | --- |
| May this person see this section? | `middleware.ts` in its directory |
| May this caller run this action? | Inside the action |
| May this caller use this endpoint? | Inside the route handler |
| Should the page show different things to different people? | The page — it renders per request anyway |

# Asking once per request

> cache() — one lookup, however many places need it.

Source: https://docs.rsc-kit.dev/guides/caching/ · Markdown: https://docs.rsc-kit.dev/guides/caching/index.md

Middleware checks who you are. The layout wants their name. The page wants their
permissions. That is three calls and one answer.

Wrap the lookup:

```ts
import { cache } from '@rsc-kit/core/cache'

export const currentUser = cache(async () => db.user(await sessionId()))
```

Now call it wherever you need it. The first call runs; the rest get the same
answer:

```tsx
export async function middleware() {
  if (!(await currentUser())) redirect('/login')
}

export default async function Page() {
  const user = await currentUser()   // already resolved

  return <h1>Hello {user.name}</h1>
}
```

## One request, and no further

Two requests in flight never see each other's answers, and nothing survives into
the next one. The scope opens when the request arrives and is torn down with it.

That is the whole safety story: a table that outlived its request would not be a
stale cache, it would be one visitor seeing another's data.

## Arguments

Compared the way React compares them — primitives by value, objects by identity:

```ts
const post = cache(async (id: string) => db.post(id))

post('a')   // runs
post('a')   // reuses the first
post('b')   // runs
```

Two objects that look the same are two different calls, so pass an id rather
than an object when you want the reuse.

> **Not React's cache()**
>
> Same idea, wider scope. Middleware runs before any component does, which is
> exactly where the duplicate lookups start — and React has no scope open yet.

# Rendering per request

> Marking work that belongs to the visitor, not to the build.

Source: https://docs.rsc-kit.dev/guides/connection/ · Markdown: https://docs.rsc-kit.dev/guides/connection/index.md

Most pages can be rendered once, at build time, and served as files. Some work
cannot: a query whose database the build machine cannot reach, or a value that
has to differ per visitor.

`connection()` marks that work.

```tsx title="src/app/orders/page.tsx"
import { connection } from '@rsc-kit/core/request'

export default async function OrdersPage() {
  await connection()

  const rows = await db.query('select * from orders')

  return <ul>{rows.map((r) => <li key={r.id}>{r.reference}</li>)}</ul>
}
```

At build time it never resolves, so **nothing after it runs** — the query is not
made, and the build needs no database. At request time it resolves immediately
and the component runs normally.

## Call it once

This is the mistake worth avoiding:

```tsx
await connection()

const orders = await db.orders()
await connection()          // ← does nothing
const customers = await db.customers()
await connection()          // ← does nothing
```

It is a **barrier, not a wrapper**. Everything after it in that component
belongs to the request, however many calls that turns out to be. The second and
third calls are already covered by the first.

One call, as early as the work begins. That is the whole API.

## It needs a boundary above it

The build stores what it *can* paint. If `connection()` is reached before
anything has painted, there is nothing to store:

```tsx
export default async function Page() {
  await connection()        // nothing above it has rendered

  return <h1>{await something()}</h1>
}
```

Give it a boundary and the page becomes a shell — the layout and headings are
stored, and the marked part arrives per request:

```tsx
export default function Page() {
  return (
<>
  <h1>Orders</h1>
  <Suspense fallback={<p>Loading orders…</p>}>
    <Orders />          {/* calls connection() inside */}
  </Suspense>
</>
  )
}
```

A `loading.tsx` beside the page does the same thing for everything below it.
Without either, the build refuses the route rather than storing a blank page,
and tells you which one to add.

## When you do not need it

A query the build **can** run, whose answer is the same for every visitor, wants
none of this. Let it freeze — that is the whole benefit of prerendering, and
marking it per-request gives every visitor a render they did not need.

Use it when the build genuinely should not do the work:

- the database or API is not reachable from the build machine
- the value must differ per visitor
- the data changes faster than you deploy

## Same as Next.js

Same name and same behaviour as Next's `connection()`, so there is nothing new
to learn if you have used it.

You will reach for it less often here, though. The build classifies routes by
rendering them rather than asking you to declare, so most dynamic pages are
already understood without a marker.

# Serving shells from a CDN

> Putting build-time shells on the edge, and what rsc-kit does not do.

Source: https://docs.rsc-kit.dev/guides/edge-caching/ · Markdown: https://docs.rsc-kit.dev/guides/edge-caching/index.md

A prerendered page is a file. So is a PPR shell. Both can sit on a CDN and be
served without touching your origin.

## What the build gives you

```
build/static/
  about.html            a whole page, frozen
  posts/hello.html      likewise
  posts/[slug].ppr.html a shell — static parts frozen, holes still empty
  about.flight          the payload for a client-side navigation
  about.seg1.flight     the same, for a client already holding one layout
```

`.html` is a finished page. `.ppr.html` is a shell: the layout, nav and
everything outside a `<Suspense>` boundary, with the fallbacks still in place.
Neither contains per-visitor data — they were rendered at build time, in no
request's context, which is what makes them safe for a shared cache.

## Caching them

The host already sends the right header:

```
Cache-Control: public, max-age=0, must-revalidate
```

`public` says a shared cache may store it. `max-age=0, must-revalidate` says
**check with the origin first**. So a CDN in front of this holds the bytes but
still asks every time — which saves bandwidth and nothing else.

To actually serve from the edge, add a cache rule for the paths you want held,
and give the CDN an edge TTL. On Cloudflare that is a Cache Rule with *Edge TTL
→ Override origin*.

**Do not blanket-cache the whole site.** A route with middleware is deliberately
sent as:

```
Cache-Control: private, no-store
```

because middleware runs per visitor — that is a page whose content depends on
who asked. A zone-wide "cache everything" rule overrides that and serves one
person's gated page to everyone. Scope the rule to the paths you know are
static.

Deployments are handled for you: cached responses carry a build version, so a
new deploy does not leave old shells being served against a new payload.

## Finishing a shell at the edge

A shell has holes in it, and something has to fill them. That happens at your
origin, into the same response — the shell is written first, then the
boundaries it could not finish.

You get this with no configuration: request a PPR route and the document you
receive already contains its dynamic content.

A small inline script from React moves each hole into place as the HTML parses.
So the content appears without waiting for the app bundle or for hydration — on
a slow connection, the difference between a spinner and a page. It also means
the content is in the HTML a crawler reads.

This is not the same as working without JavaScript: with scripting off, the
fallbacks stay.

To serve the shell itself from a CDN, two endpoints exist for an edge worker:

```
GET  /_rsc/ppr-shell?url=/dashboard    the build-time shell, cacheable
POST /_rsc/ppr-resume?url=/dashboard   the holes, for this visitor
```

There is a complete Cloudflare implementation in
[`examples/cloudflare-ppr-worker`](https://github.com/rsc-kit/rsc-kit/tree/main/examples/cloudflare-ppr-worker),
with no KV and no build step. The cache fills itself from the shell endpoint: a
miss goes to the origin while the shell warms behind it, and a hit streams the
shell then pipes the resumed holes onto the same response.

### What the response looks like on the wire

Measured on a deployed worker, for a page whose hole takes 2.5 s:

```
headers          55 ms
first body byte  56 ms
shell heading    56 ms      ← the page is on screen here
fallback markup  56 ms
hole content   2549 ms      ← same response, no second request
stream complete 2549 ms
```

Before this, the same document finished in 2 ms and contained no hole at all —
the content arrived later, on a separate payload fetch, after React had
hydrated.

**The trade is that the response stays open until the holes finish.** Previously
the document closed immediately and `load` fired early; now it fires when the
slowest boundary resolves. Nothing a visitor sees is slower — the shell paints
at the same moment either way — but page-level metrics that key on `load` will
read differently, and a proxy with a short response timeout needs to allow for
the whole render rather than just the shell.

## Guarded routes are never cached

The shell endpoint answers `404` for any route that declares middleware. Such a
page is not cacheable by a shared cache at all, so it never becomes a cache
entry — refused at the source rather than checked at the edge.

The resume endpoint runs that route's middleware against **the caller's own
cookies**, and refuses before rendering anything. An edge worker must therefore
forward the visitor's request rather than making one of its own; a resume asked
for with no cookies is an anonymous visitor and gets an anonymous answer.

## What stays on your origin

Next's PPR protocol hands the postponed blob to the CDN and takes it back on the
resume, which means the resume endpoint parses something an attacker can write.
That is the shape of a known denial-of-service against it.

Here the endpoint takes a **url**. The origin reads its own state from disk, and
a body posted to it is ignored. This is only possible because — unlike a generic
CDN — the origin already has the artifact, so there is nothing to hand out and
take back.

## When a CDN owns the response

Everything above rests on one fact: on this host, a per-visitor response head
can only come from middleware. `responseHeaders()` and `cookies().set()` throw
outside it, so a route that declares no middleware has no way to acquire one —
which is why "declares middleware" is a safe answer to "is this cacheable".

An auth proxy in front of the app breaks that, and quietly. One with sliding
expiry re-issues the session on an ordinary `200`, so the response leaving your
CDN carries a `Set-Cookie` this host never sent. Marked `public`, that is one
visitor's session handed to the next.

**Give any path your proxy covers a `middleware.ts`**, even an empty one. That
is what makes a route covered here, and covered routes are excluded from every
cache decision: `private, no-store` on the page, and refused outright by the
shell endpoint.

Two things worth knowing about this failure if you go looking for it.

You cannot detect this by inspecting the response. Nothing added a
`Vary: Cookie`, and looking for `Set-Cookie` only catches the cookie version —
an `x-user-id`, a CSRF token or a locale header leaks the same way.

The reliable question is structural: who owns the response head on this route?

It fails both ways. The loud one is a session leaking to the next visitor. The
quiet one is the reverse — an anonymous response cached first, then served to
someone who should have had a session, silently signing them out. The first gets
reported; the second looks like a flaky login.

# Errors and 404s

> What a visitor sees when a page throws, or asks for a url nothing answers.

Source: https://docs.rsc-kit.dev/guides/errors/ · Markdown: https://docs.rsc-kit.dev/guides/errors/index.md

Two files, both optional, both following the same rule as `loading.tsx`: the
nearest one wins.

## When a page throws

Put an `error.tsx` in the directory you want to cover:

```tsx title="src/app/orders/error.tsx"
'use client'

import type { RouteErrorProps } from '@rsc-kit/core/RouteErrorBoundary'

export default function OrdersError({ error, reset }: RouteErrorProps) {
  return (
<section>
  <h1>That did not work</h1>
  <p>{error.message}</p>
  <button type="button" onClick={reset}>Try again</button>
</section>
  )
}
```

Anything below it that throws renders this instead. The layouts above stay on
screen — only the segment that failed is replaced.

`reset()` renders the segment again, for a failure that might not happen twice.
Navigating away clears it on its own.

:::caution[It has to be a client component]
`'use client'` at the top, or the build refuses it. Catching a render error is
a class component's job, it runs in the browser, and `reset` is a callback the
browser calls — none of which a server component can do.
:::

### What `error.message` says in production

React replaces it with a generic sentence and puts a hash on `error.digest`.
That is React, not this package: the real message could name a table, a query or
a path, and none of that should reach a browser.

Log the digest where you log the error, and the two line up.

### It does not catch everything

- **Errors in the layout above it.** The boundary sits inside that layout, so a
  layout that throws needs an `error.tsx` a directory up.
- **The build.** A page that throws every time it renders fails the build
  rather than shipping a stored error page. The boundary is for a request that
  goes wrong, not a page that is broken.

## When nothing answers the url

`src/app/not-found.tsx` is rendered for any url no route matches:

```tsx title="src/app/not-found.tsx"
import Link from '@rsc-kit/core/Link'

export default function NotFound() {
  return (
<main>
  <h1>No such page</h1>
  <p>Nothing answers that url. <Link href="/">Go home</Link>.</p>
</main>
  )
}
```

It renders through your root layout like any other page, and is served with a
real **404** — a page that says "not found" under a `200` is a page search
engines index.

An ordinary server component, so it can be `async` and read whatever it likes.
Without one, an unmatched url gets a plain `Not found` string.

### When the page has to decide

A url can match a route and still name nothing — `/posts/42` is a real route
and there may be no post 42. Only the page can know that, so the page says so:

```tsx title="src/app/posts/[slug]/page.tsx"
import { notFound } from '@rsc-kit/core/not-found'

export default async function PostPage({ params }) {
  const post = await findPost((await params).slug)

  if (!post) notFound()

  return <article>{post.title}</article>
}
```

Same page, same **404**. It throws, so nothing after it runs — and if you wrap
the call in a `try`/`catch`, rethrow what you do not recognise, or a missing
page becomes a blank region.

:::caution[Where you call it decides the status]
Called above every Suspense boundary — at the top of a page, in a layout —
nothing has been written yet, so the response is a real 404.

Called deeper, inside a boundary, the shell has already gone out with the
status line on it. The boundary shows its fallback instead and the status stays
`200`. If the status matters — and for anything a crawler or a cache sees, it
does — do the lookup above the boundary.
:::

# File uploads

> Sending files through a server action without encoding them.

Source: https://docs.rsc-kit.dev/guides/file-uploads/ · Markdown: https://docs.rsc-kit.dev/guides/file-uploads/index.md

A `File` is a value a server action can take. React's Flight format carries it
as binary, so there is nothing to encode on the way out and nothing to decode
on the way in.

## One file

```tsx title="src/components/AvatarUpload.tsx"
"use client";

import { useState } from 'react';
import { uploadAvatar } from '../actions';

export function AvatarUpload() {
  const [url, setUrl] = useState<string | null>(null);

  async function submit(formData: FormData) {
const file = formData.get('avatar') as File;

if (!file || file.size === 0) return;

setUrl(await uploadAvatar(file));
  }

  return (
<form action={submit}>
  <input type="file" name="avatar" accept="image/*" />
  <button type="submit">Upload</button>
  {url && <img src={url} alt="" />}
</form>
  );
}
```

The action receives the `File` itself — name, type, size and all:

```ts title="src/actions.ts"
'use server'

import { writeFile } from 'node:fs/promises';

export async function uploadAvatar(file: File): Promise<string> {
  const bytes = new Uint8Array(await file.arrayBuffer());

  await writeFile(`./public/avatars/${file.name}`, bytes);

  return `/avatars/${file.name}`;
}
```

Nothing about that is upload-specific: it is the same call, the same
serialisation and the same round trip as [any other server
action](/guides/server-actions).

## The whole form at once

An action can take the `FormData` instead of individual arguments, which is
usually simpler when the form mixes files and fields:

```tsx
"use client";

import { createPost } from '../actions';

export function NewPost() {
  return (
<form action={createPost}>
  <input name="title" />
  <textarea name="body" />
  <input type="file" name="cover" accept="image/*" />
  <button type="submit">Create</button>
</form>
  );
}
```

```ts title="src/actions.ts"
'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  const cover = formData.get('cover') as File;

  // …
}
```

## Several files

`formData.getAll` gives every file from a `multiple` input, and an array of
`File` serialises as readily as one:

```tsx
const files = formData.getAll('photos') as File[];

await uploadPhotos(files);
```

```ts title="src/actions.ts"
'use server'

export async function uploadPhotos(files: File[]) {
  for (const file of files) {
// …
  }
}
```

## Size

The whole body is buffered before the action runs — it is one `POST`, not a
stream — so an upload occupies memory for as long as it takes. The server
refuses a body over **8 MB** with a 413 before it holds a byte of it, and
the form reports that as a failed submission. Raise the ceiling when the app
genuinely uploads more:

```ts title="vite.config.ts"
rscKit({ maxActionBody: 32 * 1024 * 1024 })
```

Two consequences worth planning for:

- Keep the ceiling — and any limit a proxy in front imposes — as low as the app actually needs.
- For genuinely large files, do not send them through an action at all. Have the action mint a pre-signed URL and let the browser upload straight to storage; the bytes never touch your server.

# Fonts

> Self-hosted fonts from npm, and what next/font was doing for you.

Source: https://docs.rsc-kit.dev/guides/fonts/ · Markdown: https://docs.rsc-kit.dev/guides/fonts/index.md

Install the font, import its CSS, name it in a variable. Vite does the rest.

```sh
bun add @fontsource-variable/fraunces @fontsource-variable/geist
```

```css title="src/app/styles.css"
@import '@fontsource-variable/fraunces/full.css';
@import '@fontsource-variable/fraunces/full-italic.css';
@import '@fontsource-variable/geist';

:root {
  --font-display: 'Fraunces Variable', ui-serif, Georgia, Cambria, 'Times New Roman', serif;
  --font-sans: 'Geist Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
'Helvetica Neue', Arial, sans-serif,
'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
}
```

Put your font in *front* of a full stack rather than in place of one. Two things
the rest of the stack does that a bare `sans-serif` does not:

- **Emoji.** Geist has no emoji glyphs, so an emoji falls through to whatever is
  named after it. With nothing there, some Linux and older Android setups draw a
  monochrome glyph or a box. The four emoji fonts at the end are consulted only
  for characters the main font cannot draw, so they cost nothing.
- **A closer fallback.** During the `swap` window the browser shows the next
  font. `-apple-system` and `Segoe UI` are nearer Geist in width and x-height
  than Helvetica or Arial, so the moment of swap is a smaller jolt.

Those are Tailwind's own defaults, and shadcn's generated `--font-sans:
'Geist Variable', sans-serif` drops both. Keep the stack.

[Fontsource](https://fontsource.org) packages every Google font — and many
others — as woff2 files with the `@font-face` rules already written. Vite
hashes the files and serves them beside your other assets, so **nothing is
fetched from Google at runtime**, and nothing is downloaded at build time
either. The files are in `node_modules`.

## Porting from `next/font`

```ts
// before
const fraunces = Fraunces({
  variable: '--font-display',
  subsets: ['latin'],
  style: ['normal', 'italic'],
  axes: ['SOFT', 'opsz'],
  display: 'swap',
})
```

Every option there is something Fontsource already did:

| `next/font` | Fontsource |
| --- | --- |
| `variable: '--font-display'` | the `:root` rule above — you write the variable, once |
| `subsets: ['latin']` | every subset ships, each with a `unicode-range`; the browser fetches only the ones the page uses |
| `style: ['normal', 'italic']` | `full.css` and `full-italic.css` |
| `axes: ['SOFT', 'opsz']` | `full.css` — every axis of the variable font; `standard.css` is weight alone |
| `display: 'swap'` | already in every rule |
| `className={fraunces.variable}` | nothing — the variable is on `:root` |

So the layout loses its font imports and the `className` gains nothing:

```tsx title="src/app/layout.tsx"
import './styles.css'

export default function RootLayout({ children }) {
  return (
<html lang="en" className="h-full antialiased dark font-sans">
  …
</html>
  )
}
```

The subsetting is worth a second look, because it is *better* than what you
had. `next/font` asks you to name subsets at build time and ships those.
Fontsource ships all of them, each behind a `unicode-range`, and the browser
downloads only the ones a page's text actually needs — a Latin-only page
fetches one file whatever else is installed.

## Preloading

The one thing `next/font` did that needs a line here. It added a `<link
rel="preload">` for each font so the browser finds it before the stylesheet
does. Without one, the font is discovered when the CSS is parsed, and the text
shows in the fallback face for a moment longer.

Import the file for its url, and React hoists the link:

```tsx title="src/app/layout.tsx"
import fraunces from '@fontsource-variable/fraunces/files/fraunces-latin-full-normal.woff2?url'

export default function RootLayout({ children }) {
  return (
<html>
  <head>
    <link rel="preload" href={fraunces} as="font" type="font/woff2" crossOrigin="anonymous" />
  </head>
  …
```

`?url` is Vite's — it hands back the hashed path the build will serve. Preload
the one file the first paint needs, usually the Latin regular; preloading all
of them defeats the subsetting.

## A font that is not on npm

A file you own goes in `public/` and gets its own `@font-face` in your CSS, the
same as anywhere. Or in `src/` and imported with `?url` as above, which hashes
it.

# Forms

> Progressive forms, pending state and validation errors.

Source: https://docs.rsc-kit.dev/guides/forms/ · Markdown: https://docs.rsc-kit.dev/guides/forms/index.md

`<Form>` submits to a server action: a component
that handles the state for you, and a hook for when you want to hold it
yourself. Both cover validation errors, pending state, optimistic updates and
GET-form navigation.

## The `<Form>` component

The simplest way to handle forms. Works without any hooks — just pass a server action and use the render-prop for pending state and errors.

```tsx title="TodoForm.tsx"
"use client";

import { Form } from "@rsc-kit/core/form";
import { addTodo } from "./actions";

type FormValues = { title: string };

export default function TodoForm() {
  return (
<Form<FormValues> action={addTodo}>
  {({ pending, error }) => (
    <>
      <input name="title" placeholder="What needs to be done?" />
      {error('title') && <span className="text-red-500">{error('title')}</span>}
      <button disabled={pending}>
        {pending ? 'Adding...' : 'Add Todo'}
      </button>
    </>
  )}
</Form>
  );
}
```

The generic type parameter `<FormValues>` gives you autocomplete on `error()` and typed form data throughout the component.

### Props

```text
action — server action function (POST) or URL string (GET)
method — "get" | "post" (defaults to "post" for functions, "get" for strings)
resetOnSuccess — auto-reset form on success (default: true)
optimistic — callback for optimistic updates, called inside the transition
onSuccess — called with the action result on success
onError — called with validation errors on 422
onSubmit — called before submit, return false to cancel
prefetch — "hover" (default) | "mount" | "none" (GET forms only)
replace — replace history state (GET forms)
preserveScroll — keep scroll position (GET forms)
```

### useFormStatus

Nested components can access form state via context, without prop drilling:

```tsx title="SubmitButton.tsx"
"use client";

import { useFormStatus } from "@rsc-kit/core/form";

export function SubmitButton() {
  const { pending } = useFormStatus();

  return (
<button type="submit" disabled={pending}>
  {pending ? 'Saving...' : 'Save'}
</button>
  );
}
```

---

## Validation errors

When a submit fails validation, `<Form>` fills `errors`
themselves — there is no `try`/`catch` to write, and no state to hold. `errors`
is `Partial<Record<keyof T, string[]>>`: each field maps to its messages, and
`error('title')` returns the first one.

Where those errors come from depends on the host, and the components do not
care. See [Validation](/guides/validation).

An action can also name a field itself, for a refusal no schema could know
about. Through the [action client](/guides/server-actions#failing-on-something-a-schema-cannot-know)
`fieldErrors` arrives with the handler's arguments, typed to its input. A plain
`"use server"` function has no input type to draw on, so it imports the same
thing untyped:

```ts
'use server';

import { fieldErrors } from '@rsc-kit/core/action';

export async function addTodo(formData: FormData) {
  const title = String(formData.get('title'));

  if (await exists(title)) return fieldErrors({ title: 'Already on the list' });

  await save(title);
}
```

Either way, write `return fieldErrors(…)`. The form renders it under the field
you named, exactly as it would a schema failure.

---

## Optimistic updates

Optimistic updates go through React's `useOptimistic`. The callback runs inside the transition, so React reverts it automatically on error.

```tsx title="TodoList.tsx"
"use client";

import { useOptimistic } from "react";
import { Form } from "@rsc-kit/core/form";
import { addTodo } from "./actions";

type Todo = { id: number; title: string; done: boolean };

export default function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimistic] = useOptimistic(
todos,
(state, newTodo: Todo) => [...state, newTodo]
  );

  return (
<div>
  <ul>
    {optimisticTodos.map((todo) => (
      <li key={todo.id}>{todo.title}</li>
    ))}
  </ul>

  <Form
    action={addTodo}
    optimistic={(data) =>
      addOptimistic({ id: Date.now(), title: data.title as string, done: false })
    }
  >
    <input name="title" />
    <button>Add</button>
  </Form>
</div>
  );
}
```

## Search and filter forms

When `action` is a URL string, the form navigates via RSC instead of doing a full page reload. Form fields are serialized as query parameters. Supports prefetching for instant navigation.

```tsx title="SearchForm.tsx"
"use client";

import { Form } from "@rsc-kit/core/form";

export default function SearchForm() {
  return (
<Form action="/search" method="get" prefetch="hover">
  <input name="q" placeholder="Search..." />
  <select name="sort">
    <option value="relevance">Relevance</option>
    <option value="date">Date</option>
  </select>
  <button>Search</button>
</Form>
  );
}
```

This navigates to `/search?q=hello&sort=date` via SPA navigation. The nearest Suspense boundary streams in the results. With `prefetch="hover"`, hovering the submit button pre-warms the base URL for instant feedback.

## Using it with shadcn/ui

It works, and mostly by doing nothing. `<Form>` reads a native `FormData`, so
any component that ends up rendering a real form control is already compatible:

```tsx
<Form action={createPost} schema={schema}>
  {({ pending, errors }) => (
<>
  <Label htmlFor="title">Title</Label>
  <Input id="title" name="title" />
  {errors.title?.[0] && <p className="text-destructive">{errors.title[0]}</p>}

  <Select name="kind">
    <SelectTrigger><SelectValue /></SelectTrigger>
    <SelectContent>
      <SelectItem value="post">Post</SelectItem>
    </SelectContent>
  </Select>

  <Checkbox name="draft" />

  <Button disabled={pending}>{pending ? 'Saving…' : 'Save'}</Button>
</>
  )}
</Form>
```

`Input`, `Textarea`, `Button` and `Label` are styled native elements, so `name`
does what it always does.

**`Select`, `Checkbox`, `Switch` and `RadioGroup` also work** — they are Radix
underneath, and Radix renders a hidden native control whenever you give it a
`name`, for exactly this. Omit the `name` and it is invisible to the form; that
is the only thing to remember.

:::caution[Not shadcn's own `<Form>`]
shadcn's `<Form>`, `<FormField>` and `<FormControl>` are wrappers around
[react-hook-form](https://react-hook-form.com), which is a different system for
the same job — its own state, its own validation, its own submit. Use one or
the other, not both.

Ours gives you the field errors the *server* returned, which is the half a
client-side library cannot do.
:::

### shadcn's `Field` components

The newer `Field`, `FieldLabel`, `FieldError` and `FieldGroup` are plain
presentational components — they take props rather than reading a form
library's context, which is what the older `<FormField>` did. So they work here
directly:

```tsx
<Form action={reportBug} schema={formSchema}>
  {({ pending, errors }) => (
<FieldGroup>
  <Field data-invalid={!!errors.title}>
    <FieldLabel htmlFor="title">Bug title</FieldLabel>
    <Input id="title" name="title" aria-invalid={!!errors.title} />
    <FieldDescription>Keep it short and specific.</FieldDescription>
    <FieldError errors={errors.title?.map((message) => ({ message }))} />
  </Field>

  <Button type="submit" disabled={pending}>
    {pending ? 'Sending…' : 'Submit'}
  </Button>
</FieldGroup>
  )}
</Form>
```

`FieldError` takes `Array<{ message?: string }>`, and our `errors` are
`string[]` per field — hence the one `map`. Everything else is the same markup
you would write with any other form library.

The difference is where the errors came from. With TanStack Form or
react-hook-form those are the *client's* validation; here they are the client's
**and** whatever the server sent back, in the same object, because a refused
action returns its fields rather than throwing them away.

### Setting the values

The fields are uncontrolled, so an initial value is `defaultValue` — React's
own, nothing of ours:

```tsx
<Input id="title" name="title" defaultValue={post.title} />
```

After a refused submit the values are still there, because the DOM kept them:
nothing re-rendered the inputs, so nobody typed twice. That is the upside of
not owning the value.

The exception is a submit that happened **before hydration**, where the page
genuinely reloads. Then the server renders the page again, and putting the
values back is the server's job — return them from the action and render them
as `defaultValue`.

### Lists of values

A repeated name is an array:

```tsx
<Checkbox name="tags" value="react" />
<Checkbox name="tags" value="vite" />
// → { tags: ['react', 'vite'] }
```

With one ticked that is `'react'`, a string — which no `z.array()` will accept.
So for anything that is a list by nature, end the name in `[]` and it is always
an array:

```tsx
<Checkbox name="tags[]" value="react" />
// → { tags: ['react'] }
```

The brackets are dropped from the key, and it is the same spelling a value is
serialised back into — so a list survives a round trip.

### Nested and repeating groups

Names that describe a shape build it:

```tsx
<input name="address.city" />                 // → { address: { city } }
<input name="items[0].name" />                // → { items: [{ name }] }
<input name="items[0][name]" />               // the same field, other spelling
```

Which is the shape your schema was written against — and the shape whose errors
come back keyed the same way, because Standard Schema issue paths join with
dots too. A refused `address.city` is `errors['address.city']`.

Rows you add and remove are ordinary state; only the *names* have to line up:

```tsx
{rows.map((row, i) => (
  <input key={row.id} name={`items[${i}].name`} defaultValue={row.name} />
))}
```

### Controlling one field

Most fields need nothing — the DOM holds the value and it is read back on
submit. Two cases need more: a control with no native element behind it, and a
value you want to show *as it is typed*.

`field(name)` is for both. Spread it, the same way you would spread
react-hook-form's `<Controller>` render props:

```tsx
<Form action={reportBug} schema={formSchema} defaultValues={{ description: '' }}>
  {({ field, pending, errors }) => (
<Field data-invalid={!!errors.description}>
  <FieldLabel htmlFor="description">Description</FieldLabel>

  <InputGroup>
    <InputGroupTextarea id="description" {...field('description')} rows={6} />
    <InputGroupAddon align="block-end">
      <InputGroupText>{field('description').value.length}/100 characters</InputGroupText>
    </InputGroupAddon>
  </InputGroup>

  <FieldError errors={errors.description?.map((message) => ({ message }))} />
</Field>
  )}
</Form>
```

It gives you `{ name, value, onChange, onBlur }` — the same four things
`<Controller>` does, for the same reason.

`onChange` takes either a DOM event or a bare value, so a native input and a
Radix `Select` both work without a wrapper. A bound field is still an ordinary
named input, so it arrives in `FormData` with everything else: there is one
source of truth, and nothing merges.

Mix freely. Bind the one field that needs a character count and leave the rest
alone.

### How a field is doing

`fieldState(name)` is the other half — what is *known* about a field, as
opposed to what is spread onto it:

```tsx
{({ field, fieldState }) => {
  const title = fieldState('title')

  return (
<Field data-invalid={title.invalid}>
  <FieldLabel htmlFor="title">Bug title</FieldLabel>
  <Input id="title" {...field('title')} aria-invalid={title.invalid} />
  <FieldError errors={title.errors.map((message) => ({ message }))} />
</Field>
  )
}}
```

Two objects rather than one, which is react-hook-form's split and it is right
for a mechanical reason: `touched` and `invalid` are not DOM attributes, so a
single spreadable object would put them on the element and React would warn
about every one.

**A field is checked when it is left, not as it is typed.** An error that
appears while someone is halfway through an email address is a form arguing
with them; leaving the field is the moment they have finished saying what they
meant. `touched` is what separates "not filled in yet" from "filled in
wrongly".

It works on ordinary uncontrolled fields too — the form listens for `focusout`
rather than each field listening for `blur`, so `<Input name="title" />` is
covered without being bound to anything.

### After a successful submit

```tsx
{({ succeeded, recentlySucceeded }) => (
  <Button type="submit">{recentlySucceeded ? 'Saved ✓' : 'Save'}</Button>
)}
```

`recentlySucceeded` is the same thing for two seconds — the tick that appears
and fades. It is state rather than a timer in every form that wants one,
because the timer has to be cleared when the component goes away and that is
the part people forget.

### Why not a `<Field>` component

TanStack Form and react-hook-form both hand you a field through a render prop —
`<form.Field name="title" children={…}>`, `<Controller render={…}>`. It looks
like the more capable design, and the reason they need it is worth being precise
about, because the three of us are not in the same position.

**TanStack Form is controlled-first.** Every value lives in form state, so
without per-field subscriptions one keystroke would re-render every field. The
render prop is what scopes that, and the verbosity is the price of it.

**react-hook-form is uncontrolled-first**, like this. Its `register` is refs, not
state, so typing re-renders nothing — and `<Controller>` is the opt-in for the
fields that cannot work that way. The render prop there is doing something
narrower: it scopes the re-render of a *controlled* field to that field alone.

So the architecture here is react-hook-form's. The difference is what the
controlled opt-in costs: `field()` is a function call rather than a render prop,
which keeps the markup flat and means a bound field re-renders this component
rather than only itself.

That is the right trade for the number of controlled fields a form usually has —
one or two, for a character count or a control with no native element.

When it is not, put the field in its own component and subscribe there:

```tsx
import { useField } from '@rsc-kit/core/Form'

function Title() {
  const { field, invalid, errors, ...bound } = useField('title')

  return <Input {...bound} aria-invalid={invalid} />
}
```

`useField` re-renders **that component and nothing else** — not the form, not
its siblings. Which is what `<Controller>` achieves with a render prop, except
that the component you were going to write anyway is the boundary.

So the scoping is there when a form is large enough to need it, and the flat
markup is there when it is not. What their design also gives is per-field meta,
and that needed no render prop either: it is `fieldState()`.

### Reading the values from elsewhere

`useFormValues()` reads them from anywhere inside the form — a preview, a
summary, a count of what has changed:

```tsx
function Preview() {
  const { title } = useFormValues<{ title: string }>()

  return <h2>{title || 'Untitled'}</h2>
}
```

Only **bound** values are here. An uncontrolled input's value belongs to the
DOM, and nothing can know it changed without listening to it — bind a field with
`field()` or `useField` and it appears.

:::note[Inside the form, not outside it]
Both hooks read a context, so they work anywhere below `<Form>`. That is usually
enough, because the `<form>` element can wrap as much of the page as you like,
and a submit button outside it is `form="the-id"`.

Worth knowing what the alternatives do here, because it is not as different as
it looks. Reaching a form from another component is a context in all three:
react-hook-form has `<FormProvider>` and `useFormContext()`, and TanStack Form
has `createFormHookContexts()` with `useFormContext()` — which its own
documentation calls a bridge for integration constraints, to be avoided when
passing the form as a prop is possible. Ours needs no extra provider only
because `<Form>` already is one.

Where they are genuinely more flexible is *where the state is created*: their
`useForm()` is called by you, so it can be hoisted as far up as you like. For
the case where that matters — something that is not a descendant — create the
store yourself and hand it to the form:

```tsx
function Page() {
  const store = useFormStore<{ title: string }>({ title: '' })

  return (
<>
  <TopBar store={store} />          {/* not inside the form */}
  <Form action={save} store={store}>…</Form>
</>
  )
}

function TopBar({ store }) {
  const { title } = useFormValues<{ title: string }>(store)

  return <h1>{title || 'Untitled'}</h1>
}
```

`useFormStore` is the values and nothing else — no submit, no errors, no
optimistic updates. Creating it does not subscribe to it, so the component
holding it does not re-render on every keystroke and take the whole subtree
with it.

`useField(name, store)` and `useFormValues(store)` take one explicitly;
without one they read the context, which is what almost every form wants.
:::

## It works before hydration

The action goes on the `<form>` element as well as into the submit handler, so
the markup is submittable on its own. Someone who hits enter before the
javascript arrives still reaches the server; the page reloads with the result
instead of updating in place.

The two do not fight. The handler calls `preventDefault()` first, and React does
not run a form action for a submit that was cancelled — so the enhanced path
wins whenever there is one, and the native path is what is left when there is
not.

Nothing to turn on. It is why the fields are real `name` attributes rather than
controlled state: a browser can read them without help.

# Images

> Responsive images with no optimizer to run — unpic for a CDN, imagetools for files in the repo.

Source: https://docs.rsc-kit.dev/guides/images/ · Markdown: https://docs.rsc-kit.dev/guides/images/index.md

There is no image component and no image server. `next/image` is two things
glued together: a component that writes `srcset` and `sizes` for you, and an
optimizer that resizes on the fly — a process with sharp in it, a cache to
manage, and a CPU bill on every cold hit. The first half is worth having. The
second belongs to whatever already serves your images.

## Images on a CDN

If the file lives on Cloudinary, imgix, Cloudflare Images, Bunny, Vercel,
Netlify or any of the [other providers unpic knows](https://unpic.pics/img/react/),
it already has a resizing url. [unpic](https://unpic.pics) writes the `srcset`
against it:

```tsx title="src/app/page.tsx"
import { Image } from '@unpic/react';

<Image
  src="https://res.cloudinary.com/demo/image/upload/sample.jpg"
  layout="constrained"
  width={800}
  height={600}
  alt="A sample"
/>
```

It is a plain component, so it renders in a server component and the browser
receives an `<img>` — `srcset` from 640w up, `sizes`, `aspect-ratio`,
`loading="lazy"`, `decoding="async"` — and none of unpic's code. The route's
javascript does not change. The CDN is detected from the url; nothing to
configure.

TanStack Start and Astro point at the same library, for the same reason.

## Images in the repository

A file under `src/` is resized once, at build time, by
[vite-imagetools](https://github.com/JonasKruckenberg/imagetools). Query
parameters on the import say what you want:

```ts title="vite.config.ts"
import { imagetools } from 'vite-imagetools';

export default defineConfig({
  plugins: [imagetools(), rscKit(), ...],
});
```

```tsx title="src/app/page.tsx"
import hero from '../hero.png?w=400;800;1200&format=webp&as=srcset';
import heroSrc from '../hero.png?w=800&format=webp';

<img srcSet={hero} src={heroSrc} sizes="(min-width: 800px) 800px, 100vw" width={800} height={600} alt="…" />
```

The build emits `hero-<hash>.webp` at each width into `assets/`, hashed and
cacheable forever, and a page that is frozen carries the urls. It costs the
build what resizing costs, once per image per width, and nothing at request
time. It is opt-in for that reason: a hundred hero images at four widths is a
noticeable build, and most of them belong on a CDN.

Declare the query so TypeScript stops asking:

```ts title="src/images.d.ts"
declare module '*?*' {
  const value: string;
  export default value;
}
```

## What to pick

| the image is | use |
| --- | --- |
| user-uploaded, or on a CDN already | unpic |
| in the repo, a handful | imagetools |
| in the repo, hundreds | put them on a CDN and use unpic |
| an icon or a logo | `<img>`, or inline the svg |

Neither one runs at request time, and neither is on the page's javascript.

# Working with an AI agent

> An MCP server that answers from your actual build, and the AGENTS.md written into every project.

Source: https://docs.rsc-kit.dev/guides/mcp/ · Markdown: https://docs.rsc-kit.dev/guides/mcp/index.md

Two things ship for this, and they do different jobs.

`AGENTS.md` is written into your project by the scaffold. It is short on
purpose — it sits in an agent's context on every turn, so it states the rules
and nothing more.

The **MCP server** is for everything that does not fit in that budget: what your
build actually did, and the long-form answer to "how do I do X here".

## Connecting it

The scaffold already did. Every project gets a `.mcp.json` at its root:

```json title=".mcp.json"
{
  "mcpServers": {
"rsc-kit": { "command": "npx", "args": ["-y", "@rsc-kit/mcp"] }
  }
}
```

Claude Code reads that as project-scoped configuration and asks you to approve
it the first time it starts the server. Nothing is installed until then, and
nothing about your build or dev server changes — it is a file an agent reads.
Commit it; it is the same for everyone on the project.

For a project that predates the file, `create-rsc-kit init` writes it (and
leaves one that is already there alone), or add it by hand:

```sh
claude mcp add rsc-kit -- npx -y @rsc-kit/mcp
```

Any other MCP client takes the same entry — a stdio server, command `npx`,
arguments `-y @rsc-kit/mcp` — in its own file: `.cursor/mcp.json` under
`mcpServers`, `.vscode/mcp.json` under `servers`.

## What it answers about your app

Every build writes `build-report.json` — the same rows it printed, plus every
server action and whether a client built it. These read
it, so nothing runs a build or imports your code:

| tool | answers |
| --- | --- |
| `list_routes` | every route, what happened to it, what it ships |
| `explain_route` | why one url is stored or rendered per request |
| `what_is_dynamic` | the routes that are not stored, with reasons |
| `heaviest_routes` | what costs the browser most |

The reason a page is dynamic is **recorded, not guessed**:

```
/locale — a stored shell, with the rest rendered per request (from the last build, 5 minutes ago)
Rendered by app/locale/page.
Ships 85 kB of javascript, gzipped.

Why it is not stored whole: dynamic — called cookies(), headers()
```

That matters more than it sounds. Asked to "make this page faster", an agent
without this guesses at a cause and edits something. With it, the call that did
it is on the screen.

## What it answers about the framework

| tool | answers |
| --- | --- |
| `list_topics` | every topic it can explain |
| `how_to` | the short answer: forms, prefetch, validation, the action client, data with TanStack Query or SWR, Suspense, offline, pwa, no-javascript, api routes, authorization, why a page is dynamic |
| `list_guides` | every guide on this site, one line each |
| `read_guide` | the full text of one, exactly as published here — bundled with the server, so it matches the version installed |
| `search_guides` | every line in the guides mentioning a word, with the guide it is in |

`how_to` is the opinionated summary an agent should read first; `read_guide`
is for when the summary is not enough. Both come from the same source, and the
guides are copied in at build time, so what an agent reads is what this site
says for the version it has.

These exist because the patterns here differ from Next and plain React **in
ways that compile either way** — a check written in the component instead of the
action, a hand-parsed query string, `"use server"` at the top of a page. An
agent that has not been told writes those confidently.

## Two things worth knowing

**Every answer says how old it is.** It reports the last build, and your files
may have changed since — so `(from the last build, 5 minutes ago)` is on every
response. With no build at all it says to run one, rather than reporting that
there are no routes.

**It is read-only.** Nothing here edits, builds or deploys. Your agent already
has a shell for those, and a server that can change a project is one that can
change it while answering a question about it.

## The docs are markdown too

Every page on this site is also a markdown file at the same url with
`index.md` added — `/guides/forms/index.md` — and
[`/llms.txt`](/llms.txt) is an index of all of them, with
[`/llms-full.txt`](/llms-full.txt) as one document. An agent without the MCP
server, or one asked about a version other than the one installed, reads
those. `read_guide` is the same text, offline, at the installed version.

## Without an agent

`build-report.json` is an ordinary file. A CI step can assert on it — that
nothing stopped being prerendered, that no route crossed a size budget — which
is the check most likely to catch a regression nobody would otherwise see.

# Page metadata

> Titles, descriptions and Open Graph tags, exported from the page.

Source: https://docs.rsc-kit.dev/guides/metadata/ · Markdown: https://docs.rsc-kit.dev/guides/metadata/index.md

Titles and meta tags are exported by the page that needs them. There is no
document template to edit and nothing to register — React hoists the resulting
elements into `<head>`, so they stream with the page rather than waiting for
it.

## Static metadata

```tsx title="src/app/about/page.tsx"
export const metadata: Metadata = {
  title: 'About us',
  description: 'Learn more about our team.',
  keywords: ['about', 'team', 'company'],
  openGraph: {
title: 'About us',
description: 'Learn more about our team.',
  },
};

export default function AboutPage() {
  return <h1>About us</h1>;
}
```

`Metadata` is imported from the package:

```tsx
import type { Metadata } from '@rsc-kit/core/metadata';
```

It used to be ambient, written into your project by the build. An import
resolves as soon as dependencies are installed, where a generated file does not
exist until something has been built once — so a freshly cloned project no
longer reports an error on every page it has not built yet.

:::tip[Custom meta tags go under `other`]
```tsx
export const metadata: Metadata = {
  title: 'Pricing',
  other: { 'fb:app_id': '1234', 'theme-color': '#111' },
};
```

The named keys are a closed set on purpose. When any key was legal, a typo like
`titel` was accepted in silence — and your editor offered no completions at
all.
:::

## Metadata from data

When the values depend on what the page loaded, export `generateMetadata`. It
receives the route params:

```tsx title="src/app/posts/[slug]/page.tsx"
import { findPost } from '../../../data';

export const generateMetadata: GenerateMetadata<{ slug: string }> = async ({ params }) => {
  const { slug } = await params;
  const post = await findPost(slug);

  return {
title: post.title,
description: post.excerpt,
openGraph: { title: post.title, description: post.excerpt, images: post.cover },
  };
};

export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const post = await findPost(slug);

  return <h1>{post.title}</h1>;
}
```

It receives the same `params` and `searchParams` a page does, so there is one
shape to learn rather than two. Unlike a page's, these always resolve — a
`<title>` has no fallback, so there is nothing to suspend into.

Metadata always resolves against the **full** layout chain, even when the
render is partial. A navigation that replaces one segment still produces the
same `<title>` a full load would, because the template on the outer layout is
consulted either way.

## Title templates

A layout can define the shape every title beneath it takes. `%s` stands in for
the page's own title:

```tsx title="src/app/layout.tsx"
export const metadata: Metadata = {
  title: {
template: '%s | Acme',
default: 'Acme',
  },
  description: 'The Acme dashboard.',
};
```

```tsx title="src/app/settings/page.tsx"
export const metadata: Metadata = { title: 'Settings' };

// <title>Settings | Acme</title>
```

The nearest layout with a template wins, so a nested layout can override the
one above it. A page that exports no title gets the `default`.

## Supported keys

| Key | Becomes |
| --- | --- |
| `title` | `<title>` — a string on a page, a template on a layout |
| `description` | `<meta name="description">` |
| `keywords` | `<meta name="keywords">`, joined with commas if you pass an array |
| `author` | `<meta name="author">` |
| `robots` | `<meta name="robots">` |
| `metadataBase` | nothing itself — it is what makes every relative url below absolute |
| `openGraph` | `<meta property="og:…">`, one per field; each image brings its size and alt |
| `twitter` | `<meta name="twitter:…">` |
| `icons` | `<link rel="icon">`, `apple-touch-icon` and so on |
| `other` | `<meta name="…">`, or `property=` for an `og:`/`fb:`/`article:` key |
| anything else | `<meta name="…">` |

`keywords` takes either form — `'react, rsc'` and `['react', 'rsc']` produce
the same tag.

The flat spellings — `'og:title'`, `'twitter:card'` — still work and render
correctly, but the structured objects are the ones to write: they are typed,
they take an image object with a width and height, and they are what a Next
app already has.

## The share card

```tsx title="src/app/layout.tsx"
export const metadata: Metadata = {
  metadataBase: new URL('https://remorva.com'),
  openGraph: {
siteName: 'Remorva',
type: 'website',
  },
  twitter: {
card: 'summary_large_image',
site: '@remorva',
  },
};
```

```tsx title="src/app/posts/[slug]/page.tsx"
export async function generateMetadata({ params }): Promise<Metadata> {
  const post = await findPost((await params).slug);

  return {
title: post.title,
openGraph: {
  title: post.title,
  description: post.excerpt,
  url: `/posts/${post.slug}`,
  images: [{ url: post.cover, width: 1200, height: 630, alt: post.title }],
},
  };
}
```

Layouts merge outward-in, so `metadataBase`, `siteName` and the card type are
set once and every page gets them.

:::caution[`metadataBase` is not optional in production]
A share-card scraper needs an **absolute** image url. Facebook, Slack and
LinkedIn all refuse a relative one, silently — the link unfurls with no image
and nothing says why.

Set `metadataBase` on the root layout and every relative `url`, image and icon
below it is made absolute. Without it, an `opengraph-image.png` in `app/` goes
out as `/_app/opengraph-image.png`, which works in a browser and nowhere else.

It is the same name as Next's, so a port carries it across unchanged.
:::

`og:` tags render with `property=` and `twitter:` with `name=`, because that is
what each scraper reads. It is worth stating because it is easy to get
backwards, and a tag with the wrong attribute is not an error — it is a card
that never shows.

## Icons

A string, a list, or a categorised object:

```tsx
// One favicon
export const metadata: Metadata = { icons: '/favicon.ico' };

// Several, with attributes
export const metadata: Metadata = {
  icons: [
{ url: '/favicon.ico', sizes: '32x32' },
{ url: '/icon-192.png', sizes: '192x192', type: 'image/png' },
  ],
};

// By role
export const metadata: Metadata = {
  icons: {
icon: '/favicon.ico',
apple: '/apple-touch-icon.png',
other: { rel: 'mask-icon', url: '/safari-pinned-tab.svg', color: '#5bbad5' },
  },
};
```

Each descriptor takes `url`, `type`, `sizes`, `color`, `rel`, `media` and
`fetchPriority`.

## How it reaches the document

```text
Build     the plugin finds the metadata exports and generates a resolver
Render    the resolver runs alongside the page, against the full layout chain
Load      React hoists <title> and <meta> into <head> as they are emitted
Navigate  the resolved metadata rides on the X-RSC-Meta header, and the
      client updates document.title and the tags in place
```

The last line is why a title is correct after an SPA navigation without the
page having been re-rendered from the root.

## Icons and share images

Put them in `src/app/` and the build finds them. There is nothing to register
and no layout to edit:

| file | what it becomes |
| --- | --- |
| `favicon.ico` | served at `/favicon.ico` |
| `icon.png`, `icon-192.png`, `icon-512.png` | `<link rel="icon">`, and the [manifest](/guides/offline/)'s icons |
| `apple-icon.png` | `<link rel="apple-touch-icon">` |
| `opengraph-image.png` | `<meta property="og:image">` |
| `twitter-image.png` | `<meta name="twitter:image">`, with the large-card type |

The names are Next's. There is nothing to gain from inventing different ones —
an app moving between the two should not have to rename its favicon.

**Sizes are read from the filename**, so `icon-192.png` needs no entry anywhere
saying it is 192 pixels. Which is why a manifest usually lists no icons at all:

```ts title="src/app/manifest.ts"
export default {
  name: 'Orders',
  themeColor: '#0b0b0c',
  // icons omitted — the build uses the icon-*.png beside this file
} satisfies WebManifest
```

Listing them as well would be the same set written twice, and the copy that
goes stale is the one nobody looks at.

### Why `app/` and not `public/`

`public/` means "serve this file unchanged". These are *read* as well as
served: an icon's filename decides what goes in the manifest, and its presence
decides what goes in the head. A file whose name the build interprets belongs
with the other files whose names the build interprets.

They are copied into the build output under `/_app/`, so they never collide
with something you put in `public/` yourself. The favicon is the exception —
it is served at `/favicon.ico`, because browsers ask for that url whatever the
markup says.

:::note[Set `metadataBase`]
The image is emitted as `/_app/opengraph-image.png`, which a scraper will not
fetch. With `metadataBase` on the root layout it goes out absolute — see [the
share card](#the-share-card) above.
:::

### Not `opengraph-image.tsx`

Next also accepts a *component* by that name and renders it to a PNG at build
time. This package does not, on purpose. Rendering an image means bundling a
layout engine and a rasteriser — a couple of megabytes of dependencies, and
seconds added to every build for every image — for a picture that changes
when the design does, which is to say rarely.

Make the image once with whatever you like, and commit the file. If a page
needs a *different* image per record — a card for each post — that is an
[api route](/guides/api-routes/) that returns one, cached, and the
`openGraph.images` url points at it. Neither touches the build.

# Navigation

> What happens when someone clicks a link, and why state survives it.

Source: https://docs.rsc-kit.dev/guides/navigation/ · Markdown: https://docs.rsc-kit.dev/guides/navigation/index.md

`Link` does not reload the page. It asks the server for the part of the tree
that actually changed, and swaps it in.

```tsx
import Link from '@rsc-kit/core/Link'

<Link href="/about">About</Link>
```

## What a navigation actually sends

Going from `/posts/one` to `/posts/two`, the root layout and the posts layout
are already mounted and identical. The client says which layouts it holds, the
server compares that with the new route's chain, and answers with the deepest
piece that differs — the page alone.

You get this for free. There is nothing to configure and no `loading` prop to
thread.

Two things follow from it, and they are the reason it works this way:

**State above the swap survives.** A sidebar's scroll position, an open menu, a
half-typed form in a layout — none of it is touched, because none of it was
re-rendered.

**A page you return to is still there.** Recently visited pages are kept mounted
and hidden rather than thrown away, so going back restores a half-filled form
exactly as you left it. Only a handful are kept, ordered by last visit.

## Programmatic navigation

```tsx
'use client'

import { visit, prefetch } from '@rsc-kit/core/router'

<button onClick={() => visit('/checkout')}>Checkout</button>
```

Links prefetch on hover already. `prefetch` is for when you know where someone
is going before they hover:

```tsx
useEffect(() => { prefetch('/step-2') }, [])
```

## Showing progress

```tsx
'use client'

import { useLinkStatus } from '@rsc-kit/core/useLinkStatus'

function Spinner() {
  const { pending } = useLinkStatus()

  return pending ? <span>Loading…</span> : null
}
```

A `loading.tsx` beside a page is shown while that page's data resolves:

```tsx title="src/app/posts/loading.tsx"
export default function Loading() {
  return <p>Loading posts…</p>
}
```

## Refreshing the current page

```tsx
'use client'

import { refresh } from '@rsc-kit/core/router'

<button onClick={() => refresh()}>Reload</button>
```

Scroll positions are restored afterwards — the window's and any element with
its own overflow, such as a sidebar.

# A page with no JavaScript

> The default is none. A client component is how a page asks for it.

Source: https://docs.rsc-kit.dev/guides/no-javascript/ · Markdown: https://docs.rsc-kit.dev/guides/no-javascript/index.md

There is no JavaScript on a page until something on it needs some. A
marketing page, a changelog, an article, a policy: the build stores them as
HTML and stops. No bootstrap script, so no React, no Flight client, no router.

```
  ○  /about    no js
 no client components, so ships no javascript; stylesheet inlined
```

**`"use client"` is the opt-in.** A route that freezes whole, renders none of
your client components, and has no server action in its tree ships nothing.
Put a client component in it — a counter, a `<Link>`, an update prompt — and
that page has the runtime, because there is now something for the runtime to
do. That is the whole rule, and there is no switch beside it in either
direction, on purpose:

- Nothing can *need* the runtime without a client component or an action in
  its tree, so there is nothing an "on" switch could say that the tree does
  not already say.
- A page that must *stay* this way is an assertion, not a setting: the route's
  `clientJs` in `build-report.json` is `null` when it shipped none, and a CI
  step can hold it there.

The check reads the rendered tree, not the source, so a client component
reached through a shared layout counts. Most pages under a layout with a
`<Link>` in its header keep the runtime; a route group with its own plain
layout drops it. That is the honest shape of it: the pages that can be
nothing are nothing, and the page with a nav is a page with a nav.

## What a page without the runtime still does

**Its stylesheet is inlined** into the document when it is small on the wire
(at most 10 kB gzipped), so the first paint waits on no request but the
document itself. The build says so on the route's line. Fonts are the one
thing left to you, because only you know which face the first paint needs —
the [fonts guide](/guides/fonts) shows the two-line preload.

The default is not always the right call. A site of many small pages — a
blog, documentation — may prefer one stylesheet the browser caches once over
the same 4 kB repeated in every document, and a sheet just over the cap may
be worth inlining anyway. It is one setting on the plugin:

```ts title="vite.config.ts"
rscKit({ inlineStylesheets: 'auto' })   // the default: when at most 10 kB gzipped
rscKit({ inlineStylesheets: false })    // never — keep the link, cache one file
rscKit({ inlineStylesheets: true })     // always, whatever the size
rscKit({ inlineStylesheets: 24_000 })   // your own cap, in gzipped bytes
```

**It still registers the [service worker](/guides/offline)** when the app has
one: the runtime's one-line registration is inlined in its place, so a visitor
who lands here first gets the worker the second visit is for. What such a
page cannot show is the update prompt — that is a client component, and a
page that uses it has the runtime.

**Navigation is unchanged in both directions.** A page with no client
component has no `<Link>`, so its anchors were already full loads. A `<Link>`
elsewhere that points *at* it still fetches its flight payload and swaps the
segment, because that payload is written from the render with the runtime.

## Only a page stored whole

With no client runtime there is nothing to fill a Suspense hole after the
shell arrives, so a partial prerender always keeps it, and so does a page
rendered per request. The line is what the runtime would *do*: hydrate a
client component, submit a `<form action={serverFn}>`, fill a hole. A page
with none of those is HTML, and is stored as HTML.

# Offline

> Knowing when the server cannot be reached, and carrying on without it.

Source: https://docs.rsc-kit.dev/guides/offline/ · Markdown: https://docs.rsc-kit.dev/guides/offline/index.md

```tsx
'use client'

import { useOffline } from '@rsc-kit/core/useOffline'

export function ConnectionBanner() {
  const offline = useOffline()

  if (!offline) return null

  return <p role="status">You are offline. Changes will not be saved.</p>
}
```

## What "online" means here

Whether the **router could reach the server**, as of its last attempt — not
`navigator.onLine`.

That distinction matters. `navigator.onLine` only tells you the network
interface is up — a laptop on café wifi that needs a login is "online" by that
measure and can reach nothing.

This reports what the router actually observed on its own requests, which is
what a person means by offline.

It follows that the value only changes when something is attempted. A tab
sitting idle with a dead connection reports online until the next navigation,
prefetch or action tries and fails.

## On the server

`useOffline()` returns `false` during a server render, and deliberately: the
server can reach itself. Returning anything else would render an offline state
into the HTML and then mismatch when the browser hydrated and disagreed.

## `useOnline`

The same reading, the other way round, for when that is what the markup wants:

```tsx
'use client';

import { useOnline } from '@rsc-kit/core/useOnline';

export function Status() {
  return <span>{useOnline() ? 'connected' : 'reconnecting…'}</span>;
}
```

It returns `true` on the server, for the same reason `useOffline()` returns
`false` there. Both read the one store, so they cannot disagree.

## Working with no network at all

The hooks above report. A service worker is what lets the app keep working,
and it is off by default:

```ts title="vite.config.ts"
rscKit({ offline: true })
```

The build writes `sw.js` beside the assets and the generated entry registers
it. With it on, a page you have visited survives a full reload with no network
at all — not just a navigation, a reload — and comes back interactive.

Everything else lives in one page's memory — the pages a boundary keeps
mounted, the prefetch cache. Reload with no network and the browser shows its
own error page: no script runs, so nothing held in JavaScript is reachable.

A service worker is the only thing that survives that.

### What is cached, and when

| | |
| --- | --- |
| hashed assets | at install, and answered from the cache forever after — the name changes when the bytes do |
| a page you loaded | its document, and the payload it boots from |
| a page you reached by link | its payload, and its document fetched once to go with it |
| a page you never visited | nothing |

The last two rows are the same mechanism from either end. A hard load fetches a
document and never the payload; a link fetches a payload and never the document.
Either alone is half a page.

So whichever arrives first fetches the other, **once per url**. A page costs one
extra request the first time you reach it, and none after.

A url you have never opened cannot be served, and is not faked. An earlier
version answered with the cached root, which put the home page's markup under
the address someone asked for and did not hydrate — a wrong page pretending to
be the right one. It fails now, which is true.

### What is deliberately not cached

Anything the server sent with `Cache-Control: no-store`, whatever else it is.

The Cache API files responses by url and knows nothing about who asked. So a
guarded page, or a [query](/guides/queries/) that read the session, would be
handed to whoever opens the app next on that machine — signed in as someone
else. `no-store` is the server saying so, and the worker obeys it.

This is why a query does **not** work offline by default. Queries answer
`private, no-store` precisely because they may read the session, and widening
that is a decision about who may see the answer:

```ts
// Cacheable, and offline, because the answer is the same for everyone.
export const getPricing = query(async () => tiers(), { cache: "private", maxAge: 300 })
```

For a personal read you want across reloads, do not widen it — persist your
cache library instead. TanStack's `persistQueryClient` writes to storage that
belongs to that browser, which gets you the same result without putting one
visitor's data somewhere the next one can be served it.

### Updating

The cache name is a hash of what it holds. A build that changed nothing keeps
the same name and leaves a visitor's cache alone; a build that changed anything
gets a new one, and the new worker sweeps the old caches away.

There is no version to set, and no way to strand someone on a stale worker.

A new worker takes over as soon as it installs rather than waiting for every
tab to close. That is safe here because assets are addressed by content: a page
already open goes on asking for the names it was built with.

> **The first visit still needs a reload**
>
> A worker does not control the page that registered it. So the first visit
> caches what it needs and the *second* is the one that survives being offline.
> That is how service workers work everywhere, not something particular here.
>
> Development is left alone entirely — a worker answering from a cache in front
> of the dev server turns every edit into a question about which copy you are
> looking at.

> **It can hide a server that is down**
>
> Serving from a cache asks nothing of the network, so an app can look healthy
> while its backend is not. That is the same edge the reveal window has, and it
> is what `useOffline()` above is for: with this on, saying so in the interface
> stops being a nicety.

## When nothing can answer

A reload with no network, on a page the worker has never cached, fails. It does
not fall back to the cached home page — that was tried, and it was worse than
failing: the document *is* the page here, so the visitor got the home page's
markup under the address they asked for, and it did not hydrate.

Add a route at `/offline` and that page is served instead:

```tsx title="src/app/offline/page.tsx"
export default function Offline() {
  return (
<main>
  <h1>You are offline</h1>
  <p>Try again once you are back.</p>
</main>
  )
}
```

Nothing in the file makes it special. It is an ordinary route, and what makes it
the fallback is that the build stored it and the worker precached it. It is also
the one page that can honestly stand in for another, because it is about being
offline rather than about the url it appears under.

**It has to be static.** A fallback that renders per request cannot be served
when there is no request to be made, so the build checks and says when it will
not work:

```text
[rsc-kit] offline: /offline cannot be the fallback, because it called cookies(),
      headers(). A fallback has to be servable with no network at all.
```

It is served for navigations only — a payload request answered with a document
would be handed to the Flight decoder, which throws.

## When a new version is live

The worker takes over as soon as it installs rather than waiting for every tab
to close, and taking over sweeps the previous build's cache. A page that has
been open across a deploy is therefore running javascript whose remaining chunks
are gone. It works until it navigates somewhere that needs one.

Only the worker knows this happened, so it says so:

```tsx
'use client'
import { useAppUpdate } from '@rsc-kit/core/useAppUpdate'

export function UpdateBanner() {
  const { updated, reload } = useAppUpdate()

  if (!updated) return null

  return <button onClick={reload}>A new version is ready — reload</button>
}
```

Reported rather than acted on. Reloading out from under someone mid-form is
worse than the staleness it fixes, so this package will not do it for you.

## Going further

Installing, push notifications and background sync are in
[Progressive web apps](/guides/pwa/).

# Partial prerendering

> Storing what every visitor sees the same, and rendering the rest per request.

Source: https://docs.rsc-kit.dev/guides/ppr/ · Markdown: https://docs.rsc-kit.dev/guides/ppr/index.md

A page usually has two halves: markup that is the same for everybody, and data
that is not. The build stores the first and renders the second per request, so
the browser paints immediately and fills in as the data arrives.

There is nothing to switch on, and no mode to pick. Every route goes through
the same probe, and this is one of the things it can find.

## How the build decides

```text
Build time
  → the page is rendered with a budget
  → anything still waiting when the budget expires is postponed
  → React has already flushed what did not need the request: layouts, static
markup, and the Suspense fallbacks standing in for the rest
  → that markup is stored as the route's shell, and beside it, where it stopped
Request time
  → the shell is served straight from disk — fast, no render
  → the render is picked up from where it stopped, against data that exists now
  → only the unfinished boundaries are written, onto the same response
  → a script React emits beside each one moves it into place as the HTML parses
```

**Postponed, not merely abandoned.** The difference matters. Aborting a render
gives you the bytes that flushed and nothing else — React has no record of
where it got to, so the holes can only be filled later by the browser.
Postponing keeps that record, which is what lets the boundaries be finished
at the origin and arrive with the document.

So the content is in the first response. It appears without waiting for the app
bundle or for hydration — on a slow connection, the difference between a spinner
and a page — and it is in the HTML a crawler reads.

This is not the same as working with scripting off: with JavaScript disabled the
fallbacks stay.

If anything goes wrong — the engine cannot resume, or the render fails — the
shell is served on its own and the client fills the boundaries when it
hydrates, exactly as it did before any of this existed. A slower hole, never a
wrong page.

The shell is stored per route **pattern**, not per url. `/posts/[slug]` has one
shell serving every slug, because everything that varies by slug is behind a
boundary the request fills.

## What makes a page dynamic

Anything the build cannot know:

- **`await params`** — the url, for a route that has not listed its urls
- **`await searchParams`** — the query string
- **`await headers()` / `await cookies()`** — the request
- **a host call**, on a host that has one
- **slow work of your own** that outlasts the budget

All of them behave the same way: the read suspends, the nearest fallback above
it goes into the shell, and the real value arrives per request.

## Where to put the boundaries

Only content inside a `<Suspense>` boundary can stream. Content above every
boundary has to finish before anything paints — which is the difference between
a route the build can store and one it refuses.

```tsx title="src/app/posts/[slug]/page.tsx"
import { Suspense } from 'react';
import { findPost } from '../../../data';

async function Body({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const post = await findPost(slug);

  return <article><h1>{post.title}</h1><p>{post.body}</p></article>;
}

export default function PostPage({ params }: { params: Promise<{ slug: string }> }) {
  return (
<Suspense fallback={<p>Loading…</p>}>
  <Body params={params} />
</Suspense>
  );
}
```

`Body` is still waiting when the budget expires, so the shell holds the
fallback. At request time the slug resolves and React replaces it.

## loading.tsx instead

Rather than wrapping every page by hand, put a `loading.tsx` beside it. The
build wraps the page in `<Suspense fallback={<Loading />}>` for you, and the
page can await at its top level:

```tsx title="src/app/posts/[slug]/loading.tsx"
export default function Loading() {
  return <div className="h-6 w-50 animate-pulse rounded-lg bg-zinc-800" />;
}
```

```tsx title="src/app/posts/[slug]/page.tsx"
export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;

  return <h1>{(await findPost(slug)).title}</h1>;
}
```

### It is hierarchical

Like `layout.tsx`, the nearest `loading.tsx` to the page wins, and several in
one chain stack as nested boundaries:

```text
src/app/
  layout.tsx
  loading.tsx           fallback for everything without a closer one
  docs/
loading.tsx         fallback for /docs/*
[slug]/
  page.tsx          uses docs/loading.tsx
  dashboard/
page.tsx            uses app/loading.tsx
```

### A root loading.tsx catches everything, including mistakes

It wraps every page, so a page that waits above any boundary of its own is
still caught and still stored — and the build has nothing to refuse. It looks
exactly like a page whose boundary is in the right place.

So the build says so:

```text
◐  /locale
   ⚠  nothing painted without the root loading.tsx — the fallback the whole app
  shares is standing in for this page. Put a boundary where the waiting is.
```

Worked out by rendering the route a second time without the root fallback: a
page with a boundary of its own paints immediately, and a page leaning on the
root paints nothing. Only routes with no closer `loading.tsx` are asked, so it
costs nothing for the rest.

It is a warning rather than an error because the page does work. What it costs
is shared: every page in the app shows the same fallback while this one waits,
and the fallback cannot say anything about what is loading. Moving the boundary
to where the waiting is fixes both.

## When nothing can be frozen

If nothing was flushed before the page blocked, there is no shell to store —
and the build says so rather than filing the route under a category:

```text
Some routes could not be prerendered:

  /dashboard — reaches for the host before anything can paint, so there is no shell to store

Each one reads request data — params, headers, cookies, or the host —
above every Suspense boundary, so nothing can paint without it.

Put the part that waits inside <Suspense>, or add a loading.tsx beside
the page, so there is something to store while the rest arrives.
```

Fixed the same way every time, and there is no way to declare it away. A route
the build cannot store has its boundary in the wrong place; moving the boundary
is the fix.

## If the build hangs

`RSC_PPR_TIMEOUT_MS` sets it; the default is 2 seconds. Raising it lets slow
pages be stored whole; lowering it pushes more of them to shells.

A page whose data resolves inside the budget is stored **whole**, even one that
called `fetch()`. If a page must reflect the world at request time, what makes
it so is reading the request — not a flag.

# Progressive web apps

> Making the app installable, and adding push notifications and background sync.

Source: https://docs.rsc-kit.dev/guides/pwa/ · Markdown: https://docs.rsc-kit.dev/guides/pwa/index.md

An installable app is a manifest plus a service worker. The
[offline guide](/guides/offline/) covers the worker; this covers everything
that makes the app feel like one the operating system knows about.

## The manifest

A service worker makes an app survive a dead network. It does not make a
browser offer to put it on a home screen — that needs a web app manifest, which
is a file beside your routes:

```ts title="src/app/manifest.ts"
import type { WebManifest } from '@rsc-kit/core/manifest-file'

export default {
  name: 'Orders',
  shortName: 'Orders',
  themeColor: '#0b0b0c',
  backgroundColor: '#ffffff',
  icons: ['icon-192.png', 'icon-512.png'],
} satisfies WebManifest
```

A file rather than a `vite.config.ts` key, and rather than `metadata` in a
layout. It is not build configuration — it is one more thing the app declares
about itself, so it lives where the app is, next to `layout.tsx` and
`not-found.tsx`.

Not `metadata` either, and for a reason worth stating: `metadata` is resolved
per route and can be computed per request. A manifest is one file for the whole
app and has to exist before anything renders. Putting it in an inheritable,
dynamic mechanism would invite a question — *can I override it for this route?*
— whose only honest answer is no.

The build reads it, writes `manifest.webmanifest`, and links it from every
page. **There is no layout to edit** — React hoists the `<link>` and the
`theme-color` meta into `<head>` from wherever they are rendered, so this works
on an app that already has its own root layout.

It is read at build time, before there is a module graph to evaluate it in, so
it must be an object literal — not computed, not imported from elsewhere. A
file that is not gets a build error rather than an app that is quietly not
installable.

Icons are paths in your `public/` directory, and **their sizes are read from
the filename** — `icon-192.png` and `icon-192x192.png` both mean 192. Declaring
the size in the config as well would be the same number written twice, and the
one that drifts is the one nobody looks at.

Every icon is marked `any maskable`, because without it Android crops a square
icon into a circle and takes the corners off whatever was in them.

### The build tells you if it will not work

This is the failure worth guarding: a manifest with no icon is *valid*. It
parses, it links, it sets the theme colour, and no browser ever offers to
install it. Nothing is wrong and nothing works.

```text
[rsc-kit] manifest: no icons, so no browser will offer to install this. Add a 192px and a 512px png.
[rsc-kit] manifest: Orders is installable
```

A warning rather than a failed build — the manifest still does its other job —
but it is said out loud, because someone who wrote `manifest: {…}` meant
installable and would otherwise find out months later.

## Your own worker code

Push, notification clicks and background sync are events the generated worker
does not handle, and there is nowhere to put them in a file that says *do not
edit*. So it will import yours:

```js title="src/app/sw.js"
// Plain javascript. The browser evaluates this in a worker scope with no build
// step in front of it, so what you write is what runs.

self.addEventListener('push', (event) => {
  const payload = event.data ? event.data.json() : {}

  event.waitUntil(
self.registration.showNotification(payload.title ?? 'Update', {
  body: payload.body,
  data: { url: payload.url ?? '/' },
}),
  )
})

self.addEventListener('notificationclick', (event) => {
  event.notification.close()
  event.waitUntil(self.clients.openWindow(event.notification.data.url))
})
```

The build copies it beside the generated worker and imports it first, so your
listeners are registered before anything of ours can answer an event. It is
precached like everything else — a worker whose import fails does not start, and
then nothing is cached at all.

```text
[rsc-kit] offline: 32 files precached as rsc-kit-3d9785e4, falling back to /offline, with app/sw.js
```

There is no option for this. The file is there or it is not.

:::caution[`.js`, not `.ts`]
It is evaluated by the browser, not built. TypeScript would not run.
:::

## Push notifications

Four pieces, and only one of them is ours.

### 1. Keys

Push needs a VAPID key pair — the public half identifies your server to the
browser, the private half signs what you send.

```sh
npx web-push generate-vapid-keys
```

Keep the private key wherever you keep secrets. The public one reaches the
browser, so it can be a plain environment variable.

### 2. Ask, and subscribe

```tsx title="src/components/EnableNotifications.tsx"
'use client'

export function EnableNotifications() {
  async function enable() {
if (await Notification.requestPermission() !== 'granted') return

const registration = await navigator.serviceWorker.ready
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
})

await saveSubscription(subscription.toJSON())
  }

  return <button onClick={enable}>Enable notifications</button>
}
```

**Ask when they have a reason to say yes.** A permission prompt on first load is
how an app gets denied permanently — the browser remembers a refusal, and there
is no second chance.

### 3. Store the subscription

An ordinary [server action](/guides/server-actions/), so it is one function and
no endpoint:

```ts title="src/server/push.ts"
'use server'

import { client } from './client'

export const saveSubscription = client.input(subscriptionSchema).handler(
  async ({ input, ctx }) => db.pushSubscriptions.upsert(ctx.user.id, input),
)
```

Store it against a **user**, not a session. A subscription outlives the session
that created it, and that is the point of one.

### 4. Send

From wherever the event happens — a queue, a cron, a webhook:

```ts
import webpush from 'web-push'

webpush.setVapidDetails('mailto:you@example.com', PUBLIC_KEY, PRIVATE_KEY)

for (const subscription of await db.pushSubscriptions.forUser(userId)) {
  try {
await webpush.sendNotification(subscription, JSON.stringify({
  title: 'Your order shipped',
  url: '/orders/42',
}))
  } catch (error) {
// 404 and 410 mean the subscription is dead — the app was uninstalled, or
// the browser rotated it. Delete it rather than retrying forever.
if (error.statusCode === 404 || error.statusCode === 410) {
  await db.pushSubscriptions.remove(subscription.endpoint)
}
  }
}
```

That last branch is the one people skip, and it is why push senders accumulate
dead endpoints until they are mostly dead endpoints.

:::note[Not ours, deliberately]
This package ships no push helper. Everything above is the web API and
`web-push`, and the only part we could own — a place to put the listener — is
`app/sw.js`. A wrapper would be a thin layer over a stable standard, and one
more thing to keep current.
:::

## Background sync

For work that must happen even if the person closes the tab — a queued message,
an offline edit.

```js title="src/app/sw.js"
self.addEventListener('sync', (event) => {
  if (event.tag === 'outbox') event.waitUntil(flushOutbox())
})

async function flushOutbox() {
  const db = await openDB()

  for (const item of await db.getAll('outbox')) {
const response = await fetch('/api/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(item.body),
})

// Left in the queue on failure, so the browser retries the whole sync
// later. Removed only once the server has it.
if (response.ok) await db.delete('outbox', item.id)
  }
}
```

Register it from the page after queueing the work:

```ts
const registration = await navigator.serviceWorker.ready
await registration.sync.register('outbox')
```

:::danger[Make the endpoint idempotent]
The browser decides when a sync runs and may run it more than once — a request
that succeeded on the server but whose response never arrived gets retried. If
that posts a message twice, the person sent it twice.

Give each queued item an id the client generates, and have the endpoint ignore
one it has already seen. Nothing else about background sync is hard; this is,
and no framework can do it for you because only your data model knows what
"already seen" means.
:::

Support is narrower than the rest of this page — Chromium has it, Safari and
Firefox do not. Treat it as an optimisation over an ordinary retry, never as the
only path:

```ts
if ('sync' in registration) await registration.sync.register('outbox')
else await flushNow()
```

# Queries

> Reading from the server over GET, and letting TanStack Query or SWR own everything above it.

Source: https://docs.rsc-kit.dev/guides/queries/ · Markdown: https://docs.rsc-kit.dev/guides/queries/index.md

`query()` marks a server function as a read, so the call goes out as a GET
instead of a POST. Your logs and rate limiters can then tell it apart from a
mutation, and a cache can hold the answer.

```ts title="src/listings.ts"
"use server"

import { query } from "@rsc-kit/core/query"

export const getListings = query(async (kind: string) => {
  return db.listings.where({ kind })
})
```

That is the whole feature. There is no cache here, no batching and no
deduplication: [TanStack Query](https://tanstack.com/query) and
[SWR](https://swr.vercel.app) already do those and do them better. **This owns
the transport; they own everything above it.**

You still need `"use server"`, and it is not claiming your function mutates.
Despite the name it means *this may be called from the browser* — it is what
gives the function an id and the client a stub to call it through.

Two markers, two jobs. `"use server"` says the function crosses the boundary.
`query()` says it is a read.

:::caution[The call site picks the method]
`query()` permits the GET; it does not force it. Calling the function directly
from a client component is still a POST, because the browser cannot tell a query
id from an action id — only `fetchQuery` sends a GET.

```tsx
getListings(kind)                  // POST, even though it is a query
fetchQuery(getListings, [kind])    // GET
```

Development warns from the server when a query arrives at the action endpoint,
so a forgotten `fetchQuery` shows up rather than quietly costing you the method.
:::

## What it changes

Only the method. Same types, same arguments, same lack of an endpoint to write.

Three things follow from that:

- **Access logs and rate limiters** stop counting your reads as mutations. A
  limiter that allows 10 writes a minute should not be spending them on a list
  being refreshed.
- **A GET is the only shape a cache can keep.** A browser cache, a CDN or a
  service worker can hold one; a POST can never be held by any of them.
- **Repeating it is safe by contract**, which is what a prefetcher, a crawler
  or a retrying proxy assumes when it sees a GET.

TanStack Start makes the same choice from the other side: its `createServerFn()`
is a GET unless you ask for `{ method: 'POST' }`. We cannot default it that way
— React gives us one directive for everything, so a GET default would send
mutations as GET too.

### If you skip it

A plain server action still works as a cache library's fetcher, and nothing
breaks:

```tsx
useQuery({ queryKey: ["listings", kind], queryFn: () => getListings(kind) })
```

You lose the three things above and keep everything else. So this is a
reasonable place to start, and `query()` is the thing to reach for once a read
is worth being precise about — anything hot enough to show up in a rate limiter,
or public enough to be worth caching.

One caveat on the second: data that is the same for everyone usually wants
[prerendering](/guides/static-generation/) rather than a client read at all, and
a personal read answers `no-store` and is not cached either way. The caching win
is real, and narrower than it sounds.

## Reading it

**In a server component, call it.** It is ordinary server code — no HTTP, no
cache, no client involved:

```tsx
const listings = await getListings("stay")
```

**Better still, do not await it.** Pass the promise down and let a client
component resolve it, and the data streams with the page:

```tsx
export default function Page() {
  const listings = getListings("stay")

  return (
<Suspense fallback={<Skeleton />}>
  <List listings={listings} />   {/* "use client": use(listings) */}
</Suspense>
  )
}
```

React serialises the promise as a pending row in the payload, so the shell
paints at once and the rows arrive when the query answers — in the same
response, with no request from the browser. Nothing in this package is involved;
`use()` is React's. Reach for this first.

**When the browser decides what to read** — a filter, another page, a refresh —
hand `fetchQuery` to your cache library:

```tsx
import { fetchQuery } from "@rsc-kit/core/queryClient"

// TanStack Query
useQuery({
  queryKey: ["listings", kind],
  queryFn: () => fetchQuery(getListings, [kind]),
})

// SWR
useSWR(["listings", kind], () => fetchQuery(getListings, [kind]))
```

`fetchQuery` goes to the server every time. That is what a fetcher needs:
staleness, revalidation and deduplication belong to the library holding the
answer, not to the thing that fetches it.

:::caution[Keep the arrow]
TanStack calls a bare `queryFn` with its own context — `{ client, queryKey,
meta, signal }` — and a server function serialises whatever it is handed, so
passing one unwrapped would try to put an `AbortSignal` on the wire. The arrow
is where you choose what travels.
:::

### Paging, polling, and the rest

All of it belongs to the library, and all of it works:

```tsx
// Infinite. The cursor is just an argument.
useInfiniteQuery({
  queryKey: ["feed"],
  queryFn: ({ pageParam }) => fetchQuery(getFeed, [pageParam]),
  initialPageParam: null,
  getNextPageParam: (last) => last.nextCursor,
  initialData: { pages: [first], pageParams: [null] },
  staleTime: 60_000,
})

// Data that changes while you watch. No live connection needed.
useQuery({ queryKey: ["seats"], queryFn: () => fetchQuery(getSeats, []), refetchInterval: 2_000 })
```

Page one comes from a server component and costs no request; later pages are
ordinary reads. `/infinite`, `/pagination` and `/polling` in the example app are
these three patterns end to end.

:::caution[A seed is stale by default]
TanStack treats `initialData` as stale at its default `staleTime` of `0`, so
without an explicit `staleTime` it refetches page one on mount and the round
trip you seeded to avoid happens anyway. SWR's `fallbackData` has the same
shape of caveat, and `refetchInterval` pauses while the tab is hidden.
:::

### Where it will not work

`fetchQuery` only works in the browser. React refuses a server-function call
during the first render, so a component that also renders on the server must not
call it there.

You will not hit this through TanStack or SWR — they fetch in an effect, after
hydration.

## Sharing a check across reads

A query has no middleware above it, so each one checks for itself. If that means
writing the same check in every file, put it on the client you already use for
actions:

```ts title="src/server/client.ts"
'use server'

import { createActionClient } from '@rsc-kit/core/action'

export const client = createActionClient({ onError: report })
  .use(async ({ next }) => {
const user = await currentUser()

if (!user) throw new Error('Not signed in')

return next({ ctx: { user } })
  })
```

```ts title="src/server/posts.ts"
'use server'

import { client } from './client'

export const createPost = client.input(schema).handler(async ({ input, ctx }) => …)  // POST
export const getPosts   = client.input(filter).query(async ({ input, ctx }) => …)    // GET
```

One client, one set of middleware, one `onError`. `.handler()` makes an action;
`.query()` makes a query. Neither can be added without the check.

### They fail differently, on purpose

An action **returns** its failures, because React strips a thrown message in
production. A query **throws** — every cache library reports failure by
rejection, and one that answered with an error-shaped object would look like a
successful read of something odd.

So a refused read rejects with a real `Error`. A validation failure keeps its
fields:

```tsx
const { error } = useQuery({ queryKey: ['posts'], queryFn: () => fetchQuery(getPosts, [filter]) })

error.message   // 'Validation failed'
error.errors    // { title: ['too short'] }
```

## Securing a query

A query is a public GET endpoint. Treat it as one.

### Route middleware does not run

`middleware.ts` guards a **route**, and a query has no route — it is reachable
whoever is asking and whatever page they came from. A query behind a guarded
page is not guarded.

What you do get is the request: the visitor's cookies and session are bound for
the call, so a query can check for itself.

One query is fine written by hand:

```ts
export const getOrders = query(async () => {
  const user = await currentUser()

  if (!user) throw new Error("Not signed in")

  return db.orders.forUser(user.id)
})
```

Twenty is twenty chances to forget, and the one you forget is the one that
matters. Put the check on the client you already use for actions and build
every read from it:

```ts title="src/server/orders.ts"
'use server'

import { client } from './client'

export const getOrders = client.query(async ({ ctx }) => db.orders.forUser(ctx.user.id))
```

`ctx.user` is typed and non-null because the only way into the handler was
through the middleware that put it there — so a query **cannot be added without
the check**. Same client, same middleware, same `onError` as your actions;
`.handler()` makes a mutation and `.query()` makes a read. See
[sharing a check across reads](#sharing-a-check-across-reads) below.

Authorise on **identity, not arguments**. `getOrder(id)` that trusts the id is
the whole of an IDOR: the caller chooses the id.

### Only `query()` is reachable

The endpoint refuses anything that is not a query, which is what keeps every
action you have registered off a GET url. So export the wrapped value, not the
bare function beside it.

An unknown id and a real-but-unmarked one get the same 404. Telling them apart
would let someone probe for your action ids.

### A query must never write

It is a GET. A prefetcher, a crawler or a retry will repeat it.

### What the endpoint does for you

- **Requires `X-RSC-Query`.** A GET with no unusual header is a *simple*
  request, so any page anywhere could trigger one with
  `<img src="…/_rsc/query?…">` and it would carry the visitor's cookies — CORS
  stops them reading the answer, not the read running. That header is not
  CORS-safelisted, so a browser preflights it and nothing here answers a
  preflight. It is the same protection a POST carrying `X-RSC-Action` had.
- Refuses a cross-origin request when an `Origin` is present.
- Refuses an oversized url with `414` before decoding anything.
- Sends `Vary: Cookie`, so a cacheable answer is never shared between visitors.

None of that authorises anything. The query does that.

### Arguments are public

They travel in the url, so they reach access logs, browser history and referrer
headers. Never take a token or a password reset code as a query argument — that
is an action.

Arguments too large for a url, or containing a `File`, make the read fall back
to a POST rather than failing. It still works; it simply stops being cacheable,
and development warns when it happens.

## Caching

Answers default to `private, no-store`. A query may read the session, and a
cacheable answer to a personal read is how one visitor is served another's data.

```ts
export const getPricing = query(async () => tiers(), { cache: "public", maxAge: 300 })
```

### You probably do not need to change it

There are two caches and they solve different problems.

**Your cache library's**, in memory and per tab, decides whether to ask again.
It needs nothing from this option — `no-store` does not stop TanStack or SWR
holding an answer, because they are not an HTTP cache.

**The HTTP one**, which `cache` controls, decides whether an answer survives a
reload, works offline, or can be shared by a CDN.

Most apps want only the first. And note that data which is the same for everyone
usually wants [prerendering](/guides/static-generation/) rather than a client
read at all — which is a better answer than any cache. For a personal read you
want across reloads, persist your cache library rather than widening the read.

## During a build

A query is an ordinary function, so it follows the ordinary rule. One reading a
database the build machine can reach runs at build time and the page is frozen
with real data in it. Call `connection()` inside the query to opt out.

# React Compiler

> Enabling the compiler in the build.

Source: https://docs.rsc-kit.dev/guides/react-compiler/ · Markdown: https://docs.rsc-kit.dev/guides/react-compiler/index.md

The React Compiler memoises client components for you, so `useMemo`,
`useCallback` and `React.memo` mostly stop being things you write.

Nothing here special-cases it. The build runs your project's own Vite config,
so the compiler is enabled the way it is in any Vite app — by adding
`@vitejs/plugin-react` after `rscKit()` and turning it on there.

> **Order matters**
>
> `rscKit()` includes `@vitejs/plugin-rsc`, which has to see modules before
> any React layer transforms them. The React plugin goes **after** it.

## Two ways to run it

The compiler has a native implementation and a Babel one. Both produce the same
transform; they differ in what they cost to run and how settled they are.

### Native, through oxc

The faster path, and the least to install. `compiler: true` is
[experimental](https://react.dev/learn/react-compiler/installation) and needs
`oxc-transform-react` present — the plugin looks for it by name:

```sh
npm install --save-dev @vitejs/plugin-react oxc-transform-react
pnpm add -D @vitejs/plugin-react oxc-transform-react
yarn add -D @vitejs/plugin-react oxc-transform-react
bun add -d @vitejs/plugin-react oxc-transform-react
```

```ts title="vite.config.ts"
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { rscKit } from '@rsc-kit/core/vite';

export default defineConfig({
  plugins: [
rscKit({ sourceDir: 'src' }),
react({ compiler: true }),
  ],
});
```

Pass an object instead of `true` to configure it.

### Babel

The reference implementation. In `@vitejs/plugin-react` 6 the inline `babel`
option was removed, so the preset is applied through `@rolldown/plugin-babel`:

```sh
npm install --save-dev @vitejs/plugin-react @rolldown/plugin-babel babel-plugin-react-compiler
pnpm add -D @vitejs/plugin-react @rolldown/plugin-babel babel-plugin-react-compiler
yarn add -D @vitejs/plugin-react @rolldown/plugin-babel babel-plugin-react-compiler
bun add -d @vitejs/plugin-react @rolldown/plugin-babel babel-plugin-react-compiler
```

```ts title="vite.config.ts"
import { defineConfig } from 'vite';
import react, { reactCompilerPreset } from '@vitejs/plugin-react';
import babel from '@rolldown/plugin-babel';
import { rscKit } from '@rsc-kit/core/vite';

export default defineConfig({
  plugins: [
rscKit({ sourceDir: 'src' }),
react(),
babel({ presets: [reactCompilerPreset()] }),
  ],
});
```

On `@vitejs/plugin-react` 5 and earlier, the inline option still exists:

```ts
react({
  babel: { plugins: ['babel-plugin-react-compiler'] },
})
```

## Checks worth running first

The compiler only memoises components it can prove are safe to memoise, and it
skips the rest silently. These are how you find out which is which, and they
are worth running **before** you turn it on rather than after.

**Type checking.** The compiler assumes your code means what its types say. Run
`tsc --noEmit` and fix what it reports first — an untyped `any` threading
through a component is exactly the shape the compiler has to give up on.

```bash
tsc --noEmit
```

**The health check.** Reports how many components in your codebase the compiler
can handle, and why the others are refused:

```bash
npx react-compiler-healthcheck
```

**The lint rule.** `eslint-plugin-react-hooks` includes the compiler's own
diagnostics — the Rules of React violations that make a component
uncompilable — so they surface as you write rather than as silence in the
build:

```js title="eslint.config.js"
import reactHooks from 'eslint-plugin-react-hooks';

export default [reactHooks.configs.recommended];
```

**StrictMode.** The compiler's assumptions are the Rules of React, and
StrictMode is what surfaces breaking them at runtime — double-invoked renders
catch the impure ones.

> **It applies to client components**
>
> Server components render once and are thrown away, so there is nothing to
> memoise in them. The compiler earns its keep in the `"use client"` half of
> the app.

## Confirming it ran

The compiler leaves a cache array at the top of every component it compiled.
Build without minification and look for it:

```js
function Counter() {
  const $ = _c(10);                                    // ← compiled
  const [count, setCount] = useState(0);

  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
// …
  }
}
```

No `_c(...)` and no `memo_cache_sentinel` means that component was skipped —
which the health check will explain.

## Opting a component out

```tsx
"use client";

export default function LegacyWidget() {
  "use no memo";

  return <div>…</div>;
}
```

## Turning it off

Drop `compiler: true`, or remove the plugin. Neither the router nor the build
depends on it being there.

Further reading: [React Compiler installation](https://react.dev/learn/react-compiler/installation).

# Redirects

> Leaving a page from inside the render, and what that costs.

Source: https://docs.rsc-kit.dev/guides/redirects/ · Markdown: https://docs.rsc-kit.dev/guides/redirects/index.md

```tsx title="src/app/products/[slug]/page.tsx"
import { redirect } from '@rsc-kit/core/redirect';
import { findProduct } from '../../../data';

export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const product = await findProduct(slug);

  if (!product) redirect('/products');

  return <h1>{product.name}</h1>;
}
```

`redirect` never returns — it throws, which is what stops the component. The
default status is `307`, because it preserves the method: a redirect out of a
`POST` does not silently become a `GET` of the target.

A redirect during a navigation stays a navigation. The document does not reload,
the layouts you are inside stay mounted, and only the part below them changes.

The url that redirected replaces its history entry rather than adding one, so
Back does not land on it and redirect you again.

## Where you call it matters

This is the part worth understanding, because it is also the security-relevant
part. Headers flush early on purpose — that is what makes the first paint fast
— so a redirect decided late has no status line left to use. There are two
windows, and nothing you write chooses between them:

| Called | Answered with | What the browser saw first |
| --- | --- | --- |
| Above every `<Suspense>` boundary | A real `3xx`, or `X-RSC-Redirect` on a navigation | Nothing at all |
| Inside a boundary | The shell, then the redirect | Layouts, and the fallbacks standing in for what never arrived |

Neither buffers the response. Before anything is written the host is still
waiting on the shell, so a component that redirects instead of rendering is
caught there. After that, React already carries an error digest to the client
and the destination rides along in it.

> **Middleware belongs above the boundaries**
>
> A `loading.tsx` wraps the whole page in `<Suspense>`. That is usually what you
> want — it is how a page gets a frozen shell — but it also means an `await` at
> the top of that page is *inside* a boundary, and a redirect after it arrives
> in the second window.
>
> Nothing from inside the boundary was shown, so a not-found redirect is fine
> there. An authorization check is different: the layouts above it already
> rendered and already went out. If a page must reveal nothing at all, the
> check has to run somewhere that blocks the shell.

## Where to put an authorization check

In order of preference:

**In `middleware.ts`.** A file beside the layout, run before anything at or below it
renders, on every path. This is the one built for the job.

> **A layout is not a security boundary**
>
> It is tempting — a layout renders above the page's boundary, so on a full
> page load a redirect there happens before anything is sent. But a navigation
> tells the server which layouts the client already has, in `X-RSC-Segments`,
> and the server skips re-rendering those. A client that *claims* to hold your
> layout skips the check:
>
> ```bash
  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout' /guarded
  # 204, X-RSC-Redirect: /orders        ← the middleware ran

  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout,app/guarded/layout' /guarded
  # 200, and the page's content         ← it did not
```
>
> The header is not verified and cannot be. Put the check in a `middleware.ts`
> beside the layout instead — it runs before anything below it renders, on
> every path. See [Authorization](/guides/authorization).

**At the top of a page with no `loading.tsx`.** Runs on every render of that
page, so it is not skippable the way a layout is — but fragile in a different
way: adding a `loading.tsx` later silently moves the check into the second
window, and nothing warns.

> **Never catch it and continue**
>
> `redirect` communicates by throwing. A `try`/`catch` that swallows everything
> turns the redirect into a blank region — the component stops, and nothing
> takes its place. If you must wrap the call, rethrow what you do not
> recognise:
>
> ```ts
  import { isRedirectSignal } from '@rsc-kit/core/redirect';

  try {
await mightRedirect();
  } catch (error) {
if (isRedirectSignal(error)) throw error;
// …
  }
```

## From a server action

An action is not a render, so there is no shell to be on either side of. Throw
from the action and the client follows it:

```ts title="src/actions.ts"
'use server'

import { redirect } from '@rsc-kit/core/redirect';

export async function createPost(title: string) {
  const post = await savePost(title);

  redirect(`/posts/${post.slug}`);
}
```

## A route that only redirects

The redirect itself is stored, so it costs no render at all:

```text
○  /old-pricing   (redirects to /pricing)
```

The build writes the status and the location, and the host answers from that
file — a document gets the status code, a navigation gets `X-RSC-Redirect` and
does it as an SPA navigation. Nothing is rendered per request, and a static
export can carry it.

## Loops

A navigation follows at most **8** redirects before throwing. A page that
redirects to itself is a mistake someone will make, and without a ceiling it is
an unbounded run of full renders rather than an error you can see.

# Headers and cookies

> Setting response headers and cookies during a render.

Source: https://docs.rsc-kit.dev/guides/response-headers/ · Markdown: https://docs.rsc-kit.dev/guides/response-headers/index.md

## Reading

Anywhere in a server component or action:

```tsx
import { headers, cookies, searchParams } from '@rsc-kit/core/request'

export default async function Page() {
  const h = await headers()
  const jar = await cookies()

  return <p>Hello {jar.get('name')?.value ?? 'stranger'}</p>
}
```

## Writing

```tsx
import { responseHeaders, cookies } from '@rsc-kit/core/request'

export async function middleware() {
  responseHeaders().set('X-Frame-Options', 'DENY')

  const jar = await cookies()
  jar.set('last-seen', new Date().toISOString(), { httpOnly: true, path: '/' })
}
```

**Writing only works in middleware.** Middleware runs before the render, while
the response line has not been sent yet. A component runs *during* streaming,
when the headers are already on the wire — writing from one throws rather than
being silently dropped, so you find out immediately.

A redirect carries them too, which is what lets middleware remember where
someone was going before sending them to log in:

```tsx
export async function middleware() {
  const jar = await cookies()

  if (!jar.get('session')) {
jar.set('intended', '/dashboard', { path: '/' })
redirect('/login')
  }
}
```

## Security headers

Nothing sets them for you, because which ones an app wants is the app's
decision. The usual set is one middleware at the root, which every route
then inherits:

```tsx title="src/app/middleware.ts"
import { responseHeaders } from '@rsc-kit/core/request'

export default function middleware() {
  const h = responseHeaders()

  h.set('X-Content-Type-Options', 'nosniff')
  h.set('Referrer-Policy', 'strict-origin-when-cross-origin')
  h.set('X-Frame-Options', 'DENY')
}
```

A `Content-Security-Policy` is the one that needs more than a header: a
page stored at build time cannot carry a per-request nonce. That is
[on the list](https://github.com/rsc-kit/rsc-kit/issues), and until then a
policy that allows your own origin's scripts is the honest one.

## Cookie options

```ts
jar.set('name', 'value', {
  httpOnly: true,
  secure: true,
  sameSite: 'lax',      // 'strict' | 'lax' | 'none'
  path: '/',
  maxAge: 60 * 60 * 24,
  expires: new Date('2027-01-01'),
})
```

Names are validated as cookie tokens and `sameSite` / `expires` are checked, so
a typo is an error rather than a header the browser quietly ignores.

# Route interception

> Opening a route as a modal over the page you were on.

Source: https://docs.rsc-kit.dev/guides/route-interception/ · Markdown: https://docs.rsc-kit.dev/guides/route-interception/index.md

Route interception lets you load a route from a different part of your app within the current layout. When a user clicks a link, the intercepted component renders in a parallel slot (like a modal) while the current page stays visible behind it. On hard navigation (refresh or direct URL), the normal page renders instead.

This follows the same convention as Next.js — using `(.)folder`, `(..)folder`, and `(...)folder` prefixes.

## Convention

| Prefix | Intercepts |
| --- | --- |
| (.)folder | Same level — matches a sibling route |
| (..)folder | One level up — matches a route in the parent segment |
| (...)folder | Root level — matches a route from the app root |

## A photo modal

The most common use case is showing content in a modal on SPA navigation, with the full page as a fallback on hard navigation.

### File Structure

```tsx title="File structure"
src/app/
├── layout.tsx              ← renders {children} + {modal}
├── page.tsx                ← feed page
├── @modal/
│   ├── default.tsx         ← empty by default (no modal open)
│   └── (.)photo/[id]/
│       └── page.tsx        ← photo modal (interceptor)
└── photo/[id]/
└── page.tsx            ← full photo page (hard nav)
```

### Root Layout

The layout receives the `modal` parallel slot as a prop. No special wrapper component needed — just render it directly:

```tsx title="app/layout.tsx"
export default function Layout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
<div>
  <main>{children}</main>
  {modal}
</div>
  );
}
```

### Default Slot

The `@modal/default.tsx` renders when no interception is active:

```tsx title="app/@modal/default.tsx"
export default function ModalDefault() {
  return null;
}
```

### Interceptor Component

The interceptor at `@modal/(.)photo/[id]/page.tsx` receives the target route's params. It can be a server component — only the frame around it needs to be interactive:

```tsx title="app/@modal/(.)photo/[id]/page.tsx"
import { ModalShell } from '../../../components/ModalShell';
import { findPhoto } from '../../../../data';

export default async function PhotoModal({ id }: { id: string }) {
  const photo = await findPhoto(id);

  return (
<ModalShell>
  <h2>{photo.title}</h2>
  <p>This renders in a modal on SPA navigation.</p>
</ModalShell>
  );
}
```

Read the same data the full page reads. An interceptor pointed at a
different source than the page it stands in for looks exactly like a
broken interception: the modal opens correctly and says the record does
not exist.

### Closing It

The engine puts the interceptor in the slot; the affordances for dismissing it are yours to write. A modal needs three, and the last two are the ones that get forgotten — a close control, the `Escape` key, and a click on the backdrop:

```tsx title="components/ModalShell.tsx"
"use client";

import { useEffect, useRef } from 'react';
import type { ReactNode } from 'react';

export function ModalShell({ children }: { children: ReactNode }) {
  const close = useRef<HTMLButtonElement>(null);

  useEffect(() => {
// The only way to dismiss a dialog without a pointer.
const onKey = (event: KeyboardEvent) => {
  if (event.key === 'Escape') history.back();
};

window.addEventListener('keydown', onKey);
close.current?.focus();

return () => window.removeEventListener('keydown', onKey);
  }, []);

  return (
<div className="modal-backdrop" onClick={() => history.back()}>
  {/* A click inside the dialog is not a click on the backdrop. */}
  <article role="dialog" aria-modal="true" onClick={(e) => e.stopPropagation()}>
    <button ref={close} aria-label="Close" onClick={() => history.back()}>
      ×
    </button>
    {children}
  </article>
</div>
  );
}
```

Closing is `history.back()` rather than a link to a fixed URL. The modal was opened by pushing a history entry over the page beneath, so going back is both what the browser's own back button does and what returns to whatever page it was opened *over* — a hardcoded destination is wrong the moment the same modal is reachable from two places.

The router recognises that as leaving an interception and empties the slot without asking the server for anything. The page underneath never left, so closing costs no request and everything typed into it is still there.

A modal reachable from exactly one place can link to that place instead, and a real `<Link>` is worth keeping for it — a link can be opened in a new tab, and it still works before the page hydrates. `history.back()` is for a shell used from several.

### Full Page (Hard Nav)

When a user navigates directly to `/photo/123` (hard refresh, shared link), the normal page renders:

```tsx title="app/photo/[id]/page.tsx"
export default function PhotoPage({ id }: { id: string }) {
  return (
<div>
  <h1>Photo {id}</h1>
  <p>Full photo page — shown on direct navigation or refresh.</p>
</div>
  );
}
```

## How it works

On **SPA navigation** (clicking a Link):

- The client checks the intercept manifest (generated at build time)
- If the target URL matches an intercept pattern, headers are added to the request
- The server resolves the current page from the referer URL, to know which slot the interceptor belongs in
- It renders the interceptor *alone*, and says so with `X-RSC-Revalidate: modal`
- The client puts it in that slot. The page underneath is never re-rendered — so a half-filled form on it is still half-filled

On **hard navigation** (direct URL, refresh):

- Normal route matching — `/photo/123` renders `photo/[id]/page.tsx`
- No interception — the full photo page renders

Re-rendering the page underneath would put the modal on screen at the
cost of rebuilding everything below the layout that declares the slot.
That page is already mounted and still correct; only the slot is new.

## Nested interception

Use `(..)` to intercept routes one level up, or `(...)` to intercept from the app root:

```tsx title="Intercepting from a nested page"
// From /feed, intercept /photo/[id] at the same level
app/@modal/(.)photo/[id]/page.tsx

// From /feed/trending, intercept /photo/[id] one level up
app/feed/@modal/(..)photo/[id]/page.tsx

// From /dashboard/settings, intercept /photo/[id] from root
app/dashboard/settings/@drawer/(...)photo/[id]/page.tsx
```

## Several slots

You can intercept the same route into different slots:

```tsx title="File structure"
app/
├── @modal/(.)photo/[id]/page.tsx     ← renders in "modal" slot
├── @preview/(.)photo/[id]/page.tsx   ← renders in "preview" slot
└── photo/[id]/page.tsx               ← full page
```

## Seeing it work

The example app in the repository has a working one: `@modal/(.)posts/[slug]`
over a feed of posts. Click a post to open it in a modal, then refresh to get
the same route as a page.

---

Route interception builds on [parallel routes](/guides/routing). The `@folder`
convention is worth being comfortable with first — an interceptor is a page
inside a slot, and everything a slot does applies to it.

# Routing

> File-based routes, layouts, loading states and parallel slots.

Source: https://docs.rsc-kit.dev/guides/routing/ · Markdown: https://docs.rsc-kit.dev/guides/routing/index.md

import CodeFromFile from "@/components/CodeFromFile.astro";

Routes are directories. The plugin reads your source tree at build time and
generates the entry that knows about them — there is nothing to register, and
no route table to keep in sync with the files.

## File-based routing

Pages and layouts follow the Next.js App Router conventions. The default source
directory is `src/app`:

```text
src/app/
  layout.tsx          root layout — wraps every page
  loading.tsx         Suspense fallback for every page
  page.tsx            GET /
  @sidebar/
page.tsx          parallel slot "sidebar"
  about/
page.tsx          GET /about
  docs/
layout.tsx        nested layout for /docs/*
page.tsx          GET /docs
sidebar.tsx       colocated component — NOT a route
[slug]/
  page.tsx        GET /docs/:slug
```

> **Somewhere else?**
>
> `src/app` is the default. Set `sourceDir` in the plugin options to put it
> elsewhere — everything below works the same, only the prefix differs.

### Special files

- `page.tsx` — defines a route. Only files named `page.*` create routes.
- `layout.tsx` — wraps every page in the same directory and below. Receives `children`.
- `loading.tsx` — Suspense fallback. Wraps the page in `<Suspense>` automatically. Hierarchical: the nearest one to the page wins.
- `default.tsx` — what a parallel slot renders when no page matches it.
- `middleware.ts` — runs before anything at or below the directory renders, on every path. Not a component: it returns nothing and decides, by redirecting or throwing. Composes up the tree like layouts. See [Authorization](/guides/authorization).
- `@folder/` — a parallel route slot. Rendered as a named prop on the layout that declares it. Adds no URL segment.

Everything else in the directory is a colocated component — importable by pages
and layouts, but not a route.

### Dynamic segments

Square brackets mark a dynamic segment. `[slug]` matches one segment and
arrives as a `slug` prop on the page; `[...path]` catches the rest of the URL.

```tsx title="src/app/docs/[slug]/page.tsx"
export default async function DocsPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;

  return <h1>{slug}</h1>;
}
```

`params` is a promise, and that is deliberate. Awaiting it lets everything above
the read paint first, and the build stores that as one shell serving every url
the route matches. Reading it synchronously would force a fresh render for every
visitor. `searchParams` works the same way.

### Route groups

Parenthesised directories like `(marketing)` group files without adding a URL
segment. `app/(marketing)/pricing/page.tsx` serves `GET /pricing`.

## Fetching data

A server component runs on the server, so it reads its data the way any
server-side module does — by importing it:

```tsx title="src/app/dashboard/page.tsx"
import { revenue, orderCount } from '../../db/stats';

export default async function DashboardPage() {
  const [amount, orders] = await Promise.all([revenue(), orderCount()]);

  return (
<div>
  <h1>Dashboard</h1>
  <p>Revenue: {amount}</p>
  <p>Orders: {orders}</p>
</div>
  );
}
```

There is no data-fetching API to learn, and no request context to thread
through. `db/stats` never enters the client module graph, so neither does the
connection string it opens.

## Server components

Server components are the default: any `.tsx` file without a `"use client"`
directive is one. They may be async, and they may render client components.

## Client components

`"use client"` on the first line marks a module as client code. It hydrates in
the browser and can use hooks, event handlers and browser APIs.

```tsx title="src/components/Counter.tsx"
"use client";

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}
```

The build turns each one into a client reference, so a server component can
import and render it without shipping its own source.

## Navigation

`Link` intercepts the click, fetches the payload, and updates the React tree
without a reload.

```tsx
import Link from '@rsc-kit/core/Link';

<Link href="/docs/installation">Docs</Link>

// Prefetch on hover (the default)
<Link href="/settings" prefetch="hover">Settings</Link>

// Prefetch as soon as the link mounts
<Link href="/dashboard" prefetch="mount">Dashboard</Link>

// Keep the scroll position instead of jumping to the top
<Link href="/docs/rsc" preserveScroll>Stay here</Link>
```

A navigation sends the layout chain the client already has mounted, and the
server answers with only the part below the deepest layout they share. The
layouts above it are never re-rendered, which is why the nav does not flicker
and why a half-typed form in a retained page survives.

### Programmatic navigation

```tsx
"use client";
import { visit, prefetch } from '@rsc-kit/core/router';

await visit('/about');
await visit('/dashboard', { replace: true });  // no back-button entry
prefetch('/settings');                         // warm the cache
```

A default export is available too, if you prefer `router.visit('/about')`.

### Link props

| Prop | Type | Default | What it does |
| --- | --- | --- | --- |
| `href` | `string` | — | The destination. An off-origin URL is left to the browser. |
| `prefetch` | `"hover" \| "mount" \| "click" \| "none"` | `"hover"` | When to warm the cache. `hover` waits 100 ms for the pointer to settle, so crossing a nav bar does not fire a request per link. `true`/`false` are accepted as aliases for `hover`/`none`. |
| `cacheFor` | `number` | `30000` | How long a prefetched payload stays usable, in milliseconds. |
| `replace` | `boolean` | `false` | Replace the history entry instead of pushing one. |
| `preserveScroll` | `boolean` | `false` | Stay where you are instead of scrolling to the top. |

Anything else is passed straight to the underlying `<a>`, `ref` included.

### Loading state

Each `Link` carries a `data-pending` attribute while its navigation is in
flight, which is usually enough on its own:

```css
a[data-pending] {
  opacity: 0.5;
  pointer-events: none;
}
```

When the affected UI is not the link itself, `useLinkStatus` reads the nearest
parent `Link`'s state:

```tsx
"use client";

import { useLinkStatus } from '@rsc-kit/core/useLinkStatus';

function NavContent({ children }: { children: React.ReactNode }) {
  const { pending } = useLinkStatus();

  return (
<span className={pending ? 'opacity-50' : 'opacity-100'}>
  {children}
  {pending && <span className="spinner" />}
</span>
  );
}
```

## Typed links

Every build writes the routes it found into `.rsc-kit/rsc-routes.d.ts`, so
`href` is checked against them rather than being any old string:

```tsx
<Link href="/orders">Orders</Link>
<Link href="/ordres">Orders</Link>
//          ^ Type '"/ordres"' is not assignable. Did you mean '"/orders"'?
```

For a route with params, write the url — a template literal is checked the same
way, including the static part around the value:

```tsx
<Link href={`/posts/${post.slug}`}>Read</Link>
<Link href={`/postz/${post.slug}`}>Read</Link>
//           ^ Type '`/postz/${string}`' is not assignable
```

The same type covers `redirect()`, `visit()`, `prefetch()` and `Form`'s
`action`. Nothing to
configure and no flag — the file is regenerated on every build, so deleting a
page makes every link to it stop compiling.

One thing you will hit immediately: a list of links widens to `string` unless
you say otherwise. `satisfies` keeps each literal *and* checks it, so the typo
fails at the list rather than at the `Link` that renders it:

### When the value is not already a url

A template literal interpolates whatever it is given, and the type cannot stop
it — `${string}` covers spaces, slashes and `?` as happily as a slug. So a
title used as an identifier quietly produces a url that means something else:

```ts
`/posts/${'Q3 report / draft?v=2'}`
// '/posts/Q3 report / draft?v=2' — three segments and a query string
```

Encode it in the template, the same as anywhere else. There is no url builder
to reach for and nothing new to remember:

```tsx
<Link href={`/posts/${encodeURIComponent(post.title)}`}>Read</Link>
```

> **Why there is no route() helper**
>
> The url *is* the file path, and a template literal is already checked against
> it. A builder would only give you a second way to write the same line.

When a destination is computed rather than written, cast it — that is the seam
where you are telling the typechecker something it cannot know:

```ts
import type { Href } from '@rsc-kit/core/routes';

<Link href={savedPath as Href}>Resume</Link>
```

Two limits. A dynamic segment widens to `${string}`, and a template literal type
cannot say "no slashes here" — so `/posts/a/b` type-checks against
`/posts/[slug]`. And before your first build there are no route types yet, so
every href falls back to `string`.

## Reading the url from a client component

`usePathname` and `useSearchParams` read the current url and follow
navigations:

```tsx title="src/components/Filters.tsx"
"use client";

import { useSearchParams } from '@rsc-kit/core/useSearchParams';

export function Filters() {
  const q = useSearchParams().get('q');

  return <p>Showing results for {q}</p>;
}
```

They behave differently on the server, for a reason. A **pathname** is fixed for
a stored page, so `usePathname` just answers with the url being rendered.

A **query string** is not — the same route is asked for with `?q=shoes` and
`?q=hats` — so there is no honest answer at build time, and `useSearchParams`
throws rather than pretending it is empty.

Wrap it, and the throw becomes the fallback:

```tsx title="src/app/search/page.tsx"
export default function SearchPage() {
  return (
<Suspense fallback={<p>Reading the query…</p>}>
  <Filters />
</Suspense>
  );
}
```

React treats the throw as recoverable at the nearest boundary: the fallback is
what gets stored, and the browser renders the real value on hydration.

> **Without a boundary it still works, and that is the problem**
>
> A root `loading.tsx` catches it, so the page is stored showing the fallback
> the whole app shares — for a search page, the word "Loading" where the query
> should be. The build says so rather than leaving you to find it:
>
> ```text
  ○  /search
 ⚠  nothing painted without the root loading.tsx — the fallback the whole
    app shares is standing in for this page. Put a boundary where the
    waiting is.
```

For a **server** component, the query arrives as a prop instead — `searchParams`,
awaited like `params`. Reach for the hook only when the component is
`"use client"` and has to follow navigations.

## Search params as state

[nuqs](https://nuqs.dev) is the usual answer for a filter or a tab that lives
in the url, and it works here with its own adapter:

```tsx title="src/app/layout.tsx"
import { NuqsAdapter } from '@rsc-kit/core/nuqs'

export default function RootLayout({ children }) {
  return <NuqsAdapter>{children}</NuqsAdapter>
}
```

```tsx
const [kind, setKind] = useQueryState('kind')
```

The stock `nuqs/adapters/react` also works, for a **shallow** update — one
that changes the url and nothing else. Where it gives out is `shallow: false`,
the case where a server component reads the query and should render again with
the new one: with no router to call, it falls back to a full page load.

This adapter hands that case to the router, so the page's payload is refetched
in place and every bit of client state survives. It also tells our own
`useSearchParams` about a shallow change — that hook listens for a navigation
event rather than watching history, so an adapter that only writes the url
would leave the rest of the page reading the old query.

`nuqs` is an optional peer dependency. Nothing else imports it.

:::note[Where this should live]
In nuqs, alongside its adapters for Next, Remix and TanStack Router — that is
how every other framework's works, and the `custom` API this is built on is
their escape hatch for a framework that does not have one in-tree yet. It is
here until there are enough people using it to make that contribution a
reasonable ask. When `nuqs/adapters/rsc-kit` exists, this import will point at
it and then be removed.
:::

## Parallel routes

A directory prefixed with `@` is a slot. It renders alongside the page and
arrives as a named prop on the layout **in its own directory** — not on the
innermost one.

```text
src/app/
  layout.tsx          receives { children, sidebar, modal }
  page.tsx            arrives as "children"
  @sidebar/
page.tsx          arrives as "sidebar"
  @modal/
default.tsx       arrives as "modal" — empty until something fills it
```

```tsx title="src/app/layout.tsx"
export default function Layout({
  children,
  sidebar,
  modal,
}: {
  children: React.ReactNode;
  sidebar: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
<div className="flex">
  <aside className="w-[250px]">{sidebar}</aside>
  <main className="flex-1">{children}</main>
  {modal}
</div>
  );
}
```

A layout that does not render a slot it was handed drops it silently — the page
comes out whole apart from the missing region, and nothing warns. Slots are
what [route interception](/guides/route-interception) fills.

## Streaming

On a full page load the HTML streams. React flushes the shell — layouts, static
markup, and every Suspense fallback in it — immediately, and injects the real
content as each boundary resolves.

SPA navigations stream too: the Flight payload is read with
`createFromReadableStream()` as it arrives, so React reconciles progressively
rather than waiting for the last byte.

## What the build stores

Nothing is declared. The build renders each route and stores what it can:

| Outcome | What happened |
| --- | --- |
| The whole page | It rendered to completion. Served from disk, no render per request. |
| A shell | Something was still waiting when the budget expired, but the static parts had already painted. The shell is stored; the rest is rendered per request and streamed in. |
| A redirect | The route only redirects. The redirect itself is stored — status and location — and served without rendering. |

There is no fourth outcome. A route that could not be stored, and did not say
it wanted to be rendered per request, **fails the build** and names the fix:

```text
Some routes could not be prerendered:

  /photo/[id] — renders its params before it can paint, and lists no urls to build

Each one reads request data — params, headers, cookies, or the host —
above every Suspense boundary, so nothing can paint without it.

Put the part that waits inside <Suspense>, or add a loading.tsx beside
the page, so there is something to store while the rest arrives.
```

That is deliberate, and there is no flag to silence it. The alternative is a
category of routes that quietly render per request, which is where the slow
ones go to be forgotten.

See [Static generation](/guides/static-generation) for listing the urls of a
parameterised route, and [Partial prerendering](/guides/ppr) for where the
boundaries go.

# Sections

> Refreshing one region of a page without re-rendering the rest.

Source: https://docs.rsc-kit.dev/guides/sections/ · Markdown: https://docs.rsc-kit.dev/guides/sections/index.md

A page often has one part that changes and a lot that does not. A section names
that part, so an action can refresh it on its own.

```tsx title="src/app/orders/orders.section.tsx"
import { section } from '@rsc-kit/core/section'

async function Orders() {
  const orders = await db.orders()

  return (
<ul>
  {orders.map((o) => <li key={o.id}>{o.reference}</li>)}
</ul>
  )
}

export default section('orders', Orders)
```

Render it like any other component:

```tsx title="src/app/orders/page.tsx"
import Orders from './orders.section'

export default function OrdersPage() {
  return (
<>
  <h1>Orders</h1>
  <Orders />
</>
  )
}
```

## Refreshing it

An action names what it changed, and only that region is rendered again:

```tsx
'use server'

import { revalidate } from '@rsc-kit/core/revalidate'

export async function placeOrder(form: FormData) {
  await db.orders.create({ reference: String(form.get('reference')) })

  revalidate('orders')
}
```

The rest of the page is untouched — not re-rendered and not re-fetched. Whatever
state lives outside the section, including a half-filled form beside it, stays
exactly as it was.

## The name is scoped to the module, not the app

Two pages may both call their section `orders`. The name is resolved through the
module the route declares, not through a table every section in the app writes
to.

That is a security property rather than a convenience. A name-keyed registry is
populated by every section at bundle load, so a lookup by name could reach any
page's region from any url — bounded only by whatever guard happened to sit on
the url that was asked for.

## What a section is not

It is not a cache boundary and not a client component. It renders on the server
like everything else; what it adds is a seam the server can render *into* on its
own, without producing the whole page around it.

# Server actions

> Calling the server from a client component, as an ordinary function.

Source: https://docs.rsc-kit.dev/guides/server-actions/ · Markdown: https://docs.rsc-kit.dev/guides/server-actions/index.md

import CodeFromFile from "@/components/CodeFromFile.astro";

A server action is an async function a client component can call directly. Mark
the module `"use server"` and its exports become callable from the browser; the
body stays on the server.

## Writing one

Nothing is registered and nothing is generated. The build turns each export
into a reference, and the import in a client component resolves to a stub that
performs the call.

## Calling one

`import { placeOrder }` does not pull `actions.ts` into the browser bundle.
Anything that module imports — a database client, a secret — stays on the
server with it.

## What happens on the wire

1. The client component calls the function.
2. React serialises the arguments in the Flight format.
3. The browser sends one `POST /_rsc/action` carrying the action's id and the encoded arguments.
4. The host decodes them and runs the real function.
5. The return value is serialised as Flight and streamed back.

Files travel this way too, without any encoding of your own — see
[File uploads](/guides/file-uploads).

## Returning UI

Step 5 is the same serialiser a page goes through, so an action can answer
with elements instead of data — server components, client components, Suspense
boundaries — and the caller receives real React elements to render:

```tsx title="src/actions.tsx"
'use server';

import { Suspense } from 'react';
import { Counter } from './Counter';

export async function renderCard(name: string) {
  return (
<section>
  <h2>{name}</h2>
  <Counter />
  <Suspense fallback={<p>loading…</p>}>
    <Related to={name} />
  </Suspense>
</section>
  );
}
```

```tsx title="src/CardButton.tsx"
'use client';

const [ui, setUi] = useState<ReactNode>(null);

<button onClick={async () => setUi(await renderCard('ada'))}>card</button>
{ui}
```

The answer streams. The promise resolves as soon as the root row arrives, so
the card mounts with its fallback showing, and `<Related>` fills the hole when
it is done — the action did not wait for it. The browser never receives
`<Related>`'s code: it ran on the server, and only its output crossed.

### Streaming tokens

That is the primitive behind "generative UI". An async component that renders
one chunk and suspends on the next is a streamed answer, with nothing to
install:

```tsx title="src/actions.tsx"
'use server';

export async function ask(prompt: string) {
  const tokens = model.stream(prompt);   // an AsyncIterator<string>

  return (
<Suspense fallback={<p>thinking…</p>}>
  <Tokens from={tokens[Symbol.asyncIterator]()} />
</Suspense>
  );
}

async function Tokens({ from }: { from: AsyncIterator<string> }) {
  const { value, done } = await from.next();

  if (done) return null;

  return (
<>
  {value}
  <Suspense fallback={null}>
    <Tokens from={from} />
  </Suspense>
</>
  );
}
```

Each token is a row in the stream and each `<Suspense>` a hole the next one
fills. That is what `createStreamableUI` from Vercel's AI SDK does under the
hood, in Next as here — the same React serialiser.

Reach for it when the server knows what to render and the client should not:
a card, a chart, a widget. A chat wants data streamed to the client instead
(`streamText` and `useChat` in the AI SDK), because a half-streamed element
tree cannot be cancelled, resumed, retried or persisted, and this one is a
tree as deep as the token count.

## Refreshing what the action changed

An action that changes data usually makes something on screen wrong. Mark it
stale with `revalidate`, and the re-rendered content travels back **with the
action's own answer**:

`placeOrder` in the module above does exactly that: it writes the order, then
calls `revalidate('orders')`.

The tag names a section — a region of the page registered under a name the
server can address on its own:

One request, not two: the caller sees only what its action returned, and the
page updates around it. Nothing else is re-rendered — which is what the second input in
`AddOrder` is there to prove. Type into it, place an order, and
what you typed is still there.

`section()` is deliberately not a client module. The boundary it wraps things in
is one, but the thing it wraps is a server component that fetches its own data,
and a client reference cannot be async.

## Building one with a schema and middleware

A bare `"use server"` function takes whatever it is given and defends itself by
hand. `createActionClient` gives you a shape where the checking, the context
and the types come from one declaration:

```ts title="src/lib/action.ts"
import { createActionClient } from '@rsc-kit/core/action';

export const action = createActionClient({
  // Everything reaching here is a bug or an outage, and its message may name a
  // query, a path, a host. Say something fixed unless you raised it yourself.
  onError: (error) => (error instanceof AppError ? error.message : 'Something went wrong.'),
});
```

```ts title="src/actions.ts"
'use server'

import { z } from 'zod';
import { action } from './lib/action';

export const createPost = action
  .use(async ({ next }) => next({ ctx: { user: await currentUser() } }))
  .use(async ({ ctx, next }) => {
if (!ctx.user) throw new AppError('Sign in first');

return next({ ctx: { audit: `user:${ctx.user.id}` } });
  })
  .input(z.object({ title: z.string().min(3), body: z.string().min(10) }))
  .handler(async ({ input, ctx }) => {
return savePost({ ...input, authorId: ctx.user.id });
  });
```

`input` is typed from the schema and `ctx` from every middleware that ran, so
the handler is checked against both without either being written twice. Add a
`.use()` and the handler's `ctx` grows; change the schema and the handler stops
compiling.

Middleware runs outermost first and wraps what follows, so a step can time or
clean up around the rest, not only check before it. Throw to refuse.

Return what `next()` gave you — it carries the value from everything inside. A
step that neither calls `next()` nor throws is reported as a mistake, because a
forgotten `next()` would otherwise look exactly like a check that passed.

> **A different thing from middleware.ts**
>
> `middleware.ts` in a route directory decides whether a page may render. This
> wraps one action. They are separate because an action is reachable without
> any page — which is why it defends itself.

### Failures come back, they are not thrown

```ts
const result = await createPost({ title: 'x', body: 'y' });

result.data              // what the handler returned
result.validationErrors  // { title: ['Too short'] }
result.serverError       // 'Something went wrong.'
```

Returned rather than thrown, and that is not a style choice: React serialises a
rejected server action opaquely — production strips the message and leaves a
digest — so a thrown validation error reaches the browser as "an error
occurred" with the fields it named gone. A returned object crosses intact.

`<Form>` reads that shape directly, so there is nothing to wire:

```tsx
<Form action={createPost} schema={schema}>
```

The schema then runs twice, in the two places it has to: in the browser so a
mistake costs no round trip, and in the action because the action is a public
endpoint reachable without the form.

### Failing on something a schema cannot know

```ts
.handler(async ({ input, fieldErrors }) => {
  if (await slugTaken(input.slug)) return fieldErrors({ slug: 'Already taken' });

  return save(input);
})
```

It arrives as `validationErrors`, on the field you named, exactly like a schema
failure — so the form renders it in the same place with no extra handling.

`fieldErrors` comes in with the handler's arguments rather than being imported,
and that is what makes it typed: the field names are the schema's, so
`fieldErrors({ slgu: … })` does not compile. There is nothing to pass — the
handler already knows its input.

**Write `return fieldErrors(…)`.** It throws either way, so nothing after it
runs — but TypeScript cannot see that from a destructured argument. Without the
`return`, a `user` you checked is still `possibly undefined` on the next line.
With it, the type narrows and the code reads as what it is: this branch is
over. A forgotten `return` is not a runtime bug; it is a type error that tells
you to add one.

A string is one message; an array is several. The empty key is the whole
submission, for a refusal that is about no field in particular:

```ts
return fieldErrors({ '': 'Sign-ups are closed for the weekend' });
```

:::note[Porting from next-safe-action]
`return returnValidationErrors(schema, { email: { _errors: ['Account not found'] } })`
becomes `return fieldErrors({ email: 'Account not found' })`. No schema
argument, because the typing comes from the handler, and no `_errors` nesting.
:::

## Setting a cookie

Signing someone in is a mutation whose entire result is a cookie, so an action
can write one:

```ts
'use server';

import { cookies } from '@rsc-kit/core/request';

export async function login(formData: FormData) {
  const session = await authenticate(formData);

  (await cookies()).set('session', session.token, {
httpOnly: true,
secure: true,
sameSite: 'lax',
maxAge: 60 * 60 * 24 * 7,
  });
}
```

It lands on the action's own response, so the next navigation already carries
it. `delete` expires one, which is what signing out is.

That `get`/`set`/`delete` trio is the whole surface an auth library needs, so
one can be wired in without this package having an opinion about which. See
[Writing to the response](/guides/authorization#writing-to-the-response) for
where else it works, and where it does not.

## Two at once

Nothing queues them. Each call is an ordinary `fetch`, so two submits fired
together really do overlap — they are not serialised behind one another.

That is a difference from Next, which runs one server action at a time per
client — and it is worth being deliberate about, because Next's queue was
doing something for you that you may not have noticed.

A double-clicked "add to cart" sends two calls either way. Next runs them one
after the other; here they run together.

So if a handler reads a value, changes it and writes it back, two of them can
lose an update. That is ordinary database concurrency, which a per-client queue
was quietly absorbing for you. Fix it where you would fix it anywhere else:

- do the read and the write in one transaction
- use an atomic update instead of read-modify-write
- accept an idempotency key from the form

None of that is new advice. It just stops being optional.

The engine itself is safe under concurrency, and that part is tested rather
than assumed: two actions running at the same moment each get their own
request scope, so their cookies, headers and revalidation marks never reach
each other's response.

An action's answer can carry a re-rendered region with it, and applying two of
those is last-response-wins. Two actions that both `revalidate('orders')` will
leave whichever response *arrived* last on screen, which is usually the one
that committed last — but not necessarily, and nothing detects the difference.

> **Why not just order them**
>
> Tagging each call with a sequence number and ignoring the older one sounds
> like the fix and is worse than the problem. The order they were *sent* in is
> not the order they *committed* in: a slow first action can commit after a
> fast second one, and its tree is then the newer state. Rejecting it because
> it was sent first shows older data. Only the server knows which write won,
> so ordering has to come from there or not at all.

Fire as many as you like when they touch different things. When several touch
the same region, either let the last answer win or serialise them yourself.

`<Form>` gives you `pending` for that. It does not guard itself, so a
double-click sends two requests unless you disable the button.

## Errors

An action that fails does not answer with a Flight stream, so the client turns
the response into an error before the decoder ever sees it:

| Response | What the client throws | What you do |
| --- | --- | --- |
| `X-RSC-Redirect` header | `ServerRedirectError` | Nothing — the browser is sent to the location. |
| `422` | `ServerValidationError`, carrying `errors` | Show the messages. `<Form>` does it for you. |
| Any other failure | `Error`, naming the status | Whatever the app needs. |

```tsx
"use client";

import { ServerValidationError } from '@rsc-kit/core/errors';
import { createPost } from '../actions';

try {
  await createPost(title, body);
} catch (error) {
  if (error instanceof ServerValidationError) {
// error.errors — { title: ['Too short'], body: ['Required'] }
  }
}
```

A redirect is treated as an instruction rather than something to display: an
expired session answers that way, and the right response is the login page, not
a message about one. See [Validation](/guides/validation) for the form-shaped
version of the same flow, which needs no `try`/`catch` at all.

> **An action is a public endpoint**
>
> The id is not a secret and the endpoint takes no session: anything exported
> from a `"use server"` module can be invoked by anyone who can reach your
> server. Check the caller **inside the action** — rendering the button
> conditionally is a UI decision, not a control. See
> [Authorization](/guides/authorization).

# Static generation

> Rendering pages ahead of time, and exporting a site of files.

Source: https://docs.rsc-kit.dev/guides/static-generation/ · Markdown: https://docs.rsc-kit.dev/guides/static-generation/index.md

import CodeFromFile from "@/components/CodeFromFile.astro";

Pages that do not need the request can be rendered once, at build time, and
served from disk — no render per request, no round trip to a database.

## The build decides by rendering

Nothing declares whether a route is stored. The build renders each one with a
budget and watches what happens:

| Outcome | What the probe saw |
| --- | --- |
| The whole page | It rendered to completion. Stored and served from disk. |
| A shell | Something was still waiting when the budget expired, but the static parts had painted. The shell is stored; the rest is rendered per request. |
| A redirect | The route only redirects, so the redirect itself is stored — status and location. |
| Refused | Nothing painted before the page blocked. The build fails. |

The budget is 2 seconds, and `RSC_PPR_TIMEOUT_MS` changes it. A page whose data
resolves inside it is stored whole — including one that called `fetch()`, as
long as the answer arrived.

There is no way to opt out, and that is the point: a route the build cannot
store has its boundary in the wrong place. Put the part that waits inside
`<Suspense>`, or add a `loading.tsx` beside the page, and it becomes a shell.

> **Stored means stored**
>
> Whatever a page read at build time is in the file. If it should reflect the
> current state of the world on every request, it needs to read the request —
> `params`, `searchParams`, `headers()`, `cookies()` — which suspends, and puts
> it behind a boundary rather than in the stored bytes.

## Listing the URLs of a parameterised route

A route with a `[param]` cannot be frozen unless something says which values
exist. Export `generateStaticParams` from the page:

Each object it returns is one URL to build. For a route with several params,
return every combination:

```tsx title="src/app/blog/[year]/[slug]/page.tsx"
export function generateStaticParams() {
  return [
{ year: '2025', slug: 'hello-world' },
{ year: '2025', slug: 'getting-started' },
  ];
}
```

A route that lists nothing is rendered on demand. That is a decision, not a
failure — `/posts/[slug]` in the example app declares no params precisely so
the two paths can be compared side by side.

## Running the prerender

`vite build` does it, at the end, once every bundle exists — prerendering is
the app rendering itself, so it needs the thing the build just produced.

```bash
bun run build
#  ○  /
#  ○  /about
#  ◔  /account
#
#  2 stored, 1 shell
```

### Turning it off

```ts title="vite.config.ts"
rscKit({ sourceDir: 'src', prerender: false });
```

**Try [`connection()`](/guides/connection) first.** It is almost always the
better answer, and this is almost always too big a hammer.

It is also one hammer for two things. The decision that a page has
[nothing to hydrate](/guides/no-javascript) is made in the same build-time
render, so with prerendering off every page renders per request, with the
runtime. That is the right trade for a build machine that cannot reach the
data — the reason this exists — and the wrong one for anything else.

Prerendering **runs your application code**, so it needs whatever that code
needs — a page that queries a database needs that database reachable from the
build. When it is not, marking that one query is a smaller and more accurate
statement than switching prerendering off for every route in the app:

```tsx
await connection()

const rows = await db.query('select * from orders')
```

The build then skips that work, stores everything around it, and the page still
gets a shell. Turning prerendering off stores nothing, anywhere, and every page
renders for every visitor forever.

Reach for this switch when the reason is about the *build itself* rather than
any page:

Two other reasons: a large site adds real time to every build, and a deploy
that has to run migrations first may want to prerender at a later stage
entirely. `RSC_PRERENDER=0` does the same thing for a host that drives the
build out of process and cannot pass an option.

It is off in watch mode regardless — a rebuild on every keystroke that also
re-renders every route is not a feedback loop anyone wants.

### Doing it yourself

`prerender` is also a plain function, exported from `@rsc-kit/core/prerender`,
so it runs wherever your build does. `write` is a callback rather than a
directory, because not every place this runs has a filesystem — `writeTo` is
the `node:fs` implementation of it, and a platform without one passes its own.

You should not need it. The build calls it for you, with the engine bundle it
just produced — a path only the build knows, since Nitro builds the rsc
environment under `node_modules`.

## What gets written

Per route, keyed by its URL — `/` becomes `index`, `/docs/install` becomes
`docs/install`:

| File | For |
| --- | --- |
| `{key}.html` | A full page load. |
| `{key}.flight` | An SPA navigation that replaces the whole document. |
| `{key}.seg1.flight`, `{key}.seg2.flight`, … | An SPA navigation that keeps that many layouts. |
| `{key}.meta.json` | The client chunks and build version the payload belongs to. |
| `{key}.ppr.html` | A shell, stored per route *pattern* rather than per URL. |

The `.seg{n}` variants are what make a prerendered route participate in partial
navigation. Without them every arrival at a frozen page would replace the
document root, unmounting the pages retained behind it — the form you were
filling in would not survive going back to it.

## Serving them

The host checks for a frozen file before it matches a route. `prerendered` is
the source it checks, and like `write` it is a callback:

The generated server does this for you: the build freezes pages into
`.output/server/rsc-static`, and the entry reads them from beside itself.
Nothing found, and the request falls through to a live render.

## A value that must not be frozen

A stored page keeps whatever it rendered, which includes whatever the clock
said at build time. So this renders once, during the build, and serves that
same instant to everyone until the next one:

```tsx
export default function Page() {
  // Frozen. Not "a few seconds stale" — the moment your CI ran.
  return <p>Rendered at {new Date().toISOString()}</p>;
}
```

The build says so rather than leaving you to notice:

```
○  /
   ⚠  froze new Date() — a stored page keeps whatever that returned at build
  time. If it should differ per visitor, await connection() so the page
  renders per request; if only the browser needs it, use(browser()) keeps
  it out of the build entirely.
```

`new Date()`, `Date.now()`, `Math.random()` and `crypto.randomUUID()` are all
watched.

> **Suspense alone does not fix this**
>
> Wrapping it in a boundary changes nothing: prerendering renders straight
> through a component that never awaits, so the value is captured exactly as
> before — same `○`, same warning. A boundary becomes a hole only when
> something inside it *waits* for what the build cannot finish — a read that
> outlasts the build's budget, or a page that has said `await connection()`.

Moving it into a client component makes it worse, not better. Hydration is not
React attaching handlers to existing markup — it *runs* the component, because
that is the only way it learns what the tree should be.

So the body executes twice, once where the HTML came from and once in the
browser, and a clock read inside gives two different answers.

Where the value comes from is what decides it, not whether the component is a
client one:

| the value is | result |
| --- | --- |
| read in a server component | frozen at build time, and the build warns |
| read in a client component's body | produced twice, and the two disagree |
| computed on the server, passed as a prop | travels in the payload, so both renders read the same string |
| read only in the browser | nothing on the server to disagree with |

The third row is the ordinary answer for anything the server can decide. It
does hydrate the client component, and there is no mismatch, because the value
arrived rather than being recomputed. It is still frozen with the page, which
is fine for a build stamp and wrong for a clock.

## Rendering something in the browser only

For a value that is genuinely per-visitor and needs no server — a clock,
`localStorage`, a map, an editor — say so, and React will skip the component on
the server:

```tsx
'use client';

import { Suspense, use, useState } from 'react';
import { browser } from 'react-dom';

function SavedDraft() {
  use(browser('the draft lives in localStorage'));

  const [draft] = useState(() => localStorage.getItem('draft') ?? '');

  return <p>{draft || 'Nothing saved yet'}</p>;
}
```

The page it sits on stays frozen at build time. React stops the server render
at that component and puts the nearest Suspense boundary's fallback into the
HTML; everything around it rendered normally, so there is still a finished
document to store.

```tsx
<Suspense fallback={<p>Loading draft…</p>}>
  <SavedDraft />
</Suspense>
```

That fallback is what visitors see in the first paint, and the real thing
replaces it once the browser renders. There is no mismatch to have, because
only one side ever ran.

Three things to know:

- **The Suspense boundary is required.** Without one, the server render fails
  rather than degrading.
- **It has to be a client component.** `browser()` is about skipping the server
  render of something that will render in the browser; a server component has
  no browser render to fall back to.
- **`browser()` alone does nothing.** Pass it to `use()`. Do not throw it.

The `reason` is optional and only ever read on the server, where it shows up in
the renderer's bailout callback. Give it one anyway — it is the sentence the
next person needs. Pass a function if building it is expensive.

> **This replaced a workaround**
>
> The old answer was an empty first render plus a `useEffect`, which worked by
> making both renders agree on nothing. `browser()` lands the same outcome with
> the fallback in the HTML instead of a blank, and says in the component why.
> It is in `react-dom` 19.3.
>
> This package ships no `ClientOnly` of its own, and now never will — the
> boundary was always React's to draw.

## Exporting a site

Build with `output: 'export'` and the build writes a directory a static host
can serve with no origin at all:

```bash
RSC_OUTPUT=export npm run build
# Exported 9 pages to dist
```

It refuses unless every route came out static. A shell on a static host is a
page that loads and then stays empty forever, because there is nothing running
to fill it in. `RSC_EXPORT_FORCE=1` writes the site anyway and reports what it
left out, which is how you move an app towards being exportable.

A route that only redirects is written as a meta refresh, which is the one
redirect every static host performs without being configured.

## Customising the document

There is no separate shell template. The root `layout.tsx` renders the whole
document, and the build injects the bootstrap script and stylesheet links into
it. The same layout serves streamed and frozen pages.

```tsx title="src/app/layout.tsx"
import './styles.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
<html lang="en">
  <head>
    <meta charSet="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>{children}</body>
</html>
  );
}
```

> **Fonts and global CSS belong in the root layout**
>
> The root layout renders once and survives every SPA navigation, so its
> `<link>` tags load a single time. The same tags in a nested layout or a page
> are re-injected on every navigation.

Per-page titles and meta tags come from the page, not the layout — see
[Page metadata](/guides/metadata).

# Testing

> Three tiers, and the one thing that still needs a browser.

Source: https://docs.rsc-kit.dev/guides/testing/ · Markdown: https://docs.rsc-kit.dev/guides/testing/index.md

Almost everything here is a function, and functions are tested by calling them.
Any test runner works — Bun's, Vitest, Jest — because nothing below needs a
runtime of ours. The examples use `bun:test`.

## Actions, queries and api routes are functions

`"use server"` is a directive for the bundler. In a test file it is a string, and
the function it marks is importable:

```ts title="tests/actions.test.ts"
import { placeOrder } from '../src/actions'
import { getListings } from '../src/queries'

test('placeOrder accepts an item', async () => {
  expect(await placeOrder('a rubber duck')).toEqual({ ok: true })
})

test('getListings answers with a list', async () => {
  expect(await getListings('stay')).toBeInstanceOf(Array)
})
```

An action built on the [action client](/guides/authorization/) runs its whole
middleware chain when called, so a check that refuses a stranger is testable by
calling it as one. It **returns** its failures, so assert on the result:

```ts
const result = await createPost({ title: '' })

expect(result.validationErrors).toEqual({ title: ['too short'] })
```

An api route is the same. Hand it a `Request` and the context the engine would:

```ts title="tests/api.test.ts"
import { GET } from '../src/app/api/greet/[name]/route'

test('greets by name', async () => {
  const res = await GET(new Request('https://app.test/api/greet/ada'), {
params: Promise.resolve({ name: 'ada' }),   // a promise, as the engine gives it
  })

  expect(await res.json()).toEqual({ greeting: 'Hello, ada' })
})
```

:::note[This is more than Next offers]
Next's advice for server actions is end-to-end, because the interesting part
there is the round trip. Here the function *is* the interesting part — the
validation, the middleware, the authorisation — and it is a unit test.
:::

### Reading the request

`cookies()`, `headers()` and the rest read from a scope the host opens per
request. In a test there is no host, so open it yourself:

```ts title="tests/session.test.ts"
import { withRequest } from '@rsc-kit/core/request'
import { currentUser } from '../src/session'

test('a signed-in cookie is a user', async () => {
  const user = await withRequest(
new Request('https://app.test/', { headers: { Cookie: 'session=abc' } }),
currentUser,
  )

  expect(user?.name).toBe('Ada')
})

test('and no cookie is nobody', async () => {
  expect(await withRequest(new Request('https://app.test/'), currentUser)).toBeNull()
})
```

The scope is per call, so two requests in flight in the same test do not see
each other's cookies.

## The whole app, as it is deployed

The tier between a function and a browser, and the one that is ours to offer:
the app as `Request → Response`, through the real router, the real middleware,
the real api routes and the pages the build stored — with no port and no
process.

```ts title="tests/app.test.ts"
import { createTestApp } from '@rsc-kit/core/testing'

const app = await createTestApp()

test('a stored page is served', async () => {
  const res = await app.fetch('/orders')

  expect(res.status).toBe(200)
})

test('a guarded page turns a stranger away', async () => {
  const res = await app.fetch('/admin', { redirect: 'manual' })

  expect(res.status).toBe(307)
  expect(res.headers.get('Location')).toBe('/login')
})

test('a method a route does not export is 405', async () => {
  const res = await app.fetch('/api/health', { method: 'DELETE' })

  expect(res.headers.get('Allow')).toContain('GET')
})
```

This is where a route that renders fine and is served wrong shows up: a guard
that never ran, a stored page that should not have been, a `404` that came back
`200`.

`createTestApp()` builds when your source is newer than the last build, and not
otherwise — the first run pays for it, the rest do not, and an edit is picked
up. It runs your own `vite build`, so what is tested is what ships. Pass
`{ build: false }` in a ci step that already built.

One build and one loaded module per test run, shared across files. That is both
the fast path and the correct one: two copies of the server bundle in one
process would be two client-reference registries.

## Components

`<Form>`, `useField`, `useOnline` and the rest are client components. Test them
with React's own tools and any DOM — the package's own suite uses `happy-dom`
with `react-dom/client` and `act`, and so can yours. Testing Library works the
same way.

## What still needs a browser

One thing: **a server action called over the wire.** The function is testable
directly, and every url is testable through `createTestApp()` — but the wire
call carries an id that React keeps private, so a test holding the source
function cannot address the built one.

That is the same limit Next has, and it is narrower here: it is the encoding of
one round trip, not the action. Everything the action *does* is a unit test
above. For the round trip itself, and for anything that depends on hydration —
`useField` re-rendering, a navigation, an optimistic update reverting — use
Playwright against `vite preview`, which serves the real build.

## What to test where

| what | how |
| --- | --- |
| an action's logic, validation, middleware | call it |
| a query | call it |
| an api route | call `GET`/`POST` with a `Request` |
| anything that reads cookies or headers | `withRequest()` |
| routing, guards, stored pages, status codes | `createTestApp().fetch()` |
| a client component | React + a DOM |
| an action over the wire, hydration, navigation | Playwright |

# Third-party scripts

> Analytics, tag managers and widgets — and why there is no Script component.

Source: https://docs.rsc-kit.dev/guides/third-party-scripts/ · Markdown: https://docs.rsc-kit.dev/guides/third-party-scripts/index.md

Write the tag. React 19 does the rest, and it does the parts Next's `<Script>`
component existed for.

## An external script

```tsx title="src/app/layout.tsx"
export default function RootLayout({ children }) {
  return (
<html>
  <body>
    {children}
    <script async src="https://www.clarity.ms/tag/abc123" />
  </body>
</html>
  )
}
```

Rendered from a server component, React **hoists** it into `<head>` and
**deduplicates** it — render the same `src` in three components and one tag
goes out. `async` means it never blocks the page. That is `afterInteractive`,
without an import.

## An inline snippet

Most analytics ship one — a few lines that stub a global and load the real
thing:

```tsx title="src/app/layout.tsx"
<script
  id="ms-clarity"
  dangerouslySetInnerHTML={{
__html: `(function(c,l,a,r,i,t,y){c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
  t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
  y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "abc123");`,
  }}
/>
```

It renders where you wrote it and runs during parse, **before hydration**. For
a snippet whose job is to start recording as early as possible, that is the
earlier of the two moments and the one its authors intended. Next's
`Script` with `strategy="afterInteractive"` would have made it later.

:::note[Put it in the root layout]
The root layout renders once and is kept across navigations, so the snippet
runs once. In a *page*, a client-side navigation to it re-renders the tag, and
whether the browser runs a script inserted that way is not something to rely on
either way. Site-wide scripts go in the layout; that is where they belong
anyway.
:::

## Porting from Next

| Next's `Script strategy` | here |
| --- | --- |
| `beforeInteractive` | `<script src>` without `async` — the browser blocks on it, which is what that strategy meant |
| `afterInteractive` | `<script async src>`, or the inline snippet above |
| `lazyOnload` | the effect below, inside `requestIdleCallback` |
| `worker` | not supported — that was Partytown, a separate project |

The `id` prop carries across unchanged. `onLoad` and `onReady` are the one
thing that needs a component, because they need to run in the browser:

## When a script has to run after hydration

Rare, and specific: a script that touches DOM React rendered, and would find it
missing if it ran during parse. A ten-line client component covers it, and it is
yours rather than ours because there is nothing to abstract:

```tsx title="src/components/AfterHydration.tsx"
'use client'

import { useEffect } from 'react'

export function AfterHydration({ src, onLoad }: { src: string; onLoad?: () => void }) {
  useEffect(() => {
const tag = document.createElement('script')

tag.src = src
tag.async = true
if (onLoad) tag.onload = onLoad

document.head.append(tag)

return () => tag.remove()
  }, [src, onLoad])

  return null
}
```

Wrap the body in `requestIdleCallback` and it is `lazyOnload`.

## Why nothing ships for this

A `Script` component would be a wrapper around a `script` tag whose two
useful behaviours — hoisting and deduplication — React already provides. The
package's own tests pin that React does, so the day it stops, this page is
what changes rather than your app.

# Typed routes

> Links that fail the typecheck instead of the browser.

Source: https://docs.rsc-kit.dev/guides/typed-routes/ · Markdown: https://docs.rsc-kit.dev/guides/typed-routes/index.md

Every build writes the urls it found to `.rsc-kit/rsc-routes.d.ts`.
`Link`, `visit`, `prefetch` and `Form` accept only those.

```tsx
import Link from '@rsc-kit/core/Link'

<Link href="/about">About</Link>       // ✅
<Link href="/abuot">About</Link>       // ❌ typecheck fails
```

Dynamic segments work through ordinary template literals:

```tsx
<Link href={`/posts/${post.slug}`}>{post.title}</Link>   // ✅
<Link href={`/postz/${post.slug}`}>{post.title}</Link>   // ❌
```

## There is no `route()` helper

Deliberately. A template literal is already checked the same way a builder
would check it, so a builder would only wrap what the language does for free.
One existed and was removed.

The one thing to watch is that a value you interpolate is url-safe.
`` `/posts/${'a / b'}` `` type-checks and means three path segments — use
`encodeURIComponent` when the value is not yours:

```tsx
<Link href={`/posts/${encodeURIComponent(slug)}`}>…</Link>
```

## Search params, typed by the page

A page that [exports a `searchParams` schema](/guides/url-validation) has said
what its query string means. The same schema types every link to it:

```tsx title="src/app/search/page.tsx"
export const searchParams = z.object({
  q: z.string().default(''),
  page: z.coerce.number().int().min(1).default(1),
});
```

```tsx
<Link href="/search" search={{ q: 'shoes', page: 2 }}>Page 2</Link>

<Link href="/search" search={{ sort: 'asc' }}>…</Link>   // does not compile: the page never reads sort
<Link href="/search" search={{ page: '2' }}>…</Link>     // does not compile: page is a number
```

A key the page requires is required on the link — a `q: z.string()` with no
default makes `search` itself required, so the page's error boundary is not
where a missing `q` is found. A page with no schema takes any scalars, and so
does an href that is not one route (`path as Href`), because there is nothing
to check it against.

Values are typed by what the page will **see**, not what the schema accepts:
`z.coerce.number()` takes anything in, and a link typed by that would take
`page: 'two'`. Required-ness comes from the schema's input, the value from its
output. Arrays repeat the key — `tags: ['a', 'b']` is `?tags=a&tags=b`, which
is what `z.array()` parses back.

For `visit()`, `prefetch()` and anything else that wants the string,
`href()` runs the same check:

```ts
import { href } from '@rsc-kit/core/routes';

visit(href('/search', { q: 'shoes', page: 2 }));
```

The build writes one line per route into `rsc-routes.d.ts` that reads the
page module's `searchParams` export as a type. Nothing runs; a page without
the export costs nothing.

## Two limits

**A dynamic segment widens.** `/posts/[slug]` becomes `` `/posts/${string}` ``,
so `/posts/a/b` type-checks even though it does not match at runtime.

**A list widens to `string`** unless you say what it is:

```tsx
const nav = [
  { href: '/', label: 'Home' },
  { href: '/about', label: 'About' },
] satisfies { href: Href; label: string }[]
```

Without `satisfies`, TypeScript infers `string` for `href` and you lose the
check.

## If you never run the generator

`.rsc-kit/rsc-routes.d.ts` is written by the build. Without it — or with a
tsconfig whose `include` does not cover `.rsc-kit` — nothing is registered,
every url-taking prop stays exactly as permissive as a plain `string`, and
nothing breaks. There is no flag to turn this on.

## `redirect()` is not typed

Its destination is usually computed — read from a cookie, handed over by
middleware — so typing it would make the common case a cast.

## Api routes

Every build writes the `route.ts` files it found as well, in their own union —
so a `fetch` to an endpoint that no longer exists stops compiling:

```ts
import { apiUrl } from '@rsc-kit/core/routes'

await fetch(apiUrl(`/api/orders/${id}`))
await fetch(apiUrl('/api/ordrs'))          // does not compile
```

`apiUrl` returns what it was given. It exists because `fetch` takes any
`string`, so without somewhere to put the type there is nothing to check
against — the function is the place.

**Pages and api routes are separate unions on purpose.** `<Link href="/api/health">`
does not compile, because linking to an api route navigates the browser away to
a json document; and `apiUrl('/orders')` does not compile either, because
fetching a page gets html where json was expected. Each refuses the other's
urls, which is the pair of mistakes worth catching.

:::note[Paths, not response types]
This checks the **url**. It does not infer what the endpoint returns — that
would mean a typed `json()` helper of our own in place of `Response.json()`, and
api routes are deliberately web standards with nothing of ours required in them.

For end-to-end types without a fetch at all, a [server action or
query](/guides/queries/) is already typed across the boundary: the return type
is the function's, because it is the same function.
:::

# Typed URLs

> Checking and typing params, query strings and request bodies with a schema you already write.

Source: https://docs.rsc-kit.dev/guides/url-validation/ · Markdown: https://docs.rsc-kit.dev/guides/url-validation/index.md

A url is input from a stranger. `params` arrive as strings, `searchParams` as
more strings, and `?page=banana` reaches your database as `NaN` unless
something stopped it.

Export a schema beside the page and it stops there instead:

```tsx title="src/app/posts/[slug]/page.tsx"
import { z } from 'zod'
import type { PageProps } from '@rsc-kit/core/route-schema'

export const params = z.object({ slug: z.string().min(1) })

export const searchParams = z.object({
  page: z.coerce.number().int().min(1).default(1),
  tag: z.array(z.string()).default([]),
})

export default async function PostPage({ params, searchParams }: PageProps<
  typeof params,
  typeof searchParams
>) {
  const { slug } = await params        // string
  const { page, tag } = await searchParams  // number, string[]
}
```

Both are ordinary exports, read by the build the same way `metadata` and
`generateStaticParams` are. Any [Standard Schema](https://standardschema.dev)
works — Zod, Valibot, ArkType — because the schema is asked to validate itself
and nothing here imports one.

Three things you get that types alone cannot give you:

- **`?page=3` arrives as `3`**, the number, not `"3"`.
- **A missing value arrives as its default**, so there is no `undefined` branch
  to write.
- **A bad value is refused once**, at the edge, instead of surviving as `NaN`
  into whatever the page does next.

Export neither and nothing changes: `params` is the record of strings it always
was, and `searchParams` is a `URLSearchParams`.

## They fail differently, on purpose

This is the part worth reading twice.

| what was wrong | answer | why |
| --- | --- | --- |
| `params` | **404**, `not-found.tsx` | the url does not describe a page |
| `searchParams` | nearest `error.tsx` | the page exists, the query was wrong |

`/posts/` with a slug your schema refuses is not a broken page, it is an
absent one — and a `500` tells a crawler to come back later while a `404` tells
it the thing is gone. Meanwhile refusing a bad `?page=` as a 404 would let one
bad link make a real page look deleted.

The error carries the fields, so a boundary can say which one:

```tsx title="src/app/posts/[slug]/error.tsx"
'use client'

import { isSearchParamsError } from '@rsc-kit/core/route-schema'

export default function Error({ error }) {
  if (isSearchParamsError(error)) {
return <p>That link is not quite right: {Object.keys(error.errors).join(', ')}</p>
  }

  return <p>Something went wrong.</p>
}
```

## Repeated keys

`?tag=red&tag=blue` arrives as an array and `?q=shoes` as a string, without the
schema having to know which shape the url happened to take. So
`z.array(z.string())` and `z.string()` both work on the key you would expect.

## API routes take the same three

Plus the body, which is the one that matters for a `POST`:

```ts title="src/app/api/posts/[id]/route.ts"
import { z } from 'zod'

export const params = z.object({ id: z.coerce.number().int() })
export const searchParams = z.object({ fields: z.string().optional() })
export const body = z.object({ title: z.string().min(1), draft: z.boolean().default(false) })

export async function POST(request: Request, { params, body }) {
  const { id } = await params      // number
  const { title } = await body     // non-empty string

  return Response.json(await createPost(id, title), { status: 201 })
}
```

Awaited, the same way a page awaits its props. That is not only symmetry: a
route that never awaits `searchParams` provably does not vary by it, so the
build can store one answer and serve it for `?utm_source=anything`. Resolved
eagerly, that fact is unknowable and every tracking link misses the stored
answer.

The handler still takes a real `Request` and still returns a real `Response` —
the schemas add a second argument and take nothing away. A route that exports
none behaves exactly as it did before any of this existed.

Statuses follow the same reasoning as a page, plus one:

| what was wrong | answer |
| --- | --- |
| `params` | `404` |
| `searchParams` | `400` with `{ message, errors }` |
| `body` | `422` with `{ message, errors }` |

`422` because that is what a [server action](/guides/validation/) already
returns for a refused field, so a client has one shape to handle rather than
two.

JSON and form encodings both parse, since a url is posted to by `fetch` and by
`<form>` alike. A body that is not valid JSON is a `422` about the body as a
whole rather than a crash.

:::caution[Exporting `body` reads the request]
The schema consumes the stream, so `await request.json()` inside the handler
will find it already read. Use the parsed value — that is the point of it.

Only when you export a `body` schema, and only for `POST`, `PUT`, `PATCH` and
`DELETE`. A `GET` handler is never touched.
:::

## What this is not

A schema here checks the **shape** of a request, not whether the person making
it may. `params.id` being a number says nothing about whose row it is — the
caller chooses the id, and trusting it is the whole of an IDOR.

Authorise on identity, in the handler, after the shape is known good. See
[Authorization](/guides/authorization/).

# Validation

> Surfacing server-side validation errors in a form.

Source: https://docs.rsc-kit.dev/guides/validation/ · Markdown: https://docs.rsc-kit.dev/guides/validation/index.md

Validation errors have one shape everywhere: a field name mapped to the
messages for it.

```ts
{ title: ['The title must be at least 3 characters.'], body: ['The body is required.'] }
```

`ServerValidationError` carries that shape, and `<Form>`
catch it and put it in `errors`. Nothing in a component has to know where the
validation ran.

## In a form

```tsx title="src/components/PostForm.tsx"
"use client";

import { Form } from '@rsc-kit/core/Form';
import { createPost } from '../actions';

export function PostForm() {
  return (
<Form action={createPost}>
  {({ errors, pending }) => (
    <>
      <input name="title" />
      {errors.title?.map((message) => <p key={message} className="error">{message}</p>)}

      <textarea name="body" />
      {errors.body?.map((message) => <p key={message} className="error">{message}</p>)}

      <button disabled={pending}>Create</button>
    </>
  )}
</Form>
  );
}
```

No `try`/`catch`, and no state of your own. A successful submit clears
`errors`; a failed one fills them.

## Outside a form

Catch it yourself, wherever the call rejects with one:

```tsx
"use client";

import { ServerValidationError } from '@rsc-kit/core/errors';
import { createPost } from '../actions';

try {
  await createPost(title, body);
} catch (error) {
  if (error instanceof ServerValidationError) {
setErrors(error.errors);
  }
}
```

## Producing one

> **The server half is the host's**
>
> There is no validation library here, and no rule syntax to learn. What the
> engine defines is the error the client understands — deciding that input is
> invalid is your code's job, or your host's.

### Before it is submitted

`<Form>` takes any [Standard Schema](https://standardschema.dev) —
Zod, Valibot, ArkType, or anything else implementing it. There is no adapter
per library and no import of one: the schema is asked to validate itself.

```tsx title="src/components/PostForm.tsx"
"use client";

import { z } from 'zod';
import { Form } from '@rsc-kit/core/Form';
import { createPost } from '../actions';

const schema = z.object({
  title: z.string().min(3, 'Too short'),
  body: z.string().min(10, 'Too short'),
});

export function PostForm() {
  return (
<Form action={createPost} schema={schema}>
  {({ errors, pending }) => (
    <>
      <input name="title" />
      {errors.title?.map((m) => <p key={m} className="error">{m}</p>)}

      <textarea name="body" />
      {errors.body?.map((m) => <p key={m} className="error">{m}</p>)}

      <button disabled={pending}>Create</button>
    </>
  )}
</Form>
  );
}
```

A failure fills the same `errors` you were already rendering and the action is
never called — so a mistake costs no round trip, and an optimistic update never
shows a row the server was going to refuse. Async schemas are awaited, so a
uniqueness check works the same way.

Field names follow the schema's paths: a nested field is `address.city`, and an
issue belonging to no field — a cross-field rule like "these must match" — is
under the empty string, so it has somewhere to be shown rather than being
dropped.

> **A schema here is a courtesy, not a control**
>
> It runs in the browser. The action is a public endpoint reachable without
> this form — with `curl`, with the wrong values, in any order — so the server
> still has to check. See [Authorization](/guides/authorization).
>
> Use the same schema on both sides if you like; the point is that the one
> running on the server is the one that decides.

### In a JavaScript action

The same schema, on the side that decides. An action **returns** its failure
rather than throwing one, so one line turns that into the error the form
already understands:

```ts title="src/actions.ts"
'use server'

import { schema } from './schema';

export async function createPost(title: string, body: string) {
  const parsed = await schema['~standard'].validate({ title, body });

  if (parsed.issues) {
return { ok: false as const, issues: parsed.issues };
  }

  return { ok: true as const, post: await savePost(parsed.value) };
}
```

```tsx title="src/components/PostForm.tsx"
import { ServerValidationError } from '@rsc-kit/core/errors';
import { issuesToErrors } from '@rsc-kit/core/standardSchema';

async function submit(formData: FormData) {
  const result = await createPost(
formData.get('title') as string,
formData.get('body') as string,
  );

  if (!result.ok) throw new ServerValidationError('Validation failed', issuesToErrors(result.issues));

  return result.post;
}
```

`issuesToErrors` is the same mapping the client-side check uses, so the field
names match whichever side produced them.

## ServerValidationError

| Member | Type | What it holds |
| --- | --- | --- |
| `errors` | `Record<string, string[]>` | Field name to messages. |
| `message` | `string` | A summary, for when there is nowhere to put field errors. |

# View transitions

> What React's ViewTransition animates in an app built with this, and what it does not.

Source: https://docs.rsc-kit.dev/guides/view-transitions/ · Markdown: https://docs.rsc-kit.dev/guides/view-transitions/index.md

React 19.3 ships [`<ViewTransition>`](https://react.dev/reference/react/ViewTransition),
which animates a change by handing it to the browser's View Transition API.
You can use it here. There is nothing to turn on, and no wrapper this package
provides — it is React's component, used directly.

It has one boundary worth knowing before you reach for it, because the failure
is silence: a transition that does not run looks exactly like one you styled
badly.

| the change comes from | animates |
| --- | --- |
| your own `useState`, inside `startTransition` | yes |
| a server action's result, put into state | yes |
| `<Form>` — errors, success, optimistic updates | yes |
| a streamed `<Suspense>` boundary arriving | yes, React does this on its own |
| navigating to another page | yes, behind a flag |

## What works

Ordinary React. Give the changing element a `key` so React sees a replacement
rather than an edit, and commit inside `startTransition`:

```tsx
'use client';

import { useState, startTransition, ViewTransition } from 'react';
import { addToTotal } from '../actions';

export function Total() {
  const [total, setTotal] = useState<number | null>(null);

  return (
<>
  <ViewTransition>
    <p key={String(total)}>{total ?? '—'}</p>
  </ViewTransition>

  <button
    onClick={() =>
      startTransition(async () => {
        const next = await addToTotal(1);

        startTransition(() => setTotal(next));
      })
    }
  >
    add
  </button>
</>
  );
}
```

A server action is in the working column for a reason worth stating: its result
comes back as an ordinary return value, and what you do with it is `useState`.
That makes it a transition like any other. `<Form>` is built on `useState`
throughout, so everything it drives animates the same way.

## Navigating between pages

Off by default, because it changes how every navigation commits:

```ts title="vite.config.ts"
rscKit({ viewTransitions: true })
```

A build-time constant rather than a runtime setting, so an app that does not
ask for it does not carry the boundary at all. What it animates is the segment
a navigation replaces; what a page does inside itself needs no flag.

## Coming back to a page you were just on

A navigation to a page still being held reveals it rather than refetching it,
so the form you were filling in is still filled in. That applies to a link, not
only the back button — having one keep your work and the other throw it away is
a distinction nobody makes while using an app.

It is bounded, because the two halves pull against each other: what comes back
is the tree from when you left, so its data is from then. Thirty seconds by
default, which covers leaving a form to check something and coming straight
back. Past that a link refetches.

```ts
import { setRevealWindow } from '@rsc-kit/core/navigate';

setRevealWindow(0); // never reveal — every link is a fresh request
```

The back button is not bounded. It names a moment, and the page from that
moment is the right answer however old it is.

> **It can hide a server that is down**
>
> Revealing a held page fetches nothing, so those navigations keep working
> when the backend does not. Measured with the process killed: a page visited
> moments ago still navigates, one never visited does not. That is a reveal
> window rather than offline support, and it means a dead server can go
> unnoticed for as long as the window lasts — [`useOffline`](/guides/offline)
> is what surfaces it. Actually surviving with no network is
> [`offline: true`](/guides/offline#surviving-without-one), which is a service
> worker and a different thing entirely.

## Requirements

`react` and `react-dom` at **19.3 or newer**. A scaffolded app pins `^19.2`, so
this is an upgrade:

```bash
npm install react@^19.3 react-dom@^19.3
```

React also documents a [`browser`](https://react.dev/reference/react-dom/browser)
api for rendering a component only in the browser — the right tool for a value
the server cannot know. It is not in 19.3 yet; see
[static generation](/guides/static-generation#a-value-that-must-not-be-frozen)
for what to do meanwhile.

# Deploying

> What to ship, and the two settings that fail quietly.

Source: https://docs.rsc-kit.dev/hosts/deployment/ · Markdown: https://docs.rsc-kit.dev/hosts/deployment/index.md

`npm run build` writes one directory, and it is the deployment:

```
.output/server    the server Nitro built, and the engine it calls
.output/public    hashed assets and the pages frozen at build time
```

```sh
npm run build
npm run start     # node or bun .output/server/index.mjs
```

`npx vite preview` runs the same build through Vite's preview server, which is
what Nitro suggests at the end of a build. Both serve the real thing; `start`
is what a deployment runs.

## Anywhere that runs the runtime

`.output/` is self-contained. Copy it and start it — a container, a VPS, a
process manager, a platform that runs a Node or Bun process. There is nothing to
register and no platform API to satisfy, and **no `node_modules`**: the
dependencies are in the bundle.

```dockerfile
FROM oven/bun:1 AS build
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build

FROM oven/bun:1
WORKDIR /app
COPY --from=build /app/.output ./.output
CMD ["bun", ".output/server/index.mjs"]
```

The second stage carries `.output` and nothing else. On the docs application
that is 1.0 MB against 104 MB of `node_modules`.

## Or a platform, without a Dockerfile

Change the preset and Nitro produces what that platform expects — a Worker and
its `wrangler.json`, a Vercel function, a Netlify handler. See
[Where it runs](/hosts/where-it-runs).

## Two things that fail quietly

**Do not set `NODE_ENV` when starting the server.** The build bakes its mode
into the bundle, so a server started with nothing set is production because it
was *built* that way. Setting it at start time is a second source of truth and
the one that can disagree — and when it disagrees the failure is silent: every
page renders, and none of them hydrate.

The check is React's debug rows in the payload:

```sh
curl -s https://your-app.example.com/ | grep -c ':D{'
```

`0` on a correct production build. Anything else means a development bundle
reached the client.

**Serve `.output/public` at the root.** Nitro does this itself, so this only
matters behind a CDN: point it at that directory and let the hashed filenames do
the caching — they are content-addressed, so they can be cached forever.

## Server actions across a deploy

A server action can close over server-side values, and React encrypts those
before sending them to the browser so the page cannot read them. The process
that decrypts them on the way back has to hold the same key.

By default that key is generated at build time and baked in. Every instance
running the same build agrees, so the only exposure is the deploy itself: a
browser sitting on a page from the old build calls an action on the new one,
and the key has changed underneath it. The call fails.

For most apps that window is seconds and nobody notices. If yours is long
enough to care about — a slow rollout, long-lived pages, an app people leave
open — pin the key:

```sh
# once, kept wherever you keep secrets
openssl rand -base64 32
```

```sh
RSC_ACTION_ENCRYPTION_KEY=<that value>
```

Set it at **build time** and the build stops baking its own; the value is read
from the environment when the server runs, so the same artifact deploys
anywhere.

:::danger[Set it everywhere or nowhere]
Half-configured is worse than unconfigured. If one instance reads the variable
and another falls back to a baked key, they disagree, and the symptom is an
action that fails for some visitors and not others with nothing in the logs
pointing at a key.

Unset, everything works — the build-time key is used, which is the default
precisely because it cannot be got half right.
:::

## Frozen pages and the routes that own them

`.output/public` holds whole frozen pages and PPR shells alongside the assets.
They are read through the `prerendered` reader, which is a function rather than a
directory precisely so a runtime with no filesystem — a Worker — can supply them
from a binding instead.

A route that declares middleware is never cached publicly: it is sent as
`private, no-store`, because middleware runs per visitor. If something in front
of your app also owns the response — an auth proxy re-issuing a session on
pass-through — give the paths it covers a `middleware.ts` so this host knows
they are covered. See [serving shells from a CDN](/guides/edge-caching).

## Rebuild on deploy

Cached responses carry a build version, so a deploy invalidates them.

Ship `.output/` from the same commit as the code that serves it. A server
running one build against another's frozen pages is the one combination nothing
checks for you.

# Where it runs

> A host is a Nitro preset, not a server you write.

Source: https://docs.rsc-kit.dev/hosts/where-it-runs/ · Markdown: https://docs.rsc-kit.dev/hosts/where-it-runs/index.md

There used to be a page here for each runtime, and a server file generated to
match. There is no server file now, and no choice about it either:
[Nitro](https://nitro.build) builds the server around the route tree, and
choosing where an app runs is choosing a preset.

```ts title="vite.config.ts"
import { defineConfig } from 'vite';
import { nitro } from 'nitro/vite';
import react from '@vitejs/plugin-react';
import { rscKit } from '@rsc-kit/core/vite';

export default defineConfig({
  plugins: [
nitro({ preset: 'bun', serveStatic: 'inline' }),
rscKit(),
react(),
  ],
});
```

`bun create rsc-kit@latest my-app` writes that for you. Changing where it deploys is
changing the one string.

## The presets

`rsc-kit` asks about three, because those are the ones it can check for you.
Nitro carries [many more](https://nitro.build/deploy) and they need nothing from
this package — a preset is a string, not an integration.

| `--host` | preset | what you get |
| --- | --- | --- |
| `bun` | `bun` | `.output/server/index.mjs`, and `bun run compile` for a single binary |
| `node` | `node` | `.output/server/index.mjs`, run with `node` |
| `worker` | `cloudflare_module` | a Worker, plus the `wrangler.json` and `_headers` Nitro generates |

Everything else — Vercel, Netlify, Azure, Deno, AWS Amplify — is the same
change:

```ts
nitro({ preset: 'vercel', serveStatic: 'inline' })
```

## Running it

```bash
npm run dev      # vite is the renderer; nothing is prebuilt
npm run build    # writes .output/
npm run start    # runs .output/server/index.mjs
```

A Worker has no `start`, because it is deployed rather than started:

```bash
npm run preview  # wrangler dev, on workerd
npm run deploy   # nitro deploy --prebuilt
```

## Compiling to a single binary

Bun only, and the whole application ends up inside one file — engine, route
tree and assets:

```bash
npm run compile   # builds, then bun build --compile
./dist/app
```

It builds first on purpose. Compiling whatever `.output` happens to hold means
a binary one version behind the source with nothing to say so — and on a
project that has never been built, an `ENOENT` naming a path the app did not
write.

> **A Worker serves the frozen pages from a module**
>
> A Worker has no filesystem, so the directory the build writes is not there
> at request time. The build also writes the same pages as one module beside
> the bundle, `rsc-static-inline.mjs`, which wrangler uploads with the rest
> and the server imports when the directory is missing. Nothing to configure;
> it is why `○` on a Worker means the stored page and not a live render that
> happens to be the same. It counts toward the Worker's script size, which is
> worth knowing on a site with hundreds of frozen pages.

> **Frozen pages stay outside the binary**
>
> The build freezes pages into `.output/server/rsc-static` and the server reads
> them from there. A compiled binary has no filesystem to read — the directory
> is not embedded — so it renders those pages live instead. Everything still
> answers; what you lose is the stored render, not the page.

> **serveStatic: 'inline' is what makes this work**
>
> Without it the binary compiles, starts, serves pages, and 404s every asset.
> Inside a compiled binary the static path resolves into Bun's virtual
> filesystem — where the files on disk are not — and the failure is
> `ENOENT: /$bunfs/public/assets/…` with the pages themselves looking fine.
>
> The generated config sets it. If you write your own, set it too.

## Offline

`rscKit({ offline: true })` writes a service worker into `.output/public`
alongside the assets, so a page someone has visited survives a reload with no
network. Off by default, and covered in [Offline](/guides/offline#surviving-without-one).

## Why `nitro` is pinned

The generated `package.json` pins an exact version rather than a range:

```json
"nitro": "3.0.260903-beta"
```

Nitro's own `latest` tag is a dated prerelease, and it sorts **above** the plain
`3.0.0` on npm. So `^3.0.0` resolves to the older release, which builds without
complaint and then answers 404 to every route. TanStack Start pins a dated beta
for the same reason.

## Assets are Nitro's

The build writes browser assets to `.output/public`, and Nitro serves them from
its own root. There is no `assetsDir` or `assetsUrl` to set: both were removed,
and `rscKit()` refuses a config that still passes them rather than reading a
prefix and ignoring it.

The alternative was the silent version — the markup asks for the app's prefix,
Nitro answers at its own, and the page arrives unstyled and never hydrates with
nothing logged anywhere.

Assets live in `.output/public` and are served by the same process that serves
your pages. If you want nginx or a CDN serving them instead, point it at
`.output/public` — that directory is the deployment.

---

Next: [Deploying →](/hosts/deployment)

# Installation

> From an empty directory to a streaming RSC app.

Source: https://docs.rsc-kit.dev/installation/ · Markdown: https://docs.rsc-kit.dev/installation/index.md

import CodeFromFile from "@/components/CodeFromFile.astro";

There is no scaffolding command. An app is a Vite project with one plugin and
one request handler, so this is the whole of it.

## Create an app

One command, and it asks the rest:

```sh
bun create rsc-kit@latest my-app
```

It asks where it will run (Bun, Node or Cloudflare Workers), whether you want the
React Compiler and which implementation, and whether to include Tailwind. Every
answer has a flag, so it also runs unattended:

```sh
bun create rsc-kit@latest my-app --host=bun --compiler=oxc --tailwind
```

What comes out builds, prerenders, typechecks and serves before you edit it.

The rest of this page is for adding rsc-kit to an app you already have.

## Install

```sh
npm install @rsc-kit/core react react-dom
pnpm add @rsc-kit/core react react-dom
yarn add @rsc-kit/core react react-dom
bun add @rsc-kit/core react react-dom
```

```sh
npm install --save-dev vite @vitejs/plugin-rsc @vitejs/plugin-react @types/react @types/react-dom
pnpm add -D vite @vitejs/plugin-rsc @vitejs/plugin-react @types/react @types/react-dom
yarn add -D vite @vitejs/plugin-rsc @vitejs/plugin-react @types/react @types/react-dom
bun add -d vite @vitejs/plugin-rsc @vitejs/plugin-react @types/react @types/react-dom
```

`@rsc-kit/core` brings the Vite plugin, the render engine and the client
runtime. React 19 and Vite 8 are peer dependencies — the versions the RSC build
needs, not ones this package pins for you.

> **What @vitejs/plugin-react is for**
>
> Fast Refresh: edit a client component and React keeps its state, instead of
> the page reloading and losing it. Put it *after* `rscKit()`.

## Configure Vite

`sourceDir` is where your route tree lives. The defaults are plain Vite ones —
`src/app` in, `dist/client` and `.rsc` out — so a project that adopts them can
call `rscKit()` with nothing at all.

> **Add your own plugins after it**
>
> `rscKit()` includes `@vitejs/plugin-rsc`, which has to see modules before
> any React layer transforms them. Tailwind, the React Compiler and anything
> else go after it in the array.

## Write a root layout

The root layout renders the **whole document** — there is no separate HTML
template, and the build injects the bootstrap script and stylesheet links into
what you return here.

## Write a page

```tsx title="src/app/page.tsx"
export default function HomePage() {
  return <h1>Hello</h1>;
}
```

`app/page.tsx` serves `GET /`, wrapped in `app/layout.tsx`. Nothing registers
it — the plugin reads the directory at build time. See
[Routing](/guides/routing) for the rest of the conventions.

## Serve it

There is no server file to write. Nitro builds one around the route tree, and
`npm run build` leaves it in `.output/`:

```sh
npm run build
npm run start
```

Where it runs is the preset in `vite.config.ts` — see [Where it
runs](/hosts/where-it-runs).

## Scripts

```json title="package.json"
{
  "type": "module",
  "scripts": {
"dev": "vite",
"build": "vite build",
"start": "bun .output/server/index.mjs",
"compile": "bun build --compile .output/server/index.mjs --outfile my-app"
  }
}
```

`build` freezes every page it can, so there is no separate prerender step and
no command for one — freezing runs the app, which needs the bundle the build
just wrote, and only the build knows where that is. Turn it off with
`rscKit({ prerender: false })`.

`start` runs what the build wrote. There is no server file in a scaffolded app —
Nitro builds the server around the route tree, and where it runs is a preset in
`vite.config.ts`. See [Where it runs](/hosts/where-it-runs).

`compile` produces a standalone binary containing the engine, the route tree,
the frozen pages **and** the assets. That last part is `serveStatic: 'inline'`
in the vite config; without it the binary serves pages and 404s every asset.

> **Do not set NODE_ENV**
>
> The build stamps its mode into the bundle, so `npm run start` is
> production because it was *built* that way. Setting `NODE_ENV` yourself adds a
> second source of truth that can disagree — and when it disagrees, every page
> renders and none of them become interactive.
>
> For a development build with React's real error messages, use
> `vite build --mode development`.

Then:

```bash
npm run build   # bundles, and freezes every page it can
npm run start
```

Worth adding a `typecheck` script beside them (`tsc --noEmit`) and running it
in CI. Server components are ordinary functions and pages are ordinary
modules, so the typechecker sees the whole route tree — a page whose props do
not match its `[param]` segment is a compile error rather than a blank page.

## TypeScript

`vite/client` is doing real work in that list: without it a side-effect import
of a stylesheet (`import './styles.css'` in the root layout) is an error, and
`import.meta.env` is untyped.

### Environment variables

There is nothing to install and nothing this package adds — Vite already owns
this. Two rules and one declaration.

Anything named `VITE_*` is **inlined into the client bundle** and ships to the
browser, whether or not a browser file reads it. Everything else stays on the
server, read through `process.env`.

The prefix is the whole boundary, so never put a secret behind it.
`VITE_STRIPE_KEY` is a published key.

Declare the ones you use, and Vite types them:

```ts title="src/env.d.ts"
interface ViteTypeOptions {
  // Turns an unknown import.meta.env key into an error instead of `any`.
  strictImportMetaEnv: unknown;
}

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
}
```

> **On Bun, a misspelled variable still compiles**
>
> `@types/bun` declares its own `ImportMetaEnv`, which cancels out the strictness
> Vite's option adds. You still get autocomplete and `string` instead of
> `string | undefined` — but a typo is `any`, not an error.

#### When they are read

`import.meta.env.VITE_*` is a literal in the bundle: changing one means a
rebuild. `process.env.*` is a live read, so the deploy's environment wins —
with one exception the build makes for you. A route that reads an environment
variable and nothing request-bound is frozen at build time, value included,
because nothing marked it as needing a request. That is the right answer for
`PUBLIC_SITE_NAME` and the wrong one for a feature flag flipped per deploy. For
the second kind, read it after `await connection()`, which keeps the route on
the server. See [Static generation](/guides/static-generation).

#### Validating them

Vite checks the prefix and nothing else: a missing `DATABASE_URL` is
`undefined` until the first query fails. There is nothing native for this
because nothing native is needed — [t3-env](https://env.t3.gg/docs/core) works
unchanged, with any Standard Schema validator:

```ts title="src/env.ts"
import { createEnv } from '@t3-oss/env-core';
import { z } from 'zod';

export const env = createEnv({
  server: { DATABASE_URL: z.string().url() },
  clientPrefix: 'VITE_',
  client: { VITE_API_URL: z.string().url() },
  runtimeEnv: typeof process === 'undefined' ? import.meta.env : { ...import.meta.env, ...process.env },
  emptyStringAsUndefined: true,
});
```

Read `env.DATABASE_URL` instead of `process.env.DATABASE_URL` and three things
follow. It is a `string`, not `string | undefined`. A server variable touched
from a client component throws by name rather than being silently `undefined`.
And because the module validates when it is first imported, a missing variable
fails the **build** — the prerender imports it — instead of the first request
in production.

The build writes its declaration files into `.rsc-kit/` at the project root,
not among your own source. Three of them:

- `rsc-routes.d.ts` — the routes it found, which is what makes `Link` and
  `redirect()` [typed](/guides/routing#typed-links)
- `rsc-env.d.ts` — the host global
- `rsc-engine.d.ts` — the generated bundle

Only what has to be generated is. Anything you can import, you import —
[`Metadata`](/guides/metadata/) comes from the package and works before you have
built anything.

These are ambient, which needs only that they are inside the project and that
the typechecker is told the directory exists:

```json title="tsconfig.json"
{ "include": ["src/**/*", ".rsc-kit/**/*"] }
```

A scaffolded app has that line, and `rsc-kit init` adds it. Leave it out and
the build says so — otherwise typed routes fall back to plain `string` and
nothing else would tell you.

Add `.rsc-kit/` to `.gitignore`.

## Where next

- **Routing** — [Pages, layouts, slots and navigation →](/guides/routing)
- **Server actions** — [Calling the server from a client component →](/guides/server-actions)
- **Static generation** — [Rendering ahead of time, and exporting →](/guides/static-generation)

# Introduction

> React Server Components as a Vite plugin, deployed wherever you like.

Source: https://docs.rsc-kit.dev/introduction/ · Markdown: https://docs.rsc-kit.dev/introduction/index.md

`rsc-kit` is a Vite plugin that gives you React Server Components. You write
pages, layouts and server actions the way you would in the Next.js App Router;
it renders them, streams the HTML, and turns links into navigations that replace
only the part of the page that changed.

It brings no build system of its own — it is a Vite plugin — and it does not
write a server for you either. [Nitro](https://nitro.build) builds one around
your route tree, so where an app runs is a preset: Bun, Node, a Cloudflare
Worker, Vercel, Netlify, Deno.

## What an app looks like

```text
src/app/
  layout.tsx         the document — <html>, <head>, <body>
  loading.tsx        Suspense fallback for everything below
  page.tsx           GET /
  posts/
[slug]/
  page.tsx       GET /posts/:slug
  @modal/
default.tsx      a parallel slot, empty until something fills it
```

Nothing registers those files. The plugin reads the directory at build time and
generates the entry that knows about them.

```tsx title="src/app/posts/[slug]/page.tsx"
import { findPost } from '../../../data'

export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const post = await findPost(slug)

  if (!post) return <h1>No such post</h1>

  return (
<article>
  <h1>{post.title}</h1>
  <p>{post.body}</p>
</article>
  )
}
```

A server component is an ordinary async function. It imports its data module
directly, and neither the module nor its secrets reach the browser.

## What you get

- **Streaming, not waterfalls** — The shell paints before the data resolves. Suspense boundaries fill in as
they finish, in whatever order they finish.
- **Navigations that keep the page** — A navigation sends the layout chain it already has, and the server answers
with only the part that changed. Scroll, focus and half-typed forms survive.
- **Parallel routes and interception** — `@slot` directories render alongside the page. `(.)folder` opens a route as
a modal over the page you were on, and as a real page on refresh.
- **Server actions** — `"use server"` makes an async function callable from a client component.
The body never ships; the call becomes one POST.
- **Queries, without an endpoint** — `query()` marks a read. It travels as a GET, so it can be cached and
prefetched — and reads that happen together leave as one request.
- **Frozen where it can be** — Pages that ask for nothing dynamic are rendered at build time. Pages that do
get their shell frozen and their data streamed.
- **An export target** — The same app can build to a directory of files and be served by anything —
including a CDN with no origin at all.

## Where it runs

You do not write a server. [Nitro](https://nitro.build) builds one from your
route tree, and where it runs is one line in your Vite config:

```ts title="vite.config.ts"
nitro({ preset: 'bun' })
```

Swap the preset for `node`, `cloudflare_module`, `vercel`, `netlify` or `deno`
and the same app deploys there instead. The build produces a `.output`
directory; nothing else changes.

## What it is not

> **No data layer, no CSS pipeline, no dev server of its own**
>
> The build runs your project's Vite config, so Tailwind, PostCSS and the rest
> are configured the way they are in any Vite app. Data access is an import.
> There is no `getServerSideProps` equivalent, and no request context to learn.

## Where to go next

- **Getting started** — [Build and deploy your first app →](/getting-started)
- **Routing** — [Pages, layouts, slots and navigation →](/guides/routing)
- **How it works** — [What happens between a request and a page →](/reference/how-it-works)

# Quick start

> A running app in one command, or added to a project you already have.

Source: https://docs.rsc-kit.dev/quick-start/ · Markdown: https://docs.rsc-kit.dev/quick-start/index.md

## A new app

```sh
bun create rsc-kit@latest my-app
cd my-app
bun run dev
```

That is it. You get a page, a layout, a client component and a Vite config,
wired together and running. There is no server file — Nitro builds one from the
preset in that config when you build.

When you are ready to ship:

```sh
bun run build
bun run start
```

The build prints what it did:

```
  ○  /

  ○  (Static)  prerendered as static content

  1 static
```

Pages marked `○` are **static**: rendered once at build time rather than for
each visitor.

## An app you already have

Already have a project? Add rsc-kit to it:

```sh
bunx rsc-kit@latest init
```

It reads your `package.json`, works out which server you use and where your
source lives, and writes only what is missing:

```
  server      hono
  source      src
  react       will be added

  + src/app/layout.tsx
  + src/app/page.tsx
  + vite.config.ts
  ~ package.json  — added @rsc-kit/core, react, react-dom, vite, nitro, …
  ~ scripts  — dev, build, start, compile, typecheck
```

No server file. Nitro builds one around the route tree, so the app owns a route
tree and a vite config and nothing in between.

**It never overwrites anything.** If you already have a `vite.config.ts`, it
prints the edit to make instead of replacing work you have done. Running it twice is safe — the second run just tells you what is already
in place.

Then:

```sh
bun install
bun run dev
```

## Add a page

Routes are directories under `src/app`. Create a folder, put a `page.tsx` in
it, and it exists:

```tsx title="src/app/about/page.tsx"
export default function AboutPage() {
  return <h1>About</h1>
}
```

```sh
bun run build   # the route tree is read at build time
```

## Doing it by hand

If you would rather wire it up yourself — or the CLI cannot reach your
setup — [Installation](/installation) walks through the same result one file at
a time.

## Where next

- [Routing](/guides/routing) — layouts, dynamic segments, parallel slots
- [Server actions](/guides/server-actions) — mutations without an API route
- [Where it runs](/hosts/where-it-runs) — presets, and compiling to a binary

# How it works

> What happens between a request and a rendered page.

Source: https://docs.rsc-kit.dev/reference/how-it-works/ · Markdown: https://docs.rsc-kit.dev/reference/how-it-works/index.md

Three pieces, and each one can be replaced without disturbing the others.

- **The plugin** reads your route tree at build time and generates the entries.
- **The engine** turns a component and its layouts into a Flight payload and an HTML stream.
- **The host** owns HTTP. It matches a URL, decides how much of the page to send, and streams the answer.

The generated Nitro entry is a host, and it knows nothing about your routes
that the manifest does not tell it.

> **What a Flight payload is**
>
> React's own wire format for a rendered tree — the server's output, serialised.
> It is not HTML: it describes elements, which client components to load and the
> props to give them, so the browser can rebuild the same tree and attach to it.
>
> The server renders a page twice over: once to a Flight payload, then that
> payload to HTML. A navigation asks for the payload alone, because the browser
> can render it into the page it already has.

## A first load

```text
GET /posts/hello
  → the host matches the route in the manifest
  → the engine renders the page inside its layout chain
  → HTML streams out: shell first, Suspense completions as they resolve
  → the Flight payload is embedded for hydration
  → the client bundle hydrates, and the page becomes an SPA
```

The shell — layouts, static markup, every Suspense fallback — is flushed
before anything slow is awaited, so the browser has something to paint while
the data is still in flight.

## A navigation

A `<Link>` click does not ask for the document again. It sends the layout chain
it already has, and gets back only what is below the deepest layout they share:

```text
GET /posts/world
  X-RSC: true
  X-RSC-Segments: app/layout,app/posts/layout

  ← X-RSC-Segment-Depth: 2
  ← X-RSC-Layouts: app/layout,app/posts/layout
  ← a Flight payload for the page alone
```

Depth `0` means a whole document: it replaces the root and clears everything
under it. Anything deeper is handed to a segment boundary — a small client
component sitting between each layout and its children.

It has to be a client component, because server components cannot re-render in
the browser.

The engine gets the last word on the depth: an interceptor targeting a slot on
a layout the client is keeping forces a wider render, because an override can
never reach a layout that is not being re-rendered.

## The headers

| Header | Direction | Meaning |
| --- | --- | --- |
| `X-RSC` | → | Send the Flight payload, not the page. Every answer varies on it. |
| `X-RSC-Segments` | → | The layout chain the client has mounted, outermost first. |
| `X-RSC-Segment-Depth` | ← | The boundary this payload replaces. `0` is a whole document. |
| `X-RSC-Layouts` | ← | The chain to send back next time. |
| `X-RSC-Version` | ↔ | The build. A mismatch mid-session answers `409`. |
| `X-RSC-Action` | → | The server reference being invoked. |
| `X-RSC-Content-Type` | → | The body's real type, because the body itself is sent opaque. |
| `X-RSC-Referer` | → | The page an action or interception came from. |
| `X-RSC-Intercept` | → | Render this route into the named slot. |
| `X-RSC-Revalidate` | → | Render this one region and nothing else. |
| `X-RSC-Location` | ← | Go here instead. |
| `X-RSC-Redirect` | ← | The render redirected. Sent with `204` on a navigation, never a 3xx — `fetch` would follow that and hand the decoder the wrong body. |

## A server action

One `POST /_rsc/action`, carrying the reference id and the arguments in Flight
format. The body travels as `application/octet-stream` with its real type in a
header, so a host that parses multipart cannot consume it before the action
does — reading `Content-Type` instead leaves an upload undecodable.

Anything the action marks stale with `revalidate()` is re-rendered and travels
back **inside the same response**. The caller sees only what its function
returned; the page updates around it, and there is no second request.

A failed action answers with JSON or a redirect header, never a Flight stream.
Handing a failure to the Flight decoder reports the decoder's confusion rather
than what the server said.

## A redirect from a render

Headers flush before the render's slow work, so a redirect has two ways to
arrive and which one depends on where it was thrown:

- **Above every Suspense boundary.** React cannot finish the shell, so the promise for it rejects while the response is still unwritten. A document gets a real 3xx; a navigation gets `204` and `X-RSC-Redirect`.
- **Inside a boundary.** The shell is already out. The destination travels in React's error digest for the client's boundary to perform, and a document also gets a `location.replace` script appended so it need not hydrate first.

Neither buffers anything. See [Redirects](/guides/redirects) for what that
means for an authorization check.

## Frozen answers

Before matching a route, the host looks for a prerendered file. A frozen page
is a whole page, so that lookup happens *after* the two things that ask for
something smaller — a revalidation and an interception — and before everything
else.

Prerendered routes answer partially too: alongside `{path}.flight` the build
writes one variant per depth, and the host serves the one matching the chain
this client shares. Without them, arriving at a stored page would always
replace the document root and unmount the pages retained behind it.

A route that only redirects is stored as the redirect — `{path}.redirect.json`,
holding a status and a location — and answered from that file without rendering
anything.

## Deployments

The version hash identifies the build. A client that navigates after a deploy
gets a `409` and `X-RSC-Location`, which is a full reload — a layout retained
from the previous build has no claim on being right for the new one.

## Further

[`PROTOCOL.md`](https://github.com/rsc-kit/rsc-kit/blob/main/PROTOCOL.md)
in the repository is the full contract: the engine's interface, the socket
framing a detached host uses, and the invariants that fail silently when a new
host gets them wrong. `tests/js/workerProtocol.test.ts` is its executable half.