@rsc-kit/mcp 0.16.3 → 0.18.0

package/guides/backend-answered-pages.md

@@ -0,0 +1,163 @@
+# Backend-Answered Pages
+
+> BAP — the model for an rsc-kit app with a backend behind it, and how to build for it.
+
+An rsc-kit app with a backend behind it — Laravel, Go, anything that answers
+the contract — is a **BAP: Backend-Answered Pages**. A page is rendered *in
+front of* the backend rather than *by* it. The renderer asks; the backend
+answers.
+
+This page is the whole idea, once. The [Laravel](/hosts/laravel) and
+[Go](/hosts/go) pages are how each backend answers, and
+[Your own backend](/hosts/your-own-backend) is the contract a third one
+implements.
+
+## Beside the shapes you know
+
+| | who renders the page | who the backend talks to | how a page gets data |
+| --- | --- | --- | --- |
+| **MPA** — Blade, Rails views, Inertia | the backend | the browser | in the controller, before the view |
+| **SPA** — React + an API | the browser | the browser, over an API | `fetch('/api/orders')` after load |
+| **BAP** — rsc-kit | a renderer, on the server | the renderer, over loopback | `await rpc('Orders.recent')` inside the component |
+
+If you have built a SPA with an API behind it, you know most of the shape:
+the React app is what the visitor sees, and the backend is the thing it asks
+for data. The one change is that **the React app is rendered on a server, and
+that server is the one asking the backend** — not the browser. The visitor
+gets a finished, streamed page; the backend never builds one.
+
+In plain terms: a restaurant. In an MPA you order from the kitchen and the
+kitchen sends out the whole plate. In a SPA the kitchen hands you an empty
+plate and a recipe, and your browser cooks at the table, running back for
+every ingredient. In a BAP there is a chef between you and the kitchen — the
+renderer. You order a page; the chef plates it right there, asking the kitchen
+through a hatch for what only the kitchen has: your orders, whether you are
+signed in, whether you may be in this room. The kitchen only ever answers. And
+the dishes that never change, the chef plated in advance.
+
+## How it works
+
+```text
+browser  →  renderer  ──render──▶  React
+                │
+                ├─ before rendering:  POST /__rsc/host-call  { "function": "__rsc.middleware", "args": [["auth"]] }
+                └─ during rendering:  POST /__rsc/host-call  { "calls": [{ "function": "Orders.recent", "args": [5] }, …] }
+                                              │
+                                              ▼
+                                         your backend
+```
+
+- **The renderer is the front door.** It is what `vite dev` serves and what
+  Nitro builds into `.output/server`: it routes, renders, serves the pages it
+  froze at build time and the assets, and streams the rest.
+- **One endpoint, one direction.** The renderer calls the backend, never the
+  reverse, with a shared secret the backend checks on every call. The
+  visitor's cookie travels with the call, so the backend's session and auth
+  are the visitor's. The backend needs no credential to reach the renderer;
+  the renderer's pages are the public site.
+- **Everything else stays the backend's.** Any url the React tree does not
+  own — `/login`, a webhook, an OAuth callback, a file under `/storage`, an
+  admin panel — is forwarded to the backend as it is. Per url the rule is: if
+  the React tree has it, React renders it; otherwise the backend does. Nothing
+  is half-and-half on one url.
+- **Calls are batched.** Sibling components each awaiting `rpc()` are one
+  request to the backend, answered in order; a guarded page is typically two
+  backend requests — the guard, then the batch of its reads.
+
+## What the backend is, then
+
+Neither an API nor an MPA. It is the **backend** in the literal sense — the
+part of the application that is not a page: models and the database, sessions
+and auth, policies, validation, queues, mail, events. It does not build pages,
+so it is not an MPA; it does not expose a JSON API to the browser, so it is
+not an API server. It answers one private endpoint that only the renderer can
+call, with functions you write as ordinary classes.
+
+For a Laravel app that means: Laravel stops being the app that serves pages
+and becomes the app that answers them. Eloquent, policies, form requests,
+queues, notifications — all of it stays, and none of it is behind a controller
+any more.
+
+## Building for it
+
+**Pages read by name.** A server component calls the backend the way it would
+call a function, because from its side it is one:
+
+```tsx title="src/app/orders/page.tsx"
+export default async function Orders() {
+  const orders = await rpc<Order[]>('Orders.recent', 5)
+
+  return <ul>{orders.map((o) => <li key={o.id}>{o.number}</li>)}</ul>
+}
+```
+
+No API to design, no routes to declare, no JSON layer between a component and
+a method. `rpc()` exists in server components during a render and nowhere
+else — the browser never calls the backend directly.
+
+**Guards are the backend's, named in `middleware.ts`.** The backend decides
+whether a route may render, in its own vocabulary, and the renderer asks
+before anything at or below that directory renders — including a page frozen
+at build time:
+
+```ts title="src/app/admin/middleware.ts"
+export const middleware = ['auth', 'can:manage-orders']
+```
+
+A refusal is its own kind on the wire — unauthenticated, unauthorized, a
+redirect, a throttle's 429 — and reaches the page as that, never as a 500.
+
+**Mutations are server actions the backend implements.** A function the
+backend registers as an action gets a `"use server"` stub written by the
+build, and a client component imports and calls it. The action says what it
+made stale (`Rsc::revalidate('orders')`, `rsckit.Revalidate(ctx, "orders")`)
+and the answer carries the re-rendered region back.
+
+**Browser-driven reads are queries that call `rpc()`.** A `query()` is a
+JavaScript server function, so its body can be one call into the backend, and
+the browser reads it over GET with [`fetchQuery`, `usePolling`, TanStack or
+SWR](/guides/queries) on top:
+
+```ts
+export const recentOrders = client.query(async () => rpc<Order[]>('Orders.recent', 5))
+```
+
+**Put things where they belong.** Data, identity, rules and jobs are the
+backend's; layout, interaction and everything a visitor sees is React's. A
+page that needs nothing from the backend is frozen at build time and never
+touches it; one that reads per visitor is a shell with holes the backend
+fills. The build's table says which is which.
+
+## Running it
+
+Two processes, and the decision that matters is which faces the internet.
+
+**The renderer in front** is the arrangement to reach for: it serves assets
+and frozen pages straight off disk, renders the rest, forwards what it does
+not own, and holds a backend worker for the length of a *host call*, never a
+render. Restrict the host-call endpoint at the web server so only the renderer
+reaches it.
+
+**The backend in front** proxies pages to the renderer — the dev-mode shape,
+and what a Laravel app does with `RSC_RENDERER_URL`. It holds a worker for the
+whole render while the render calls back for data, so it needs several
+workers and caps concurrency at one fewer than it has.
+
+**What a call costs** is the backend handling a request — under PHP-FPM a
+framework boot, under Octane or a Go process about a millisecond — times the
+number of *sequential* rounds a page needs, which batching keeps to one or
+two.
+
+## When to choose it
+
+A BAP earns its second process when the pages want what a server-rendered
+React app gives — streaming, server components with no client bundle, static
+and partially-prerendered pages, typed routes and actions — *and* the data,
+identity and rules already live in a backend you are keeping. An app whose
+backend is only a database is better as a plain rsc-kit app, where the
+"backend" is an import. An app whose pages are simple forms over a Laravel
+model may be happier as an MPA. Everything in between is what this is for.
+
+---
+
+Next: [Laravel](/hosts/laravel) · [Go](/hosts/go) · [Your own backend](/hosts/your-own-backend)

