@rsc-kit/mcp 0.18.0 → 0.19.0

package/guides/bun.md

@@ -0,0 +1,76 @@
+# Running on Bun
+
+> What is different when the runtime is Bun — and what only looks like it is.
+
+Bun is the default host, and most of an app never notices. What follows is
+what an app *does* notice, collected from real ports: the framework's part
+first, then the things that will look like the framework's fault and are not.
+
+## Vite runs on Bun too
+
+`vite` is a bin with a Node shebang, so `bun run dev` alone starts Vite —
+and with it the dev server, the build and the prerender — under **Node**. An
+app that imports `bun`, `bun:sqlite` or a Bun-only driver then fails at the
+first render with `Cannot find package 'bun'`, in a project that just said
+it was a Bun app.
+
+The scaffold's scripts run Vite on Bun's runtime, and an existing app should
+too:
+
+```json title="package.json"
+{
+  "scripts": {
+    "dev": "bun --bun vite",
+    "build": "bun --bun vite build",
+    "start": "bun .output/server/index.mjs"
+  }
+}
+```
+
+`createTestApp()` runs that `build` script, so a test builds on the same
+runtime the server ships on.
+
+## 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 title="vite.config.ts"
+rscKit({ serverExternalPackages: ['@acme/native-thing'] })
+```
+
+The same applies on Node; it is only more visible on Bun because the
+scaffold builds there.
+
+## A build machine without the secrets
+
+The build prerenders pages, which runs the app, which runs `instrumentation.ts`,
+which imports `env.ts`. A build machine without the production variables
+sets `SKIP_ENV_VALIDATION=1`; the server that runs the build validates at
+startup regardless. And never `NODE_ENV` in a `.env` — Vite honours it, and
+`NODE_ENV=development` turns `vite build` into a build that cannot render;
+[the build refuses it](/installation#environment-variables) and names the
+line.
+
+## Not the framework's, but you will meet them
+
+- **`bun test` reads `.env`.** Bun loads the package's `.env` into every test
+  run. A test that must not see the app's variables — or must see only the
+  ones it sets — runs with `bun test --env-file=/dev/null`.
+- **Stripe's SDK is async-only on Bun.** `stripe.webhooks.constructEvent()`
+  throws on every call because Bun has no synchronous WebCrypto;
+  `constructEventAsync()` is the same check, awaited.
+- **`pg` puts SQLSTATE in `errno`.** Bun's Postgres driver reports the
+  five-character SQLSTATE (`23505`) where Node's `pg` reports it as `code`.
+  Match on both if the app runs on both.
+- **Bun's `setTimeout(0)` is a real millisecond**, as Node's is. Nothing to
+  do; worth knowing when a test counts ticks.
+
+---
+
+Everything else — presets, deployment, the single binary — is on
+[Where it runs](/hosts/where-it-runs).

package/guides/coming-from-next.md

@@ -29,25 +29,30 @@ it, the server evaluates the library's internals for nothing on every render.
 | Next.js | here |
 | --- | --- |
 | `next/link` | `@rsc-kit/core/Link` — `href` is typed to your routes, and `search` to the page's schema |
+| `import type { Route } from 'next'` | `import type { Route } from '@rsc-kit/core/routes'` — pages and `route.ts` files alike, as in Next; a link to a route is an anchor, never prefetched |
 | `useRouter().push(url)` | `visit(url)` from `@rsc-kit/core/router`; `replace: true` for `.replace()` |
 | `useRouter().refresh()` | `refresh()` from `@rsc-kit/core/router` — or better, `revalidate()` from the action |
 | `usePathname()` | `@rsc-kit/core/usePathname` |
 | `useSearchParams()` | `@rsc-kit/core/useSearchParams`, or [nuqs](/guides/routing#search-params-as-state) with our adapter |
 | `useParams()` | the page's `params` prop, passed down |
-| `cookies()`, `headers()` from `next/headers` | the same names from `@rsc-kit/core/request` |
+| `cookies()`, `headers()` from `next/headers` | the same names and shapes from `@rsc-kit/core/request` — `cookies().get(name)` is `{ name, value }`, `getAll()` a list, `set()` takes either call form |
 | `redirect()` from `next/navigation` | `@rsc-kit/core/redirect` |
+| `after()` from `next/server` | `after()` from `@rsc-kit/core/request` — handed to `waitUntil` on a Worker, detached on a process; [server actions](/guides/server-actions#work-the-visitor-should-not-wait-for) |
 | `notFound()` | `@rsc-kit/core/not-found` |
 | `revalidatePath()`, `revalidateTag()` | `revalidate('tag')` from `@rsc-kit/core/revalidate` — see below, it is narrower |
 | `Metadata` from `next` | `@rsc-kit/core/metadata` — `metadataBase`, `openGraph`, `twitter`, `icons` as you had them |
 | `next/font` | [Fontsource](/guides/fonts): install the font, import its CSS |
 | `next/image` | [unpic](/guides/images) for a CDN, `vite-imagetools` for files in the repo |
 | `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_PUBLIC_*` | `PUBLIC_*`, read through `import.meta.env` (`VITE_*` works too); everything else stays `process.env` on the server |
+| `flags/next` (Vercel's Flags SDK) | unchanged — the build answers its `next/headers` import with `headers()` and `cookies()` from here; [Feature flags](/guides/feature-flags) |
 | `next.config.js` | `vite.config.ts` — Tailwind, aliases and plugins are Vite's |
+| `serverExternalPackages` | `rscKit({ serverExternalPackages })`, with the same default list — sharp, bcrypt, prisma and the rest stay outside the bundle; [Running on Bun](/hosts/bun#native-dependencies-stay-outside-the-bundle) |
 | `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) |
