@rsc-kit/mcp 0.18.1 → 0.20.0

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

@@ -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
@@ -120,7 +138,10 @@ that never ran, a stored page that should not have been, a `404` that came back
 otherwise — the first run pays for it, the rest do not, and an edit is picked
 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. Pass
+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,8 @@ 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.
 
 :::note[Paths, not response types]
 This checks the **url**. It does not infer what the endpoint returns — that

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
@@ -113,6 +114,48 @@ the list:
 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`
@@ -147,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.1",
+  "version": "0.20.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",