@rsc-kit/mcp 0.17.0 → 0.18.0

package/guides/coming-from-next.md

@@ -44,7 +44,10 @@ 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 |

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/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,7 +57,8 @@ 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.

package/guides/go.md

@@ -0,0 +1,194 @@
+# Go
+
+> A Go process behind the renderer — functions, guards and actions in Go.
+
+Go owns the request: sessions, auth, the database. The renderer owns
+rendering, because that half is React. A server component reaches Go by
+calling `rpc()`, which leaves the renderer as an ordinary POST; a `middleware.ts`
+names guards Go runs before a page renders; a server action the browser calls
+is a Go function the build wrote a stub for.
+
+A [BAP](/hosts/backend-answered-pages) with Go behind it. There is no
+JavaScript to write for Go: the app is what the scaffold writes, and the Go
+side is one package answering
+[the endpoint every backend answers](/hosts/your-own-backend).
+
+```sh
+go get github.com/rsc-kit/go
+```
+
+## Wiring
+
+In a Go module, `init` sees `go.mod` and does the JavaScript half — the route
+tree, `vite.config.ts`, `.env` with `RSC_BACKEND` and a generated secret, the
+scripts — and prints the Go half for you to add:
+
+```sh
+bunx rsc-kit@latest init            # in the directory with go.mod
+bun create rsc-kit@latest my-app --backend=http://127.0.0.1:8080   # or a new app
+```
+
+What it wrote is two lines, read by `vite` in development and by the built
+server in production:
+
+```ini title=".env"
+RSC_BACKEND=http://127.0.0.1:8080
+RSC_HOST_CALL_SECRET=a-long-random-string
+```
+
+And the endpoint, on whatever mux you already have:
+
+```go title="main.go"
+reg := rsckit.NewRegistry()
+// … Register, Middleware, RegisterAction below …
+
+callback, err := rsckit.NewCallbackHandler(reg, os.Getenv("RSC_HOST_CALL_SECRET"))
+if err != nil {
+    log.Fatal(err) // refuses to exist without a secret
+}
+
+mux := http.NewServeMux()
+mux.Handle("POST /__rsc/host-call", callback)
+http.ListenAndServe("127.0.0.1:8080", mux)
+```
+
+The renderer forwards any url its route tree does not own to `RSC_BACKEND`,
+so a Go route on that mux — `/login`, a webhook, an upload — is reachable at
+the renderer's origin too.
+
+## Reading from Go
+
+```go
+reg.Register("Orders.recent", func(ctx context.Context, args rsckit.Args) (any, error) {
+    var limit int
+    if err := args.Bind(&limit); err != nil {
+        return nil, err
+    }
+
+    // The visitor's cookie, forwarded from the page request: this runs as
+    // them, not as nobody.
+    session := rsckit.HeadersFrom(ctx).Get("Cookie")
+
+    return db.RecentOrders(ctx, session, limit)
+})
+```
+
+```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>
+}
+```
+
+`args.Bind` decodes the positional arguments `rpc()` was given; too few is an
+error, extra ones are ignored. Whatever the function returns is encoded as
+JSON and decoded on the other side as whatever `rpc<T>()` was told.
+
+### Refusing
+
+Return a value and it is the result. Return one of these and the render is
+told what happened, rather than handed a 500:
+
+| return | the render gets |
+| --- | --- |
+| `rsckit.InvalidField("name", "…")`, `rsckit.Invalid(map)` | 422, each message under its input on the form that submitted |
+| `rsckit.Unauthenticated()` | 401, the engine's own authentication error |
+| `rsckit.Unauthorized("…")` | 403 |
+| `rsckit.Redirect("/login")` | the browser goes there |
+| `rsckit.Refuse(429, "slow down")` | that status, kept |
+| any other `error` | 500, with the message |
+
+Wrapped errors still answer as what they are — `errors.As` finds the refusal
+inside `fmt.Errorf("…: %w", err)` — and a panic becomes an error for that one
+call rather than taking the server down.
+
+## Route middleware
+
+```ts title="src/app/admin/middleware.ts"
+export const middleware = ['auth', 'can:manage-orders', 'throttle:60,1']
+```
+
+```go
+reg.Middleware("auth", func(ctx context.Context, _ string) error {
+    if !signedIn(rsckit.HeadersFrom(ctx)) {
+        return rsckit.Redirect("/login")
+    }
+    return nil
+})
+
+reg.Middleware("can", func(ctx context.Context, ability string) error {
+    if !allowed(ctx, ability) {
+        return rsckit.Unauthorized("you may not " + ability)
+    }
+    return nil
+})
+```
+
+The renderer sends the list before anything at or below `admin/` renders —
+including a page it froze at build time, before the file is served. A guard
+receives what follows the colon in its name (`"manage-orders"`, `"60,1"`,
+`""`); guards run in order and stop at the first refusal. A name nothing is
+registered for refuses rather than passes: a declared check that silently
+does not happen is the failure this exists to prevent.
+
+## Server actions
+
+```go
+reg.RegisterAction("ordersCancel", "Orders.cancel", func(ctx context.Context, args rsckit.Args) (any, error) {
+    var id int
+    if err := args.Bind(&id); err != nil {
+        return nil, err
+    }
+
+    if err := orders.Cancel(ctx, id); err != nil {
+        return nil, err
+    }
+
+    rsckit.Revalidate(ctx, "orders")
+
+    return nil, nil
+})
+
+// Before each build. The build reads it and writes the stubs.
+reg.WriteActionManifest("rsc-host-actions.json")
+```
+
+```tsx title="src/app/orders/CancelButton.tsx"
+'use client'
+import { ordersCancel } from '../../server-actions.generated'
+
+export function CancelButton({ id }: { id: number }) {
+  return <button onClick={() => ordersCancel(id)}>Cancel</button>
+}
+```
+
+`Revalidate` names a [section](/guides/sections) or `page`, and the answer to
+the action carries it re-rendered rather than the browser being told to ask
+again. Write the manifest as part of the build — the example's `build`
+script runs the Go program with `-manifest-only` first — because a stale map
+names a function that has since been renamed, and nothing fails until the
+browser calls it.
+
+## Production
+
+`bun run build` and `bun run start` with the same two variables in the
+renderer's environment. Put the renderer in front and restrict
+`/__rsc/host-call` at the web server, as [Laravel's page](/hosts/laravel/#which-process-faces-the-internet)
+shows; a Go worker is held for the length of a host call, never a render.
+
+Or put Go in front: `rsckit.NewRenderer(url)` is a streaming reverse proxy
+to the renderer, and `rsckit.NewHandler(renderer, callback, path)` routes
+the callback path to the endpoint and everything else through it. Both sides
+mark what they forward, so a url neither owns is a 404 rather than a loop.
+
+On a Worker, the two variables are a var and a secret in `wrangler.json`,
+and the Go process has to be reachable from Cloudflare's network — an
+`https` origin behind the secret and, ideally, an allow-list, since loopback
+is not an option there.
+
+---
+
+The runnable version is
+[`examples/go-backend`](https://github.com/rsc-kit/rsc-kit/tree/main/examples/go-backend)
+in the repository: `bun run backend`, `bun run dev`, open the renderer.

package/guides/index.json

@@ -9,6 +9,11 @@
     "title": "Authorization",
     "description": "Protecting pages, server actions and API routes."
   },
+  {
+    "slug": "backend-answered-pages",
+    "title": "Backend-Answered Pages",
+    "description": "BAP — the model for an rsc-kit app with a backend behind it, and how to build for it."
+  },
   {
     "slug": "caching",
     "title": "Asking once per request",
@@ -24,6 +29,16 @@
     "title": "Rendering per request",
     "description": "Marking work that belongs to the visitor, not to the build."
   },
+  {
+    "slug": "deployment",
+    "title": "Deploying",
+    "description": "What to ship, and the two settings that fail quietly."
+  },
+  {
+    "slug": "domains",
+    "title": "Domains and subdomains",
+    "description": "A host as a route segment — admin.example.com reaches app/admin, a tenant's host binds [domain] — with nothing to rewrite."
+  },
   {
     "slug": "edge-caching",
     "title": "Serving shells from a CDN",
@@ -59,6 +74,11 @@
     "title": "Getting started",
     "description": "Serve React Server Components from any JavaScript backend."
   },
+  {
+    "slug": "go",
+    "title": "Go",
+    "description": "A Go process behind the renderer — functions, guards and actions in Go."
+  },
   {
     "slug": "images",
     "title": "Images",
@@ -69,11 +89,21 @@
     "title": "Installation",
     "description": "From an empty directory to a streaming RSC app."
   },
+  {
+    "slug": "instrumentation",
+    "title": "Startup",
+    "description": "instrumentation.ts runs once, before anything else."
+  },
   {
     "slug": "introduction",
     "title": "Introduction",
     "description": "React Server Components as a Vite plugin, deployed wherever you like."
   },
+  {
+    "slug": "laravel",
+    "title": "Laravel",
+    "description": "React Server Components in front, a Laravel application behind them."
+  },
   {
     "slug": "mcp",
     "title": "Working with an AI agent",
@@ -193,5 +223,15 @@
     "slug": "view-transitions",
     "title": "View transitions",
     "description": "What React's ViewTransition animates in an app built with this, and what it does not."
+  },
+  {
+    "slug": "where-it-runs",
+    "title": "Where it runs",
+    "description": "A host is a Nitro preset, not a server you write."
+  },
+  {
+    "slug": "your-own-backend",
+    "title": "Your own backend",
+    "description": "The one endpoint a backend in any language answers."
   }
 ]