package/guides/coming-from-next.md

@@ -44,7 +44,13 @@ it, the server evaluates the library's internals for nothing on every render.
 | `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 |
+| `instrumentation.ts` with `register()` | the same file, in `src/` — imported before any page and awaited before the first request; [startup](/guides/instrumentation) |
 | `next-safe-action` | `createActionClient()` — same shape, [below](#actions) |
+| `experimental.optimizePackageImports` | on by default for every barrel package the server imports, with no list — read from the barrel itself; `rscKit({ barrelImports: false })` turns it off |
+| a `middleware.ts` rewrite for subdomains | nothing — a host is a route segment, so `acme.example.com/` reaches `app/[domain]/page.tsx` and `admin.example.com/` reaches `app/admin/page.tsx` — [domains](/guides/domains) |
+| `app/robots.ts`, `app/sitemap.ts` | the same files, the same shapes — [robots, sitemap and llms.txt](/guides/seo-files); `app/llms.ts` beside them |
+| `@react-email/render` in a server action | the same call, in a module that starts with `"use ssr"` — [emails](/guides/emails). Next fails the same way where it renders server components; the directive is how this one moves it |
+| `cache` from `react` | `cache` from `@rsc-kit/core/cache` — React's memoises only inside a component render; this one spans the request, so a guard, the layout and the action share one call. The build names server files still importing React's |
 
 ## Different on purpose
 
@@ -59,7 +65,7 @@ which, and why:
 ```
   ○  /about               no js
   ◐  /orders              85 kB