+| a hand-written OpenAPI spec, `@scalar/nextjs-api-reference` | `rscKit({ openapi })` derives the document from every `route.ts` and its schemas; the Scalar package mounts unchanged as a `route.ts` — [OpenAPI](/guides/openapi) |
 | `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 |
@@ -158,7 +163,17 @@ in Next; see [Testing](/guides/testing).
    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.
+5. **Convert the forms and the actions, do not carry them.** A Next app's
+   `useActionState` + `useFormStatus` pair, a `react-hook-form` or
+   TanStack Form setup, and `useState` per input all still compile here —
+   which is exactly why an agent leaves them. Each one becomes
+   `<Form action={…} schema={…}>` (pending state, field errors, works before
+   hydration, uncontrolled by default) and a handler from
+   `createActionClient()` (input validated, `validationErrors` returned
+   rather than thrown, one `onError`). Drop the form library from
+   `package.json` when the last form is converted; a port that keeps two
+   form systems has ported nothing.
+6. `bun run check`. Then a browser, for the parts that are a browser's.
 
 An agent doing the port has all of this: the `.mcp.json` in the scaffold
 answers `how_to({ topic })` and `read_guide({ slug })` from the installed

package/guides/deployment.md

@@ -124,6 +124,16 @@ they are covered. See [serving shells from a CDN](/guides/edge-caching).
 
 Cached responses carry a build version, so a deploy invalidates them.
 
+**Build, then start — never build under a running server.** The server loads
+its rsc and ssr services lazily, on the first request that needs each, and
+a `vite build` that is rewriting `.output/` at that moment hands it a file
+that is half-written or briefly missing. The runtime caches that failed
+import — Bun does, and so does Node's ESM loader — so the route answers 500
+with an `ENOENT` for a file that now exists, and keeps doing so until the
+process restarts. In development use `vite` (the dev server), which owns its
+own rebuilds; in production build into a fresh directory or stop the server
+first, and start it against a finished `.output/`.
+
 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/emails.md

@@ -87,4 +87,16 @@ 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.
+A build prints the same once, as a warning, naming the file — and the
+build still succeeds, because the refusal is the call's, not the import's:
+every export of the stub throws it when called, so a server does not fail to
+boot over an action nobody has run yet.
+
+A dependency whose imports the build never looks inside — `@react-email/render`
+imported from an action, say — is read once for the import and warned about
+the same way, naming the app file and the package:
+
+```
+src/actions/send-otp.ts imports @react-email/render, which imports
+react-dom/server, and that cannot run where server components render …
+```

package/guides/feature-flags.md

@@ -0,0 +1,63 @@
+# Feature flags
+
+> Vercel's Flags SDK runs unchanged — flags/next, without Next.
+
+Nothing to install from here. The [Flags SDK](https://flags-sdk.dev) is
+framework-agnostic at its core, and its Next integration — `flags/next`,
+the one with `flag()`, `dedupe()` and the adapters — needs one thing from
+Next: `next/headers`, for `headers()` and `cookies()`. Those exist here
+under the same names and with the same shapes, one object per request,
+which is what the SDK's per-request dedupe keys on. The build answers
+`next/headers` with them, so the SDK runs as written:
+
+```sh
+bun add flags
+```
+
+```ts title="src/flags.ts"
+import { flag, dedupe } from 'flags/next'
+
+const visitor = dedupe(async ({ cookies, headers }) => ({
+  id: cookies.get('visitor')?.value ?? 'anonymous',
+  country: headers.get('x-vercel-ip-country') ?? headers.get('cf-ipcountry') ?? '',
+}))
+
+export const showBanner = flag<boolean, { id: string; country: string }>({
+  key: 'show-banner',
+  identify: visitor,
+  decide: ({ entities }) => entities?.country === 'GB',
+})
+```
+
+```tsx title="src/app/page.tsx"
+import { showBanner } from '../flags'
+
+export default async function Home() {
+  const banner = await showBanner()
+
+  return banner ? <Banner /> : null
+}
+```
+
+A flag reads the request, so the page that awaits one renders per visitor —
+the build says `headers() in run, cookies() in run stream per request` and
+stores the rest as a shell, given a `<Suspense>` or a `loading.tsx` above
+the read. That is the same line any `headers()` call earns; see
+[Static generation](/guides/static-generation). An adapter — Statsig,
+LaunchDarkly, Vercel's own — is the SDK's, configured the way its docs say.
+
+The discovery endpoint is a route handler in the shape a `route.ts` already
+has:
+
+```ts title="src/app/.well-known/vercel/flags/route.ts"
+import { createFlagsDiscoveryEndpoint, getProviderData } from 'flags/next'
+import * as flags from '../../../../flags'
+
+export const GET = createFlagsDiscoveryEndpoint(async () => getProviderData(flags))
+export const openapi = false
+```
+
+What does not carry over is `precompute()`: it is built on a Next
+middleware rewriting the url to a permutation, which is Next's routing.
+Read the flag in the page instead; a flag read under a boundary costs one
+streamed hole, not the page.

package/guides/fonts.md

@@ -110,6 +110,31 @@ export default function RootLayout({ children }) {
 the one file the first paint needs, usually the Latin regular; preloading all
 of them defeats the subsetting.
 
+## A font never blocks the page
+
+Text paints before the web font arrives, always. That is not a tuning
+choice; it is the rule everything below serves, and a font can break it in
+three ways, each of which the setup above has already closed:
+
+- **A stylesheet from another origin.** `<link href="https://fonts.googleapis.com/…">`
+  is render-blocking CSS from a host the browser has not connected to: a DNS
+  lookup, a TLS handshake and a round trip before the first paint, on every
+  cold load. Self-hosting through Fontsource keeps the `@font-face` rules in
+  your own stylesheet, which is inlined into the document.
+- **`font-display: block`, or none at all.** Without a `font-display`, the
+  browser is free to hide text for up to three seconds while it waits — the
+  invisible-text flash. Every rule the setup writes says `swap` (paint the
+  fallback now, swap when the font lands) or `optional` (paint once, in
+  whichever is ready). Never `block`, and never leave it unset in a rule you
+  own.
+- **Preloading everything.** A `<link rel="preload">` per file puts every
+  weight and subset ahead of the page in the network queue. Preload the one
+  file the first paint needs; the rest arrive with the stylesheet.
+
+A font that is slow — a cold cache, a throttled connection — then costs a
+swap or a fallback, never a blank page. The section below is how to make
+that swap invisible.
+
 ## Getting to 100 on a phone
 
 Fontsource's stylesheet is the right default and the wrong last mile. It

package/guides/forms.md

@@ -7,6 +7,21 @@ that handles the state for you, and a hook for when you want to hold it
 yourself. Both cover validation errors, pending state, optimistic updates and
 GET-form navigation.
 
+## The rule: uncontrolled, unless one field needs otherwise
+
+A form here is **uncontrolled by default**. Inputs keep their own value in
+the DOM, an initial value is React's `defaultValue`, and the action reads
+`FormData` on submit. No `useState` per field, no `value`/`onChange` pair,
+no re-render of the whole form on every keystroke — and after a refused
+submit the values are still there, because nothing re-rendered the inputs.
+
+Reach for a controlled field only where the UI has to react *as* the user
+types — a character count, a live preview, a dependent select — and bind
+that one field with `useField` (below), which scopes the re-render to it.
+Coming from react-hook-form this is the same default; coming from TanStack
+Form or from `useState`-per-input it is the opposite, and the difference is
+most of why these forms stay fast.
+
 ## The `<Form>` component
 
 The simplest way to handle forms. Works without any hooks — just pass a server action and use the render-prop for pending state and errors.
@@ -275,6 +290,54 @@ genuinely reloads. Then the server renders the page again, and putting the
 values back is the server's job — return them from the action and render them
 as `defaultValue`.
 
+### The schema is written for the shape it wants
+
+Every value in a `FormData` is a string or a file, and a control that is off
+is not there at all — a fact that used to leak into every schema as
+`z.coerce.number()` and a per-checkbox `.transform()`. It does not any more.
+The form is read *the way the schema means it*, on both sides:
+
+```ts
+const settings = z.object({
+  notify: z.boolean(),                 // unchecked posts nothing → false; "on" → true
+  limit: z.number().int().min(1),      // "5" → 5
+  tags: z.array(z.string()),           // one tag → ['a']; none ticked → []
+  policy: z.string().optional(),       // hidden behind a switch → absent when off
+  auth: z.discriminatedUnion('kind', [ // auth[kind] picks the branch
+    z.object({ kind: z.literal('none') }),
+    z.object({ kind: z.literal('bearer'), token: z.string().min(1) }),
+  ]),
+  rules: z.array(z.object({ on: z.boolean(), max: z.number() })),  // rules[0][on], rules[0][max]
+}).refine((s) => !s.notify || (s.policy ?? '').length > 0, {
+  path: ['policy'],
+  message: 'Say what to notify about.',
+})
+```
+
+Nothing in that schema knows it will meet a form. A schema describes itself
+(Standard JSON Schema — Zod 4 and ArkType do; Valibot not yet, and its
+values arrive as strings), and the decoder coerces to it: an absent
+`boolean` is `false`, `"on"`/`"1"` is `true`; a numeric string for a
+`number` is the number, an empty one for an optional number is absent; an
+`array` given one value is a list of one and given nothing is empty; nested
+names nest (`fields[0][name]` and `fields[0].name` alike); a union takes the
+branch its discriminator names; a control left blank is absent for a field
+the schema does not require, whatever its type — `z.email().optional()`
+accepts the empty input, an optional union is not read as its first branch
+— and is `""` for one it requires, so `z.string().min(1)` can say so. A value the schema refuses is still refused as itself — `"many"` for a
+number is the error you expect.
+
+A leaf JSON Schema cannot describe — `z.date()`, a custom check — costs only
+that leaf, which arrives as posted; the fields beside it are still read the
+way the schema means. A schema that cannot describe itself at all is said
+once, in development, with the library's reason.
+
+`<Form>` validates that object in the browser and the action decodes the
+same object on the server, from one codec, so a form that passes here passes
+there. A value sent through `<Form transform>` is encoded the same way back
+— a boolean as `"1"`/`"0"`, a nested object as `key[prop]` — and decodes to
+what was given.
+
 ### Lists of values
 
 A repeated name is an array:
@@ -405,6 +468,28 @@ and fades. It is state rather than a timer in every form that wants one,
 because the timer has to be cleared when the component goes away and that is
 the part people forget.
 
+### Nothing to save yet
+
+```tsx
+{({ dirty, reset }) => (
+  <>
+    <Button type="submit" disabled={!dirty}>Save</Button>
+    {dirty && <Button type="button" variant="ghost" onClick={reset}>Discard</Button>}
+  </>
+)}
+```
+
+`dirty` is whether anything differs from what the form started with. It is
+read from the form itself — a snapshot of its `FormData` on mount, compared
+on every input — so an uncontrolled field counts, which is the reason it is
+the form's to answer and not something a component beside it could work
+out. A successful submit makes the current values the new baseline;
+`reset()` goes back to the first one. A bound control with no native
+element behind it counts too, through the store. Only a form that reads
+`dirty` is measured, and it renders once when the value first differs — not
+on the keystrokes after — so a field that subscribes for itself keeps its
+promise of rendering alone.
+
 ### Why not a `<Field>` component
 
 TanStack Form and react-hook-form both hand you a field through a render prop —
@@ -519,6 +604,24 @@ the markup is submittable on its own. Someone who hits enter before the
 javascript arrives still reaches the server; the page reloads with the result
 instead of updating in place.
 
+What happens on the wire: React writes the action's id into the form as a
+hidden field and points the form at the page's own url, and the browser
+posts there. The host reads the fields, runs the action they name exactly as
+the enhanced path would have called it, and renders the page again with what
+it returned seated in the form that posted — so a refusal shows on its
+fields, `error('email')` and `fieldState` included, for a visitor with no
+javascript at all. A `redirect()` the action throws is followed as a
+document's would be; a cookie it sets is on the answer. Same origin only, as
+an action is, and the answer is never stored. A stored page is the one most
+likely to be submitted this way — it paints before its runtime arrives —
+which is why this is not optional.
+
+The seating is React's own `useActionState`, which `<Form>` uses under a
+wrapper bound to your action: React hands a form-state action a
+`(previousState, formData)` pair, and your action keeps taking the
+`FormData` alone. A `useActionState` of your own works the same way, with
+an action written for the pair.
+
 The two do not fight. The handler calls `preventDefault()` first, and React does
 not run a form action for a submit that was cancelled — so the enhanced path
 wins whenever there is one, and the native path is what is left when there is

package/guides/index.json

@@ -14,6 +14,11 @@
     "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": "bun",
+    "title": "Running on Bun",
+    "description": "What is different when the runtime is Bun — and what only looks like it is."
+  },
   {
     "slug": "caching",
     "title": "Asking once per request",
@@ -54,6 +59,11 @@
     "title": "Errors and 404s",
     "description": "What a visitor sees when a page throws, or asks for a url nothing answers."
   },
+  {
+    "slug": "feature-flags",
+    "title": "Feature flags",
+    "description": "Vercel's Flags SDK runs unchanged — flags/next, without Next."
+  },
   {
     "slug": "file-uploads",
     "title": "File uploads",
@@ -129,6 +139,11 @@
     "title": "Offline",
     "description": "Knowing when the server cannot be reached, and carrying on without it."
   },
+  {
+    "slug": "openapi",
+    "title": "OpenAPI",
+    "description": "A document derived from your route.ts files, and Scalar's page over it."
+  },
   {
     "slug": "ppr",
     "title": "Partial prerendering",

package/guides/installation.md

@@ -32,8 +32,9 @@ The rest of this page is for adding rsc-kit to an app you already have.
 <PackageManagers pkg="vite @vitejs/plugin-rsc @vitejs/plugin-react @types/react @types/react-dom" dev />
 
 `@rsc-kit/core` brings the Vite plugin, the render engine and the client
-runtime. React 19 and Vite 8 are peer dependencies — the versions the RSC build
-needs, not ones this package pins for you.
+runtime. React 19.2 or later and Vite 8 are peer dependencies — the versions
+the RSC build needs, not ones this package pins for you. 19.2 is where
+`useEffectEvent` arrived, which the live-data hooks are built on.
 
 <Aside type="note" title="What @vitejs/plugin-react is for">
   Fast Refresh: edit a client component and React keeps its state, instead of
@@ -62,6 +63,7 @@ export default defineConfig({
       sourceDir: "src",
       outDir: "build",
       offline: true,
+      openapi: { info: { title: 'Example API', version: '1.0.0' } },
     }),
     react(),
   ],
@@ -167,14 +169,20 @@ runs](/hosts/where-it-runs).
 {
   "type": "module",
   "scripts": {
-    "dev": "vite",
-    "build": "vite build",
+    "dev": "bun --bun vite",
+    "build": "bun --bun vite build",
     "start": "bun .output/server/index.mjs",
-    "compile": "bun build --compile .output/server/index.mjs --outfile my-app"
+    "compile": "bun --bun vite build && bun build --compile .output/server/index.mjs --outfile dist/app"
   }
 }
 ```
 
