@rsc-kit/mcp 0.16.3 → 0.18.0

package/guides/response-headers.md

@@ -87,3 +87,25 @@ jar.set('name', 'value', {
 
 Names are validated as cookie tokens and `sameSite` / `expires` are checked, so
 a typo is an error rather than a header the browser quietly ignores.
+
+## What a response says about itself
+
+Two things, and they are not the same kind:
+
+**How it was served**, always: `X-RSC-Kit: stored`, `rendered` or `shell` on
+every response — a page from a file the build wrote, a page rendered for this
+visitor, or a stored shell with its holes rendered now. It is the header a
+developer reads in the Network tab when a page is slower than expected, the
+way `X-Nextjs-Cache` is, and a CDN rule or a health check can key on it. It
+names no product, so there is nothing to strip.
+
+**What built it**, by default: `X-Powered-By: rsc-kit` on every response and
+`<meta name="generator" content="rsc-kit">` in every document — what
+BuiltWith and Wappalyzer read. The name only, never the version: a version in
+every response is what a vulnerability scanner filters on. A policy that
+strips every framework identifier turns both off, which matters for the tag,
+since a proxy can strip a header but not a line inside the HTML:
+
+```ts title="vite.config.ts"
+rscKit({ identify: false })
+```

package/guides/routing.md

@@ -303,7 +303,11 @@ A **query string** is not — the same route is asked for with `?q=shoes` and
 `?q=hats` — so there is no honest answer at build time, and `useSearchParams`
 throws rather than pretending it is empty. The dev server does the same, on
 purpose: a page has one shape, and a boundary missing in dev is the one the
-build will refuse.
+build will refuse. Under a `<Suspense>` you wrote, nothing is said. With
+nothing closer than a `loading.tsx`, dev prints one line and shows it at the
+bottom of the page: the whole segment is that fallback until the query
+arrives, and a boundary around the component that reads keeps the rest
+painted.
 
 Wrap it, and the throw becomes the fallback:
 

package/guides/seo-files.md

@@ -0,0 +1,140 @@
+# robots, sitemap and llms.txt
+
+> The files a site describes itself with, from a file beside the root layout — written the way Next writes them, stored at build when they can be.
+
+A crawler asks for `/robots.txt` and `/sitemap.xml` before it reads a page,
+and a model asks for `/llms.txt`. Each comes from a file beside the root
+layout, named for what it answers:
+
+| file | answers | returns |
+| --- | --- | --- |
+| `src/app/robots.ts` | `/robots.txt` | `MetadataRoute.Robots` |
+| `src/app/sitemap.ts` | `/sitemap.xml` | `MetadataRoute.Sitemap` |
+| `src/app/llms.ts` | `/llms.txt` | `MetadataRoute.Llms` |
+| `src/app/llms-full.ts` | `/llms-full.txt` | a string |
+
+The same names and shapes as Next, so a port copies them across unchanged.
+
+```ts title="src/app/robots.ts"
+import type { MetadataRoute } from '@rsc-kit/core/metadata';
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      { userAgent: '*', allow: '/', disallow: ['/api/', '/studio'] },
+      { userAgent: 'GPTBot', disallow: '/' },
+    ],
+    sitemap: '/sitemap.xml',
+  };
+}
+```
+
+```ts title="src/app/sitemap.ts"
+import type { MetadataRoute } from '@rsc-kit/core/metadata';
+import { db } from '@/lib/db';
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const posts = await db.post.findMany({ select: { slug: true, updatedAt: true } });
+
+  return [
+    { url: '/', changeFrequency: 'weekly', priority: 1 },
+    { url: '/pricing' },
+    ...posts.map((post) => ({ url: `/blog/${post.slug}`, lastModified: post.updatedAt })),
+  ];
+}
+```
+
+```ts title="src/app/llms.ts"
+import type { MetadataRoute } from '@rsc-kit/core/metadata';
+
+export default function llms(): MetadataRoute.Llms {
+  return {
+    title: 'Remorva',
+    summary: 'Photo restoration: damage repaired and colour restored, in about a minute.',
+    sections: [
+      { title: 'Pages', links: [{ title: 'Pricing', url: '/pricing', description: 'Per restoration, no subscription' }] },
+    ],
+  };
+}
+```
+
+A relative url in any of them is made absolute with the root layout's
+`metadataBase`; without one, a relative url is a build error that says so.
+Any of the three may return a string instead, served as written.
+
+## A sitemap you do not write
+
+With no `sitemap.ts`, the build writes `/sitemap.xml` itself, from what it
+already knows: every page it stored and every url `generateStaticParams`
+listed, each with the build as `lastModified`. Left out: anything under a
+`middleware.ts` (a guard means not for everyone), a page the build could not
+render, and the not-found page. The build's table says so:
+
+```
+○  /sitemap.xml
+   written by the build: 5 urls; a sitemap.ts beside the root layout replaces it
+```
+
+It needs the root layout's `metadataBase` for the host; without one the line
+says it was not written. A `sitemap.ts` replaces it entirely — the moment you
+want a page the build cannot see (a post per database row without
+`generateStaticParams`) or a `changeFrequency`, write one.
+
+## How fresh
+
+Three choices, and the function decides — the same rule every route follows:
+
+| you write | served | fresh |
+| --- | --- | --- |
+| nothing | the build's own sitemap, stored | every deploy |
+| a `sitemap.ts` that reads the database | stored at build | every deploy |
+| a `sitemap.ts` that awaits `connection()` | rendered per request | every crawl |
+
+```ts title="src/app/sitemap.ts"
+import { connection } from '@rsc-kit/core/request';
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  await connection(); // per request — the same mark a page uses
+
+  const posts = await db.post.findMany({ select: { slug: true, updatedAt: true } });
+
+  return posts.map((post) => ({ url: `/blog/${post.slug}`, lastModified: post.updatedAt }));
+}
+```
+
+Without the `connection()` line the same function runs once at build and the
+answer is stored; the build's table shows `○` for a stored one and `ƒ` for
+one that runs per request. Reading the database at build is fine — it is the
+request that makes a route dynamic, not the data.
+
+## How they are served
+
+Each file becomes an api route, and that decides the rest. A `sitemap.ts`
+that reads nothing per request — the database counts as nothing, the request
+does not — is answered once at build and stored, like any frozen route, and
+served from the file after. One that reads `cookies()` or awaits
+`connection()` stays dynamic and runs per request. The build's table lists
+them with the other routes and says which.
+
+They run no middleware, on purpose: a guard on the root layout's directory
+would otherwise answer a crawler's request for `robots.txt` with a 401.
+
+The urls are typed like every other route, so `route('/sitemap.xml')` is a
+link the build checks.
+
+## Files as written
+
+A hand-written file beside the root layout is served at the root as it is:
+`robots.txt`, `sitemap.xml` (or `sitemap-posts.xml`), `llms.txt`,
+`llms-full.txt`, and the others a site is asked for there — `humans.txt`,
+`security.txt`, `ads.txt`. In development they are read from `app/`; a build
+copies them beside the client output. A file and a function for the same url
+is a build error naming both.
+
+## Coming from Next
+
+`app/robots.ts` and `app/sitemap.ts` carry across unchanged. `app/llms.txt`
+in Next is usually a `route.ts`; here it is `llms.ts` with a shape, or a file
+as written. Next's `generateSitemaps()` for a sitemap split across files is
+not here: a `sitemap-posts.xml` written by hand, or a `route.ts` under
+`app/sitemap/`, covers it.

package/guides/typed-routes.md

@@ -94,6 +94,15 @@ const nav = [
 Without `satisfies`, TypeScript infers `string` for `href` and you lose the
 check.
 
+## The build checks
+
+`vite build` runs the project's typecheck before it bundles, and stops on an
+error — so a link to a route that does not exist is a failed build, not a 404
+found after deploying. It is the same `tsc --noEmit` the `check` script runs,
+on the same tsconfig, and it costs about a second. `rscKit({ typecheck: false })`
+turns it off; a project with no `tsconfig.json`, or no `typescript`
+installed, is skipped without being asked.
+
 ## If you never run the generator
 
 `.rsc-kit/rsc-routes.d.ts` is written by the build. Without it — or with a
@@ -137,3 +146,20 @@ For end-to-end types without a fetch at all, a [server action or
 query](/guides/queries/) is already typed across the boundary: the return type
 is the function's, because it is the same function.
 :::
+
+## Regions
+
+`revalidate()` in an action and `refresh()` in the browser take a region by
+name, and the names are typed to the ones the build found: every
+`section('orders', …)` and every `@slot` directory, plus `'page'` and
+`'all'`. A typo, or a section renamed since, stops compiling instead of being
+refused by the renderer at runtime:
+
+```ts
+revalidate('orders')   // a section the build found
+revalidate('order')    // does not compile
+```
+
+A name computed at runtime is cast, as an href is: `revalidate(name as
+RevalidateTarget)`. A name that reaches the renderer unknown anyway is still
+refused with the names it does know.

package/guides/view-transitions.md

@@ -17,7 +17,7 @@ badly.
 | a server action's result, put into state | yes |
 | `<Form>` — errors, success, optimistic updates | yes |
 | a streamed `<Suspense>` boundary arriving | yes, React does this on its own |
-| navigating to another page | yes, behind a flag |
+| navigating to another page | yes — the update carries a transition type |
 
 ## What works
 
@@ -62,15 +62,61 @@ throughout, so everything it drives animates the same way.
 
 ## Navigating between pages
 
-Off by default, because it changes how every navigation commits:
+A navigation replaces the segment inside `startTransition`, so a
+`<ViewTransition>` around it animates like any other. What you cannot tell
+from outside is a navigation from the first commit after hydration — the
+boundary taking over the server-rendered page, which animated would be the
+page fading into itself on every load. So a navigation's update carries the
+transition type `rsc-navigation`, and that first commit does not. Key the
+boundary on it:
 
-```ts title="vite.config.ts"
-rscKit({ viewTransitions: true })
+```tsx title="src/app/layout.tsx"
+import { ViewTransition } from 'react';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body className="min-h-full flex flex-col">
+        <ViewTransition default={{ 'rsc-navigation': 'page', default: 'none' }}>
+          <div className="flex flex-1 flex-col">{children}</div>
+        </ViewTransition>
+      </body>
+    </html>
+  );
+}
+```
+
+That is a server component, and it can be: `ViewTransition` is a built-in like
+`Suspense`, which the payload carries as a symbol. No `'use client'` file is
+needed for it.
+
+`default: 'none'` is what makes a first load or a reload never animate. The
+`<div>` matters (here it also carries the body's flex layout, so a `<main>`
+inside still fills the height): React names each top-level element under a boundary and
+animates every one on its own, so a page of five sections becomes five groups,
+each morphing from where it was to where it is now. One wrapper element is one
+snapshot pair — the old page and the new one dissolving into each other, the
+way Inertia's does. A navbar inside the pair cross-fades into itself, which is
+invisible; put the boundary around `<main>` in a nested layout instead when
+you want the navbar left out of it entirely. Leave the wrapper out when you
+want the per-element movement instead.
+
+### Shaping the animation
+
+The pair carries the class you chose, so your CSS shapes it there. The
+browser's default is a 250 ms cross-fade:
+
+```css title="src/app/styles.css"
+/* Shorter, or none at all — the instant swap Inertia does by default. */
+::view-transition-old(.page),
+::view-transition-new(.page) {
+  animation-duration: 120ms;
+}
 ```
 
-A build-time constant rather than a runtime setting, so an app that does not
-ask for it does not carry the boundary at all. What it animates is the segment
-a navigation replaces; what a page does inside itself needs no flag.
+`animation: none` on both is the instant swap, with the transition still in
+place for the shared elements you name yourself (`<ViewTransition name="hero">`
+still morphs).
 
 ## Coming back to a page you were just on
 

package/guides/where-it-runs.md

@@ -0,0 +1,155 @@
+# Where it runs
+
+> A host is a Nitro preset, not a server you write.
+
+There used to be a page here for each runtime, and a server file generated to
+match. There is no server file now, and no choice about it either:
+[Nitro](https://nitro.build) builds the server around the route tree, and
+choosing where an app runs is choosing a preset.
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite';
+import { nitro } from 'nitro/vite';
+import react from '@vitejs/plugin-react';
+import { rscKit } from '@rsc-kit/core/vite';
+
+export default defineConfig({
+  plugins: [
+    nitro({ preset: 'bun', serveStatic: 'inline' }),
+    rscKit(),
+    react(),
+  ],
+});
+```
+
+`bun create rsc-kit@latest my-app` writes that for you. Changing where it deploys is
+changing the one string.
+
+## The presets
+
+`rsc-kit` asks about three, because those are the ones it can check for you.
+Nitro carries [many more](https://nitro.build/deploy) and they need nothing from
+this package — a preset is a string, not an integration.
+
+| `--host` | preset | what you get |
+| --- | --- | --- |
+| `bun` | `bun` | `.output/server/index.mjs`, and `bun run compile` for a single binary |
+| `node` | `node` | `.output/server/index.mjs`, run with `node` |
+| `worker` | `cloudflare_module` | a Worker, plus the `wrangler.json` and `_headers` Nitro generates |
+
+Everything else — Vercel, Netlify, Azure, Deno, AWS Amplify — is the same
+change:
+
+```ts
+nitro({ preset: 'vercel', serveStatic: 'inline' })
+```
+
+## Running it
+
+```bash
+npm run dev      # vite is the renderer; nothing is prebuilt
+npm run build    # writes .output/
+npm run start    # runs .output/server/index.mjs
+```
+
+A Worker has no `start`, because it is deployed rather than started:
+
+```bash
+npm run preview  # wrangler dev, on workerd
+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:
+
+```bash
+npm run compile   # builds, then bun build --compile
+./dist/app
+```
+
+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
+write.
+
+<Aside type="note" title="A Worker serves the frozen pages from a module">
+  A Worker has no filesystem, so the directory the build writes is not there
+  at request time. The build also writes the same pages as one module beside
+  the bundle, `rsc-static-inline.mjs`, which wrangler uploads with the rest
+  and the server imports when the directory is missing. Nothing to configure;
+  it is why `○` on a Worker means the stored page and not a live render that
+  happens to be the same. It counts toward the Worker's script size, which is
+  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
+  filesystem — where the files on disk are not — and the failure is
+  `ENOENT: /$bunfs/public/assets/…` with the pages themselves looking fine.
+
+  The generated config sets it. If you write your own, set it too.
+</Aside>
+
+## Offline
+
+`rscKit({ offline: true })` writes a service worker into `.output/public`
+alongside the assets, so a page someone has visited survives a reload with no
+network. Off by default, and covered in [Offline](/guides/offline#surviving-without-one).
+
+## Why `nitro` is pinned
+
+The generated `package.json` pins an exact version rather than a range:
+
+```json
+"nitro": "3.0.260903-beta"
+```
+
+Nitro's own `latest` tag is a dated prerelease, and it sorts **above** the plain
+`3.0.0` on npm. So `^3.0.0` resolves to the older release, which builds without
+complaint and then answers 404 to every route. TanStack Start pins a dated beta
+for the same reason.
+
+## Assets are Nitro's
+
+The build writes browser assets to `.output/public`, and Nitro serves them from
+its own root. There is no `assetsDir` or `assetsUrl` to set: both were removed,
+and `rscKit()` refuses a config that still passes them rather than reading a
+prefix and ignoring it.
+
+The alternative was the silent version — the markup asks for the app's prefix,
+Nitro answers at its own, and the page arrives unstyled and never hydrates with
+nothing logged anywhere.
+
+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.
+
+---
+
+Next: [Deploying →](/hosts/deployment)
+
+## Which entry point is whose
+
+`@rsc-kit/core/host` is the engine's front door for a **host adapter** — the
+handler, and beside it the few functions an adapter needs when it embeds the
+engine. Several of those are re-exports of app-facing modules, so an editor's
+auto-import may offer `redirect` or `revalidate` from `host`. They are the
+same functions; an app imports them from their own entry points:
+
+| in an app | not |
+| --- | --- |
+| `@rsc-kit/core/redirect` | `@rsc-kit/core/host` |
+| `@rsc-kit/core/revalidate` | `@rsc-kit/core/host` |
+
+Only an adapter imports `host`. The re-exports there are marked internal, so
+they sort below the app entry in a completion list.