@rsc-kit/mcp 0.17.0 → 0.18.1

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,16 @@
     "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": "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",
@@ -24,6 +34,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 +79,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 +94,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 +228,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

@@ -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
@@ -47,6 +48,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 +66,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)),
+    },
+  },
 });
 ```
 
@@ -159,14 +168,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
@@ -210,15 +225,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 +246,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
@@ -240,6 +266,18 @@ 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.
 
+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:
 
 ```ts title="src/env.d.ts"

package/guides/instrumentation.md

@@ -0,0 +1,91 @@
+# Startup
+
+> instrumentation.ts runs once, before anything else.
+
+Some setup belongs to the process, not to a page: validating the
+environment, configuring a shared package, warming a connection. Put it in
+`src/instrumentation.ts` and it runs once — before any page module
+evaluates, and before the first request.
+
+```ts title="src/instrumentation.ts"
+// Runs at import, before any page: a bad variable stops the server here.
+import './env'
+
+// Anything asynchronous the app needs before it serves. The first render
+// waits for it.
+export async function register() {
+  await db.connect()
+}
+```
+
+The name is Next's, so a reader arriving from there knows what it is. Both
+halves are optional: a file with only imports is a bootstrap, a file with
+only `register()` is a hook.
+
+## Why it is a framework file
+
+Two things make this a file the framework has to know about rather than a
+module the app imports.
+
+**Import order.** A page that configures a shared package at import time —
+a logger, an ORM, a metrics client — runs before any module the app could
+put in front of it, because the generated entry imports the pages. The entry
+imports `instrumentation.ts` *first*, so whatever it sets up is set up when
+the first page module evaluates. Importing a bootstrap module from every
+file that needs it works until someone forgets, and the failure is a page
+that throws "not configured" for the one visitor who reached it first.
+
+**Before the first request.** `register()` is awaited by every entry point
+a render can come through — the built server, the dev server, the
+prerender, a route's middleware check, a server action, an api route — so
+"before the first render" holds without the app knowing the list.
+
+## When it runs
+
+| where | when |
+| --- | --- |
+| a server (`bun`, `node`, any long-lived preset) | at startup, before the server reports itself up |
+| a Worker | at the isolate's first request — there is no startup, and a binding is only readable once a request has arrived |
+| `vite dev` | when the dev server first evaluates the app, and again when the file or anything it imports changes |
+| `vite build` | before the first page is prerendered |
+
+Once per process. A `register()` that resolved is not called again; one
+that rejected is retried by the next request, so a database that was not up
+yet is asked again rather than leaving the process permanently refusing.
+
+On a server, a failure at startup — the file throwing at import, or
+`register()` rejecting — is reported and the process exits. A server that
+could not bootstrap has nothing correct to serve, and a health check that
+passed on a server about to fail its first visitor is worse than one that
+never passed. The dev server stays up and reports the error on the page.
+
+## Environment validation
+
+The scaffold writes this file when the project validates its environment,
+and the only line it needs is the import: `src/env.ts` refuses at import, and
+importing it here is what makes a missing variable the server's failure at
+startup rather than a visitor's three calls later.
+
+The build prerenders pages, so it runs the bootstrap too. A build machine
+without the production variables sets `SKIP_ENV_VALIDATION=1`, which the
+generated schema honours; the server that runs the build validates at
+startup regardless.
+
+## On a Worker
+
+Read bindings inside `register()`, not at the top of the module. A Worker
+evaluates the module before any request exists, and `process.env` is empty
+until Nitro maps the first request's bindings onto it — so a top-level
+`process.env.DATABASE_URL` is `undefined` at exactly the moment it looks
+like it should not be. Inside `register()`, which runs at the first request,
+it is there.
+
+```ts
+export async function register() {
+  const url = process.env.DATABASE_URL   // readable here on every host
+  await db.connect(url)
+}
+```
+
+The same file works unchanged on a server, where both moments have the
+environment.

package/guides/introduction.md

@@ -96,6 +96,10 @@ Swap the preset for `node`, `cloudflare_module`, `vercel`, `netlify` or `deno`
 and the same app deploys there instead. The build produces a `.output`
 directory; nothing else changes.
 
+With a backend behind it — Laravel, Go, anything answering one endpoint — the
+app is a **BAP**, [Backend-Answered Pages](/hosts/backend-answered-pages):
+the page is rendered in front of the backend rather than by it.
+
 ## What it is not
 
 <Aside type="note" title="No data layer, no CSS pipeline, no dev server of its own">