+`bun --bun` runs Vite on Bun's runtime. The `vite` bin has a Node shebang, so
+`bun run dev` alone would start the dev server, the build and the prerender
+under Node — and a project importing `bun` or `bun:sqlite` fails at the first
+render. On Node the scripts are plain `vite` and `vite build`;
+[Running on Bun](/hosts/bun) has the rest.
+
 `build` freezes every page it can, so there is no separate prerender step and
 no command for one — freezing runs the app, which needs the bundle the build
 just wrote, and only the build knows where that is. A page that must render
@@ -252,12 +260,24 @@ for before they will run.
 There is nothing to install and nothing this package adds — Vite already owns
 this. Two rules and one declaration.
 
-Anything named `VITE_*` is **inlined into the client bundle** and ships to the
-browser, whether or not a browser file reads it. Everything else stays on the
-server, read through `process.env`.
+Anything named `PUBLIC_*` (or Vite's own `VITE_*`) is **inlined into the
+client bundle** and ships to the browser, whether or not a browser file reads
+it. Everything else stays on the server, read through `process.env`.
 
 The prefix is the whole boundary, so never put a secret behind it.
-`VITE_STRIPE_KEY` is a published key.
+`PUBLIC_STRIPE_KEY` is a published key.
+
+And one line never to write into a `.env`: `NODE_ENV`. Vite sets it itself —
+`development` under `vite`, `production` under `vite build` — and honours a
+`.env` that sets it, so `NODE_ENV=development` in `.env` turns `vite build`
+into a development build: the pages compile against React's development JSX
+runtime, the server bundles carry React's production build, and every route
+fails to render with React's opaque "message omitted in production builds".
+The build refuses that up front and names the file and line, because a
+plugin cannot override it — Vite applies the `.env` value after plugins have
+run. If another tool in the repository wants the line, keep it in that
+tool's own `.env`, not the app's; the env schema still validates
+`NODE_ENV` from what the runtime sets.
 
 Declare the ones you use, and Vite types them:
 
@@ -268,7 +288,7 @@ interface ViteTypeOptions {
 }
 
 interface ImportMetaEnv {
-  readonly VITE_API_URL: string;
+  readonly PUBLIC_API_URL: string;
 }
 ```
 
@@ -280,7 +300,7 @@ interface ImportMetaEnv {
 
 #### When they are read
 
-`import.meta.env.VITE_*` is a literal in the bundle: changing one means a
+`import.meta.env.PUBLIC_*` is a literal in the bundle: changing one means a
 rebuild. `process.env.*` is a live read, so the deploy's environment wins —
 with one exception the build makes for you. A route that reads an environment
 variable and nothing request-bound is frozen at build time, value included,
@@ -302,13 +322,18 @@ import { z } from 'zod';
 
 export const env = createEnv({
   server: { DATABASE_URL: z.string().url() },
-  clientPrefix: 'VITE_',
-  client: { VITE_API_URL: z.string().url() },
+  clientPrefix: 'PUBLIC_',
+  client: { PUBLIC_API_URL: z.string().url() },
   runtimeEnv: typeof process === 'undefined' ? import.meta.env : { ...import.meta.env, ...process.env },
   emptyStringAsUndefined: true,
 });
 ```
 
+`typeof process === 'undefined'` is not decoration: a `"use client"` file
+that imports this for a `PUBLIC_` value runs where there is no `process`,
+and `{ ...process.env }` there is a `ReferenceError` before the first
+render. The scaffold's `env.ts` is written this way.
+
 Read `env.DATABASE_URL` instead of `process.env.DATABASE_URL` and three things
 follow. It is a `string`, not `string | undefined`. A server variable touched
 from a client component throws by name rather than being silently `undefined`.

package/guides/laravel.md

@@ -127,6 +127,16 @@ already use. Vite **is** the renderer in development. It writes
 Laravel does not route is handed through to the address inside it. Stop the
 dev server and the file goes with it, and so does the proxy.
 
+Per url the rule is: **if the React tree has it, React renders it**;
+otherwise Laravel does. That holds for a url Laravel also routes — a fresh
+application ships `Route::get('/', …)` to its welcome page, and after
+install `/` is `resources/js/app/page.tsx`, not the welcome page. The build
+writes its route table to `bootstrap/rsc/vite/routes.json` on every `vite`
+and `vite build`, and the package registers those urls after `routes/web.php`
+loads, so a page added to the tree is routed on the next request. The
+welcome route can stay or go; it answers nothing while the page exists.
+Until the first `vite` there is no table, and Laravel answers everything.
+
 The other direction works too. The renderer reads `APP_URL` and
 `RSC_HOST_CALL_SECRET` from the app's own `.env`, and a url the route tree does
 not own — `/login`, a Blade page, a webhook, a file under `/storage` — is
@@ -232,7 +242,21 @@ method runs, which is where `ValidationException` usually comes from.
 
 A class under `app/Rsc/Actions/` is a server action. `rsc:action-manifest`
 writes the map, and the build writes a `"use server"` module beside your pages
-exporting one function per method, named `classMethod`:
+exporting one function per method, named `classMethod`.
+
+Make one with its guards already on it:
+
+```sh
+php artisan make:rsc-action Orders --method=cancel --auth --can=update,Order --revalidate=orders
+```
+
+`--method` per call (none makes the class invokable, reached as `orders`),
+`--auth` for `#[Authenticated]`, `--can=ability` or `--can=ability,Model` for
+`#[Can]`, `--middleware=throttle:60,1` for `#[Middleware]`, `--revalidate`
+for the `Rsc::revalidate()` line, and `--rpc` to make a class for `rpc()`
+under `app/Rsc` instead. A slash nests: `Billing/Invoices`. The attributes it
+writes are the ones the registry reads, so what you asked for at the prompt
+is what runs.
 
 ```php title="app/Rsc/Actions/Orders.php"
 namespace App\Rsc\Actions;
@@ -362,7 +386,8 @@ closer to a millisecond. What matters is how many *sequential* calls a page
 needs. A page with no `middleware.ts` middleware makes no guard call; sibling
 components awaiting `rpc()` are rendered concurrently, so their calls
 overlap — and calls issued in the same tick travel as **one** request, a
-batch the package answers in one Laravel request; `cache()` dedupes
+batch the package answers in one Laravel request, one line per call as
+each finishes, so a fast read is not held behind a slow one; `cache()` dedupes
 identical calls within a request; a frozen page makes none at all and a
 shell only for its holes. A guarded page is therefore typically two Laravel
 requests — the guard, then the batch of its reads — and a host-call-heavy app

package/guides/mcp.md

@@ -18,11 +18,15 @@ The scaffold already did. Every project gets a `.mcp.json` at its root:
 ```json title=".mcp.json"
 {
   "mcpServers": {
-    "rsc-kit": { "command": "npx", "args": ["-y", "@rsc-kit/mcp"] }
+    "rsc-kit": { "command": "bunx", "args": ["@rsc-kit/mcp"] }
   }
 }
 ```
 
+On a Node project, `"command": "npx", "args": ["-y", "@rsc-kit/mcp"]` — the
+same server, launched by the runtime the project has. The scaffold writes
+whichever fits.
+
 Claude Code reads that as project-scoped configuration and asks you to approve
 it the first time it starts the server. Nothing is installed until then, and
 nothing about your build or dev server changes — it is a file an agent reads.
@@ -32,12 +36,14 @@ For a project that predates the file, `create-rsc-kit init` writes it (and
 leaves one that is already there alone), or add it by hand:
 
 ```sh
-claude mcp add rsc-kit -- npx -y @rsc-kit/mcp
+claude mcp add rsc-kit -- bunx @rsc-kit/mcp      # or: npx -y @rsc-kit/mcp
 ```
 
-Any other MCP client takes the same entry — a stdio server, command `npx`,
-arguments `-y @rsc-kit/mcp` — in its own file: `.cursor/mcp.json` under
-`mcpServers`, `.vscode/mcp.json` under `servers`.
+Any other MCP client takes the same entry — a stdio server, command `bunx`
+(or `npx`), argument `@rsc-kit/mcp` — in its own file: `.cursor/mcp.json`
+under `mcpServers`, `.vscode/mcp.json` under `servers`. If a client reports
+the server as unreachable, run the command by hand: `bunx @rsc-kit/mcp`
+waits on stdin for a client, and printing nothing is it working.
 
 ## What it answers about your app