-     dynamic — called cookies()
+     cookies() in RootLayout streams per request; the rest is stored
 ```
 
 `await connection()` is the one explicit mark, for a page that must render per
@@ -145,10 +151,12 @@ 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.
+2. Fix imports from the table. `bun run typecheck` finds the rest — and the
+   build runs the same check first, as `next build` does, so a link to a
+   route that does not exist cannot ship.
 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.
+   what streams and from which component. Most surprises are a `cookies()`
+   in a layout reaching every page — 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.
 

package/guides/deployment.md

@@ -0,0 +1,129 @@
+# Deploying
+
+> What to ship, and the two settings that fail quietly.
+
+`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.

package/guides/domains.md

@@ -0,0 +1,129 @@
+# Domains and subdomains
+
+> A host as a route segment — admin.example.com reaches app/admin, a tenant's host binds [domain] — with nothing to rewrite.
+
+Next routes a subdomain with a `middleware.ts` that rewrites
+`acme.example.com/settings` to `/acme/settings` before matching, and the
+route tree never learns a host was involved. Here the same rule is the
+router's own, so the build can see it: typed routes, one stored page per
+tenant, and no middleware to write.
+
+## The rule
+
+A request from a host that is not the site's own is matched **with the host
+in front of the path**:
+
+| request | matched as | file |
+| --- | --- | --- |
+| `example.com/admin` | `/admin` | `app/admin/page.tsx` |
+| `admin.example.com/` | `/admin` | `app/admin/page.tsx` — the same file |
+| `acme.example.com/settings` | `/acme/settings` | `app/[domain]/settings/page.tsx`, `domain: "acme"` |
+| `acme.com/settings` | `/acme.com/settings` | the same file, `domain: "acme.com"` |
+
+A subdomain of the site contributes its label; any other host contributes the
+whole host. The site's own hosts — the one in the root layout's
+`metadataBase`, `www.` of it, and any named in `rscKit({ hosts })` — contribute
+nothing, so the apex keeps path routing and an app adds tenants without moving
+a file. `localhost` and an ip address are always the site's own.
+
+Nothing to configure for that: `metadataBase` names the apex, and a
+directory does the rest. `hosts` is for a name that is neither the apex nor a
+subdomain of it and is still the site rather than a tenant — a staging or
+internal name, or a second brand domain:
+
+```ts title="vite.config.ts"
+rscKit({ hosts: ['app.internal', 'example.co.uk'] })
+```
+
+Listing a subdomain there makes it the site by path instead of a tenant —
+the "app on `app.example.com`, marketing on the apex" split — which is a
+choice, not a requirement.
+
+And only when a route could answer it: a `[domain]` directory at the top of
+`app/`, or a directory named for the host. An app with a `metadataBase` and no
+tenant tree routes every host by path, and a proxy that forwards to the app by
+an internal name is not read as a tenant called `internal`.
+
+The visitor's url is untouched: `acme.example.com/settings` stays in the
+address bar, and a link to `/billing` on that page goes to
+`acme.example.com/billing`. Only the match changed.
+
+## A tenant tree
+
+```tsx title="src/app/[domain]/layout.tsx"
+import { notFound } from '@rsc-kit/core/not-found';
+import { tenantByDomain } from '@/lib/tenants';
+
+export default async function TenantLayout({ params, children }) {
+  const { domain } = await params;
+  const tenant = await tenantByDomain(domain); // "acme" or "acme.com", as stored
+
+  if (!tenant) notFound();
+
+  return <TenantProvider tenant={tenant}>{children}</TenantProvider>;
+}
+```
+
+`[domain]` is an ordinary dynamic segment: `params.domain` in every page and
+layout below it, `route('/[domain]/settings', { domain })` typed, `loading.tsx`
+and `error.tsx` where you put them. A directory named for a host,
+`app/admin/`, wins over `[domain]` the way a static segment wins over a
+parameter anywhere else.
+
+One difference from a parameter deeper in the tree: a `[domain]` at the top
+of `app/` binds **only from a host**, never from a path. `example.com/nope`
+is a 404, not a tenant called `nope`, and `acme.example.com/` cannot be
+reached as `example.com/acme`. Next has no such guard — its `[domain]` folder
+matches any path once the rewrite is in place — which is why Next apps tuck
+the tenant tree under a route group.
+
+## Domains in a database
+
+`generateStaticParams` on the tenant route is the hook. The listed hosts are
+rendered at build and stored, one file per host; a host added afterwards
+falls through to the plain tree, or — if the page reads the request — renders
+on demand and resolves at request time:
+
+```ts title="src/app/[domain]/page.tsx"
+export async function generateStaticParams() {
+  const tenants = await db.tenant.findMany({ select: { domain: true } });
+
+  return tenants.map((t) => ({ domain: t.domain }));
+}
+```
+
+A tenant's page that reads `cookies()` or awaits `connection()` is dynamic
+for that tenant and stored for none, exactly as any page is.
+
+## Locally
+
+Keep `metadataBase` as the production host. `localhost` and an ip address
+are always the site's own, so the dev server routes by path as it always
+did, and nothing changes until a `[domain]` directory exists. To try a tenant
+without DNS, send the host the router will see in production:
+
+```bash
+curl -H 'X-Forwarded-Host: acme.example.com' http://localhost:3000/
+```
+
+Or point `acme.example.com` at `127.0.0.1` in `/etc/hosts` and open it on
+the dev server's port in a browser.
+
+## Behind a proxy
+
+The host is read from `X-Forwarded-Host` first, then `Host`. A load balancer
+that terminates TLS and forwards to the app by an internal name still routes
+by the name the visitor typed.
+
+## Not for a static export
+
+An export is served by a file server, which sees no host. Host routing is a
+server feature; an exported site is the site's own on every host it is
+served from.
+
+## Coming from Next
+
+Delete the rewrite in `middleware.ts` and the `[domain]` directory works as
+it did; the segment binds the same value the rewrite put there. Next's
+`rewrite()` for anything else is not here — a host maps to a tree by file,
+not by code.

