@rsc-kit/mcp 0.18.0 → 0.19.0

package/guides/offline.md

@@ -65,8 +65,10 @@ 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.
+it — once the page has loaded, or at once if it already has by the time the
+runtime boots. 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
@@ -86,7 +88,8 @@ on every navigation, so it happens on the first load.
 
 | | |
 | --- | --- |
-| hashed assets | at install, and answered from the cache forever after — the name changes when the bytes do |
+| what boots the app | at install: the scripts, stylesheets, fonts, manifest and icons, plus `/` and the offline page with the payloads they boot from. Not an image, a wasm module or the share card — those are cached the first time they are used, so an install costs what a first page costs and not a megabyte more |
+| any other hashed asset | the first time it is asked for, and 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 |
@@ -178,7 +181,9 @@ export default function Offline() {
 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.
+offline rather than about the url it appears under. It stands in for every
+navigation nothing can answer — a page the build stored but this browser
+never visited included.
 
 **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

package/guides/openapi.md

@@ -0,0 +1,99 @@
+# OpenAPI
+
+> A document derived from your route.ts files, and Scalar's page over it.
+
+Every `route.ts` already says what an OpenAPI operation needs: the methods it
+exports, and the `params`, `searchParams` and `body` schemas beside them. So
+the document is derived, not written — the way Elysia derives its from the
+schemas on its routes — and it cannot go stale.
+
+```ts title="vite.config.ts"
+rscKit({
+  openapi: {
+    info: { title: 'Shop API', version: '1.0.0' },
+    servers: [{ url: 'https://api.shop.example' }],
+    security: [{ bearerAuth: [] }],
+    components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } } },
+  },
+})
+```
+
+`openapi: true` is the same with defaults. The document answers at
+`/openapi.json` (`path` moves it), as an api route the build stores, without
+middleware — a document exists to be read.
+
+## What a route contributes
+
+```ts title="src/app/api/orders/[id]/route.ts"
+import { z } from 'zod'
+import type { RouteContext } from '@rsc-kit/core/route-schema'
+
+export const params = z.object({ id: z.coerce.number().int() })
+export const searchParams = z.object({ expand: z.boolean().optional() })
+export const body = z.object({ title: z.string().min(1) })
+
+export const openapi = {
+  tags: ['Orders'],
+  PATCH: { summary: 'Rename an order' },
+  responses: { 200: { description: 'The order' } },
+}
+
+export async function GET(request: Request, { params }: RouteContext<typeof params>) { … }
+export async function PATCH(request: Request, { params, body }: RouteContext<typeof params, never, typeof body>) { … }
+```
+
+| from | into the document |
+| --- | --- |
+| the directory | the path: `/api/orders/[id]` → `/api/orders/{id}` |
+| each method export | an operation |
+| `params` | the path parameters' types; a segment with no schema is a string |
+| `searchParams` | one query parameter per property, required where the schema requires it |
+| `body` | the request body of `POST`, `PUT`, `PATCH`, `DELETE`, and a documented `422` |
+| a `middleware.ts` above | a `session` security requirement, and `401`/`403` |
+| `export const openapi` | anything else an operation may say — `summary`, `description`, `tags`, `responses` — shared, or per method under `GET`/`POST`/… |
+
+A schema contributes by describing itself as JSON Schema (Standard JSON
+Schema): Zod 4 and ArkType do; Valibot needs its own converter and
+contributes nothing yet. Response bodies are what a route declares in
+`openapi.responses` — a handler returns `Response`, so nothing else knows the
+shape — until a typed response helper carries it.
+
+`export const openapi = false` leaves a route out: the page that renders the
+document, a webhook meant for one caller. `{ DELETE: false }` leaves one
+method out. An app whose routes are mostly webhooks turns the default
+around with `rscKit({ openapi: { include: 'declared' } })`: only a route
+that exports `openapi` is documented, and a callback needs no line. `HEAD` and `OPTIONS` are never documented — the engine answers
+them for every route, and a file exporting `OPTIONS` for a CORS preflight is
+not describing an operation.
+
+## The page
+
+Scalar's API Reference is a route handler in this shape already, so the
+page is one file and none of it is ours:
+
+```sh
+bun add @scalar/nextjs-api-reference
+```
+
+```ts title="src/app/reference/route.ts"
+import { ApiReference } from '@scalar/nextjs-api-reference'
+
+export const GET = ApiReference({ url: '/openapi.json' })
+export const openapi = false
+```
+
+Stored at build like any route that reads nothing per request. Scalar's
+package is the app's dependency and the app's version; the engine ships no
+UI and no dependency for it, whether or not the document is on.
+
+## Coming from a hand-written spec
+
+A spec kept in a file has three parts, and two of them move:
+
+- the `paths` — delete them; they are the routes and their schemas now, and
+  the same `body` schema validates the request at runtime, which the
+  hand-written spec never did
+- `info`, `servers`, `security`, `components.securitySchemes` — into
+  `rscKit({ openapi })`
+- a route's `summary`, `tags` and response shapes — into its
+  `export const openapi`

package/guides/redirects.md

@@ -123,7 +123,18 @@ window, and nothing warns.
 ## 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:
+from the action — a plain `"use server"` function or one built from
+`createActionClient()` — and the client follows it as a navigation: the
+layouts stay mounted and the history entry the form was on is replaced, so
+Back does not return to the submitted form. A `<Form>` shows nothing for it;
+signing in and arriving is the success.
+
+To the caller, the action **resolves** — with `{ redirected: '/where' }` —
+once the navigation is under way. It does not throw: a `startTransition(async
+() => { await logOut() })` with no `catch` around it would otherwise reject
+into React, which unmounts the root, and a logout ended on a white page.
+There is nothing to catch; a component that awaited the action is on its
+way off the screen, and the object it got is safe to read any field of.
 
 ```ts title="src/actions.ts"
 'use server'

package/guides/server-actions.md

@@ -84,6 +84,12 @@ server with it.
 Files travel this way too, without any encoding of your own — see
 [File uploads](/guides/file-uploads).
 
+The id is a hash of the module and the export in a build —
+`9396f92f746f#createOrder` — and nothing about the file is in it. In
+development it is the module's path as Vite serves it
+(`/@fs/Users/…/actions.ts#createOrder`), which is what a
+`$ACTION_ID_…` hidden input in a form shows there; a build never carries it.
+
 ## Returning UI
 
 Step 5 is the same serialiser a page goes through, so an action can answer
@@ -269,11 +275,18 @@ forgotten `next()` would otherwise look exactly like a check that passed.
 ```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.'
+result?.data              // what the handler returned
+result?.validationErrors  // { title: ['Too short'] }
+result?.serverError       // 'Something went wrong.'
 ```
 
+The `?.` is the type's, not decoration: an action that `redirect()`s
+resolves with `undefined` on the client — the page is on its way elsewhere —
+and `result.serverError` on that is a `TypeError` inside a transition, which
+unmounts the root. The type is `Promise<ActionResult<Data> | undefined>`,
+so the unasked read does not compile. In a test, where nothing redirects,
+`result!` is fine.
+
 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
@@ -357,6 +370,37 @@ 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.
 
+## Work the visitor should not wait for
+
+An audit row, a welcome email, a cache warm: the action's answer should not
+wait for it, and it must still finish. `after()` queues work to run once the
+answer is on its way:
+
+```ts
+'use server';
+
+import { after } from '@rsc-kit/core/request';
+
+export async function signup(formData: FormData) {
+  const user = await createUser(formData);
+
+  after(() => sendWelcomeEmail(user));
+  after(() => audit('signup', user.id));
+
+  redirect('/welcome');
+}
+```
+
+Why not a detached promise: on a long-lived process it happens to run to
+completion; on a Worker the isolate is torn down when the response ends
+unless the work was handed to the platform's `waitUntil`, so a promise nobody
+awaited dies silently — some of the time, which is the worst way. `after()`
+is the same call on every host: handed to `waitUntil` where one exists, kept
+by the process elsewhere. A rejection is reported to the log and never
+reaches the response, which has already gone. It works from a component, a
+`middleware.ts`, an api route and an action alike; outside a request — a
+build — the work simply runs.
+
 ## Two at once
 
 Nothing queues them. Each call is an ordinary `fetch`, so two submits fired
@@ -409,11 +453,11 @@ double-click sends two requests unless you disable the button.
 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 |
+| Response | What the client does | 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. |
+| `X-RSC-Redirect` header | Starts the navigation and **resolves** with `{ redirected }` | Nothing — the page is on its way to the location, and there is nothing to catch. |
+| `422` | Throws `ServerValidationError`, carrying `errors` | Show the messages. `<Form>` does it for you. |
+| Any other failure | Throws `Error`, naming the status | Whatever the app needs. |
 
 ```tsx
 "use client";

package/guides/testing.md

@@ -41,7 +41,7 @@ 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
+    params: Promise.resolve({ name: 'ada' }),   // a promise, as the engine gives it - RouteContext types it so
   })
 
   expect(await res.json()).toEqual({ greeting: 'Hello, ada' })
@@ -54,6 +54,24 @@ there is the round trip. Here the function *is* the interesting part — the
 validation, the middleware, the authorisation — and it is a unit test.
 :::
 
+One line a port brings needs a stub: `import 'server-only'`. Keep it — the
+build honours it, and a client file that imports the module fails to build
+rather than shipping a secret. But under Vite the package resolves to an
+empty module on the server, and under `bun test` it is the real package,
+which throws on import; an action file that carries the line is not callable
+in a unit test until a preload stubs it. The scaffold ships the two files:
+
+```toml title="bunfig.toml"
+[test]
+preload = ["./tests/preload.ts"]
+```
+
+```ts title="tests/preload.ts"
+import { mock } from 'bun:test'
+
+mock.module('server-only', () => ({}))
+```
+
 ### Reading the request
 
 `cookies()`, `headers()` and the rest read from a scope the host opens per
@@ -118,7 +136,12 @@ that never ran, a stored page that should not have been, a `404` that came back
 
 `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
+up. It runs your own `build` script — `bun run build` under Bun, `npm run
+build` under Node — so what is tested is what ships, on the runtime it ships
+on. Files the build wrote to `.output/public` — the hashed assets, `sw.js`,
+`manifest.webmanifest`, the icons — are answered too, the way Nitro's static
+layer answers them in production, so a test can prove a page's links resolve
+and not only that the page renders. 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

package/guides/typed-routes.md

@@ -55,7 +55,7 @@ export const searchParams = z.object({
 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
+does an href that is not one route (`path as Route`), because there is nothing
 to check it against.
 
 Values are typed by what the page will **see**, not what the schema accepts:
@@ -88,7 +88,7 @@ so `/posts/a/b` type-checks even though it does not match at runtime.
 const nav = [
   { href: '/', label: 'Home' },
   { href: '/about', label: 'About' },
-] satisfies { href: Href; label: string }[]
+] satisfies { href: Route; label: string }[]
 ```
 
 Without `satisfies`, TypeScript infers `string` for `href` and you lose the
@@ -117,8 +117,17 @@ 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:
+A `route.ts` is a `Route` too — `<Link href="/logout">`, `visit('/agent-account')`
+and `redirect('/files/export.csv')` all typecheck, as they do in Next. What
+differs is what the browser does with one: a route answers with a `Response`,
+not a page, so the client treats a link to it as the anchor it is — never
+prefetched (a hover must not sign someone out) and a full navigation rather
+than a payload fetch. The build hands the client every route's pattern for
+that.
+
+Every build also writes the `route.ts` files in their own narrower union,
+`ApiRoute`, so a `fetch` to an endpoint that no longer exists stops
+compiling:
 
 ```ts
 import { apiUrl } from '@rsc-kit/core/routes'
@@ -131,11 +140,9 @@ await fetch(apiUrl('/api/ordrs'))          // does not compile
 `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.
+`apiUrl('/orders')` does not compile, because fetching a page gets html where
+json was expected — the one mistake the narrower union is for. `Href` and
+`ApiHref` are the same two types under their older names.
 
 :::note[Paths, not response types]
 This checks the **url**. It does not infer what the endpoint returns — that

package/guides/url-validation.md

@@ -86,12 +86,16 @@ 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'
+import type { RouteContext } from '@rsc-kit/core/route-schema'
 
 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 }) {
+export async function POST(
+  request: Request,
+  { params, body }: RouteContext<typeof params, typeof searchParams, typeof body>,
+) {
   const { id } = await params      // number
   const { title } = await body     // non-empty string
 
@@ -99,7 +103,9 @@ export async function POST(request: Request, { params, body }) {
 }
 ```
 
-Awaited, the same way a page awaits its props. That is not only symmetry: a
+`RouteContext` is `PageProps` for a route — each schema's output behind a
+promise, and with none, `RouteContext<'/api/posts/[id]'>` types `params` from
+the segments. 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

package/guides/where-it-runs.md

@@ -62,13 +62,21 @@ 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:
+tree, frozen pages and assets, the precompressed variants included:
 
 ```bash
-npm run compile   # builds, then bun build --compile
+npm run compile   # builds, then bun build --compile .output/server/compile.mjs
 ./dist/app
 ```
 
+`compile.mjs` is written by the build beside the server. It is what puts the
+frozen pages inside the binary: the server reads them through a computed
+import, which a compile cannot see, and this entry imports them by name and
+hands them over before starting the server. Compile `index.mjs` instead and
+the binary still works — it renders those pages live. Nothing else has to
+travel with the binary: not `.output/public`, not `.output/server`. A
+`Dockerfile` copies `dist/app` and runs it.
+
 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
@@ -84,13 +92,6 @@ write.
   worth knowing on a site with hundreds of frozen pages.
 </Aside>
 
-<Aside type="note" title="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.
-</Aside>
-
 <Aside type="caution" title="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
@@ -100,6 +101,61 @@ write.
   The generated config sets it. If you write your own, set it too.
 </Aside>
 
+## Native dependencies stay outside the bundle
+
+A package with a native binary — `sharp`, `bcrypt`, `better-sqlite3`,
+`@prisma/client` — cannot be rolled into a server bundle: the build succeeds
+and the server cannot load its own binary. The usual ones are left external
+by default, and Nitro traces each into `.output/server/node_modules` with its
+binaries, so the deployment is still one directory. For one that is not on
+the list:
+
+```ts
+rscKit({ serverExternalPackages: ['@acme/native-thing'] })
+```
+
+## A polyfill runs first
+
+A dependency that checks for a polyfill at module evaluation — `tsyringe`
+wants `Reflect.getMetadata`, under `@peculiar/x509`, under
+`@simplewebauthn/server` — depends on `import 'reflect-metadata'` running
+before it, and the source has it there. A bundler does not keep that place:
+it emits a chunk's imports before its external ones, whatever the source
+said, so the check ran first — survivable by luck as a directory, fatal
+compiled into a binary. When the project's graph has `reflect-metadata`
+anywhere in it, the build loads it in a Nitro plugin, which the server's
+entry evaluates before any of the app is imported; a project without it
+has nothing that checks. Nothing to add to `instrumentation.ts`.
+
+## A dependency's `"use client"` is read
+
+The other direction. A dependency is bundled into the server graphs — and
+so has its `"use client"` directives read — when it declares `react` as a
+peer dependency, which is what a React library does. One that imports React
+and never says so (a generated component wrapper, a workspace package with
+`react` under `dependencies`, a package whose author forgot) would be left
+external, and its directive is then a string nobody reads: the server loads
+it as a server module and the first `useState` in it fails at render, with an
+error that names React and not the package.
+
+So the build reads the direct dependencies once, and bundles any that carry
+a `"use client"` file and plugin-rsc would not have. It says so:
+
+```text
+[rsc-kit] bundling @acme/chat-widget: it has "use client" files but does not
+declare react as a peer dependency, so its components would otherwise run
+on the server.
+```
+
+Nothing to configure; the line is there so the package's author hears about
+the missing peer. The React-using dependencies under such a package — the
+runtime a generated wrapper calls into — are bundled with it, so there is
+one React for all of them: left external, that runtime would load React
+through Node while everything else got it through Vite, and the hooks
+dispatcher is null in one of the two. Only direct dependencies are read for
+the directive itself — a directive two levels down is the concern of the
+package between, which declared it.
+
 ## Offline
 
 `rscKit({ offline: true })` writes a service worker into `.output/public`
@@ -134,6 +190,28 @@ 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.
 
+## Nothing is sent raw
+
+A bun or node server answering the internet by itself compresses what it
+sends, because nothing in front of it will. The build writes a `.br` and a
+`.gz` beside every public asset larger than a kilobyte, and Nitro serves
+whichever the request accepts — a 147 kB stylesheet is 18 kB on the wire.
+The host gzips what it answers itself — documents, streamed pages, RSC
+payloads, stored pages, api routes — for a request that accepts it, flushing
+every chunk so a streamed shell still reaches the browser before the holes
+fill; a stored page is compressed once and kept.
+
+A port measured what this is worth: with every byte raw, first paint on a
+throttled phone was 3.8 s where 1.2 s was the baseline. That was the whole
+regression.
+
+On a Worker the platform compresses and the host does nothing. Behind a
+CDN or nginx that compresses, the proxy sees an already-encoded answer and
+passes it through. A deployment that would rather its proxy did all of it
+turns the host's half off with `compress: false` on the handler, and Nitro's
+with `compressPublicAssets: false` in its config; `Cache-Control:
+no-transform` on an answer leaves that answer alone.
+
 ---
 
 Next: [Deploying →](/hosts/deployment)

package/guides/your-own-backend.md

@@ -125,19 +125,40 @@ rather than one each:
 { "calls": [ { "function": "Orders.recent", "args": [5] }, { "function": "Me.profile", "args": [] } ] }
 ```
 
-Answer with `replies`, one per call in order, each the reply it would have had
-alone plus the `status` it would have carried:
+Answer **as each call finishes**: `Content-Type: application/x-ndjson`, one
+JSON line per call, carrying its `index` in the batch, the `status` it would
+have had alone, and the reply — in whatever order the calls complete, flushed
+as they do:
+
+```text
+{ "index": 1, "status": 401, "unauthenticated": true }
+{ "index": 0, "status": 200, "result": [ … ] }
+```
+
+That is what keeps a page's boundaries streaming independently after their
+reads travelled together: the renderer resolves each call the moment its
+line lands, so a component waiting on a fast read paints while a slow
+sibling's is still running. The Go module runs the calls concurrently and
+writes each as it returns; Laravel runs them in order and flushes after each.
+Set `X-Accel-Buffering: no` so a proxy in front does not hold the lines back.
+
+A backend that would rather answer the whole batch at once may: one JSON
+object of `replies`, one per call in order, each with its `status`:
 
 ```json
 { "replies": [ { "status": 200, "result": [ … ] }, { "status": 401, "unauthenticated": true } ] }
 ```
 
-Run every call, in order, and answer every one — a refusal in the second is
+The renderer reads either. The saving of the batch is the same; with the
+whole-batch form every call in it waits for the slowest.
+
+Either way, run every call and answer every one — a refusal in the second is
 that call's answer, not a reason to leave the third out. Each call's
-`revalidate` stays with that call. A backend that has not implemented this
-loses nothing but the saving: the renderer reads its "no function name" answer
-as "no batches here" and sends single calls from then on. Batches never mix
-visitors; every call in one carried the same forwarded headers.
+`revalidate` stays with that call. A backend that has not implemented
+batches at all loses nothing but the saving: the renderer reads its "no
+function name" answer as "no batches here" and sends single calls from then
+on. Batches never mix visitors; every call in one carried the same forwarded
+headers.
 
 ## Route middleware
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsc-kit/mcp",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "An MCP server over what an rsc-kit build decided: the routes, why each one is static or not, and what it costs the browser.",
   "type": "module",
   "license": "MIT",