package/guides/installation.md

@@ -47,6 +47,7 @@ import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import { nitro } from "nitro/vite";
 import { rscKit } from "@rsc-kit/core/vite";
+import { fileURLToPath } from "node:url";
 
 /**
  * The full route tree, built the way every scaffolded app is built.
@@ -64,6 +65,13 @@ export default defineConfig({
     }),
     react(),
   ],
+  // `@/thing` for `src/thing`, the same alias tsconfig.json declares in
+  // `paths`: both, or the import type-checks and then fails to resolve.
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
 });
 ```
 
@@ -210,15 +218,18 @@ not match its `[param]` segment is a compile error rather than a blank page.
     "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
     "jsx": "react-jsx",
     "strict": true,
     "noEmit": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "verbatimModuleSyntax": true,
     "skipLibCheck": true,
     "resolveJsonModule": true,
-    "types": [
-      "@types/bun",
-      "vite/client"
-    ]
+    "types": ["@types/bun", "vite/client"]
   },
   "include": ["src/**/*", "server/**/*", ".rsc-kit/**/*", "vite.config.ts"]
 }
@@ -228,6 +239,14 @@ not match its `[param]` segment is a compile error rather than a blank page.
 of a stylesheet (`import './styles.css'` in the root layout) is an error, and
 `import.meta.env` is untyped.
 
+Three of those are worth keeping even if you trim the rest.
+`verbatimModuleSyntax` makes a type-only import say so, which is what keeps a
+`type` import of a client component from pulling the component into the server
+bundle. `isolatedModules` and `moduleDetection` are what a per-file transpiler
+like Vite's assumes. And `paths` pairs with `resolve.alias` in `vite.config.ts`
+— `@/thing` for `src/thing` — which some tools (shadcn's `init`, for one) check
+for before they will run.
+
 ### Environment variables
 
 There is nothing to install and nothing this package adds — Vite already owns