package/guides/emails.md

@@ -0,0 +1,90 @@
+# Emails and other HTML
+
+> Rendering React to HTML on the server — an email, a PDF, a feed — from a server action or a route, with "use ssr".
+
+An email template is a React component, and `@react-email/render` (or
+`renderToString` from `react-dom/server`) turns it into HTML. Call that from
+a server action and this comes back:
+
+```
+Error: react-dom/server is not supported in React Server Components.
+```
+
+React means it. Where server components render, `react` is a server-only
+build: the renderer needs the client build's internals, and the components it
+would render import that same `react` — no `useState`, no `useContext`. Nothing
+that renders React to HTML can run there, and no alias fixes that. It has to
+run in the **ssr** environment, which every app here already has: the one that
+turns your pages into HTML for the browser.
+
+## `"use ssr"`
+
+Put the rendering — the template and the call that renders it — in a module
+that starts with the directive:
+
+```tsx title="src/lib/email/render.tsx"
+"use ssr";
+
+import { render } from '@react-email/render';
+import { OtpEmail } from './otp-email';
+
+export async function renderOtpEmail(code: string) {
+  const email = <OtpEmail code={code} />;
+
+  const [html, text] = await Promise.all([
+    render(email),
+    render(email, { plainText: true }),
+  ]);
+
+  return { html, text };
+}
+```
+
+Everything else imports it normally:
+
+```ts title="src/lib/email/send-otp.ts"
+import { renderOtpEmail } from './render';
+
+export async function sendOtpEmail(to: string, code: string) {
+  const { html, text } = await renderOtpEmail(code);
+
+  await transporter.sendMail({ to, subject: 'Your code', html, text });
+}
+```
+
+The module runs in the ssr environment, in the same process. Where server
+components render, the build replaces it with proxies of its exports that call
+across — the same thing `"use client"` does for a component, in the other
+direction. In development that is a call into the ssr module runner; in a
+build the module is part of the ssr bundle and the proxies import it from
+there. Nothing to configure.
+
+## The rules
+
+**Exports are async functions.** A call crosses environments, so the answer is
+a promise. A function declared without `async` is refused at build with its
+name; so is a value, a class, `export { … }` or `export *`. Types are fine.
+
+**Pass data across, not elements.** The template is created inside the module,
+from the arguments — `renderOtpEmail(code)`, not `render(<OtpEmail />)` from
+the caller. An element built where server components render carries
+components from that side's `react`, and they would render with no hooks.
+
+**The module's imports belong to the ssr side.** `@react-email/components`,
+`react-dom/server`, a PDF renderer, a Markdown library that uses React — all
+resolved and bundled for the ssr environment. A database client works there
+too, but belongs on the calling side; keep the module to rendering.
+
+## If you import it directly anyway
+
+`react-dom/server` imported where server components render — through a
+library, usually — now fails with the fix in the message rather than React's
+refusal:
+
+```
+react-dom/server cannot run where server components render … Imported by
+src/lib/nodemailer.ts. Put the rendering — the template and the call — in a
+module that starts with "use ssr" …
+```
+
+A build prints the same once, as a warning, naming the file.

package/guides/errors.md

@@ -7,6 +7,15 @@ nearest one wins.
 
 ## When a page throws
 
+With nothing of your own, a page that throws shows the engine's error page
+where the page was, and the layouts around it stay: in development the
+message and stack, in production "Something went wrong" with the digest to
+search the server log for, and a **Try again** in both. It used to show
+nothing — React unmounted the document on hydration, a black page with the
+cause nowhere near it.
+
+That page is the fallback. To show something of your own:
+
 Put an `error.tsx` in the directory you want to cover:
 
 ```tsx title="src/app/orders/error.tsx"
@@ -48,14 +57,19 @@ 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.
+  layout that throws needs an `error.tsx` a directory up. The engine's own
+  page is outermost and catches those too.
 - **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:
+`src/app/not-found.tsx` is rendered for any url no route matches — and a
+client-side navigation to one renders it in place, layout kept, url changed,
+status still 404, the way Next.js does once the page is overridden. Without
+the file, a navigation to a missing url is a full document load of a plain
+"Not found":
 
 ```tsx title="src/app/not-found.tsx"
 import Link from '@rsc-kit/core/Link'