@rsc-kit/mcp 0.18.1 → 0.19.0

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/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.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",