@rsc-kit/mcp 0.17.0 → 0.18.0

package/guides/queries.md

@@ -35,7 +35,7 @@ id from an action id — only `fetchQuery` sends a GET.
 
 ```tsx
 getListings(kind)                  // POST, even though it is a query
-fetchQuery(getListings, [kind])    // GET
+fetchQuery(getListings, [kind])    // GET, and [kind] is typed from getListings
 ```
 
 Development warns from the server when a query arrives at the action endpoint,
@@ -110,11 +110,43 @@ response, with no request from the browser. Nothing in this package is involved;
 `use()` is React's. Reach for this first.
 
 **When the browser decides what to read** — a filter, another page, a refresh —
-hand `fetchQuery` to your cache library:
+call it. `fetchQuery` is an async function that goes to the server and gives
+back the typed answer; nothing else is required:
 
 ```tsx
-import { fetchQuery } from "@rsc-kit/core/queryClient"
+'use client'
 
+import { useState, useTransition } from 'react'
+import { fetchQuery } from '@rsc-kit/core/queryClient'
+import { getListings } from '@/queries'
+
+export function Listings({ initial }: { initial: Listing[] }) {
+  const [listings, setListings] = useState(initial)   // the server-rendered page one
+  const [pending, start] = useTransition()
+
+  const show = (kind: string) =>
+    start(async () => setListings(await fetchQuery(getListings, [kind])))
+
+  return (
+    <>
+      <button onClick={() => show('stay')} disabled={pending}>Stays</button>
+      <button onClick={() => show('rent')} disabled={pending}>Rentals</button>
+      <List listings={listings} />
+    </>
+  )
+}
+```
+
+That is the whole pattern: an event handler, `await fetchQuery(...)`, a
+`setState`. `useTransition` keeps the old list on screen while the new one
+loads and gives you `pending` for the button. The same call works in a
+`useEffect`, in an `onSubmit`, anywhere in the browser.
+
+**When you want caching**, hand the same call to the library that will hold
+the answer. `fetchQuery` goes to the server every time; staleness,
+revalidation and deduplication belong to the library, not to the fetcher:
+
+```tsx
 // TanStack Query
 useQuery({
   queryKey: ["listings", kind],
@@ -125,10 +157,6 @@ useQuery({
 useSWR(["listings", kind], () => fetchQuery(getListings, [kind]))
 ```
 
-`fetchQuery` goes to the server every time. That is what a fetcher needs:
-staleness, revalidation and deduplication belong to the library holding the
-answer, not to the thing that fetches it.
-
 :::caution[Keep the arrow]
 TanStack calls a bare `queryFn` with its own context — `{ client, queryKey,
 meta, signal }` — and a server function serialises whatever it is handed, so
@@ -152,7 +180,7 @@ useInfiniteQuery({
 })
 
 // Data that changes while you watch. No live connection needed.
-useQuery({ queryKey: ["seats"], queryFn: () => fetchQuery(getSeats, []), refetchInterval: 2_000 })
+useQuery({ queryKey: ["seats"], queryFn: () => fetchQuery(getSeats), refetchInterval: 2_000 })
 ```
 
 Page one comes from a server component and costs no request; later pages are
@@ -166,6 +194,95 @@ trip you seeded to avoid happens anyway. SWR's `fallbackData` has the same
 shape of caveat, and `refetchInterval` pauses while the tab is hidden.
 :::
 
+### Live data
+
+A value that keeps changing while someone watches is not what `query()` is —
+a query answers once and is cacheable — but a query is the natural thing to
+read *again*:
+
+```tsx
+import { usePolling } from '@rsc-kit/core/usePolling'
+
+const { data: seats } = usePolling(() => fetchQuery(getSeats), { every: 2_000 })
+```
+
+It reuses what you already wrote, needs no special route, and goes through the
+query's `Cache-Control` — a thousand tabs polling the same seat count become
+one origin request per interval at the CDN. It pauses while the tab is hidden
+and never overlaps two reads.
+
+**Until it settles.** A job that is queued, then running, then done wants
+polling that stops on its own. `until` says when a read is the last one, and
+`onSettled` fires once, on that read. The result is the data, and what to do
+when it settles is the page's to decide — so the same primitive serves two
+pages that want different things:
+
+```tsx
+// A list of jobs, server-rendered, some still running: poll those until they
+// settle, then re-render the card through the server path that built it.
+usePolling(() => fetchQuery(jobStatus, [id]), {
+  every: 2_000,
+  enabled: !isTerminal(job),
+  until: isTerminal,
+  onSettled: () => refresh('page'),
+})
+
+// The page that started the job and owns its state machine: the value in
+// hand, and the terminal state driving the next step.
+const { data, status } = usePolling(() => fetchQuery(jobStatus, [id]), {
+  every: 1_500,
+  until: isTerminal,
+  onSettled: (final) => dispatch({ type: final.status }),
+})
+```
+
+Settled means stopped: nothing is read again until `refresh()`, which starts
+it over, or the inputs change. A page that has to survive a reload keeps the
+job's id where it likes and passes it back in; the hook starts polling the
+moment it mounts with one.
+
+**No library needed.** `data` is state; a component that only wants to show
+the value reads it. When the value already lives somewhere, `onData` hands
+every answer to it — a `useState`, a reducer, or a cache library — so that
+stays the source of truth:
+
+```tsx
+const [seats, setSeats] = useState(initial)
+usePolling(() => fetchQuery(getSeats), { every: 2_000, onData: setSeats })            // useState
+
+usePolling(() => fetchQuery(getSeats), {
+  every: 2_000,
+  onData: (s) => queryClient.setQueryData(['seats'], s),                                 // TanStack
+})
+```
+
+Neither hook needs a cache library; TanStack and SWR are shown because a page
+that already uses one should keep it as the one place the value lives.
+
+A read that fails does not stop the polling — the next interval reads again —
+and it reaches you two ways: `error` is the state, and `onError` fires per
+failed read, for a toast or a log, so a page that keeps its own state does not
+have to watch `error` in an effect:
+
+```tsx
+usePolling(() => fetchQuery(getSeats), {
+  every: 2_000,
+  onData: setSeats,
+  onError: (e, { failures }) => {
+    if (failures === 3) toast.error('Could not refresh seats')
+  },
+})
+```
+
+`failures` counts the failed reads in a row and a success resets it, so the
+third failure can be a toast where the first was a blip, without the page
+keeping a counter of its own.
+
+**When something can push**, the server sends events instead and the browser
+holds one connection per tab. That is a route, not a query:
+[a route that streams](/guides/api-routes/#a-route-that-streams). The trade-off
+is stated there.
+
 ### Where it will not work
 
 `fetchQuery` only works in the browser. React refuses a server-function call
@@ -310,6 +427,19 @@ and development warns when it happens.
 
 ## Caching
 
+There is no cache in `fetchQuery`, and there will not be one: a client cache
+is where "small and ours" goes wrong — a `Map` first, then staleness, then
+invalidation, then dedupe across components, and it ends as a worse TanStack
+Query that every guide has to teach. What this package owns is the part a
+library cannot: whether the answer is cacheable *at all*, which is an HTTP
+question. So the choice is a ladder, and most reads stop on the first rung:
+
+| you need | use |
+| --- | --- |
+| the value, now | `fetchQuery` in a handler and `setState` — every call goes to the server |
+| the answer to survive a reload, or a CDN to serve it | `cache` on the query, below — the browser and the CDN hold it, with no code in the page |
+| staleness, background refresh, optimistic updates, one value shared across components | TanStack Query or SWR, with `fetchQuery` as the fetcher |
+
 Answers default to `private, no-store`. A query may read the session, and a
 cacheable answer to a personal read is how one visitor is served another's data.
 

package/guides/quick-start.md

@@ -14,6 +14,37 @@ That is it. You get a page, a layout, a client component and a Vite config,
 wired together and running. There is no server file — Nitro builds one from the
 preset in that config when you build.
 
+It asks a few questions, each with a flag for a script: where it runs, the
+React Compiler, Tailwind, oxlint, and which **validation library** you want —
+Zod, Valibot or ArkType. That one is asked once because everything schema-shaped
+hangs off it: a form's schema, `action.input()`, a page's `searchParams`, and
+**typed environment variables**, which it offers next. Say yes and you get
+`src/env.ts`:
+
+```ts title="src/env.ts"
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    // DATABASE_URL: z.url(),
+  },
+  clientPrefix: 'PUBLIC_',
+  client: {},
+  runtimeEnv: { ...process.env, ...import.meta.env },
+  emptyStringAsUndefined: true,
+})
+```
+
+A missing or malformed variable is refused at startup with its name, not as an
+`undefined` three calls later; `env.DATABASE_URL` is typed everywhere it is
+read; and a server variable can never reach the browser — a browser-readable
+one has to start with `PUBLIC_`. That is [`@t3-oss/env-core`](https://env.t3.gg),
+with the schema in whichever library you chose. `.env.example` is written
+beside it and is the one that gets committed.
+
+```sh
+bun create rsc-kit@latest my-app --validation=valibot --env   # scripted
+```
+
 When you are ready to ship:
 
 ```sh

package/guides/redirects.md

@@ -26,6 +26,20 @@ the layouts you are inside stay mounted, and only the part below them changes.
 The url that redirected replaces its history entry rather than adding one, so
 Back does not land on it and redirect you again.
 
+## With a query string
+
+`search` is typed to the destination page's own `searchParams` schema, the
+same check `Link` puts on its `search` prop — a key the page never reads, or
+a number written as text, does not compile:
+
+```ts
+redirect('/', { search: { auth: true } });         // → /?auth=true
+redirect('/search', { search: { q, page: 2 } });   // checked against /search's schema
+redirect('/old', { status: 308 });                 // a permanent one
+```
+
+A bare second argument is still the status: `redirect('/old', 308)`.
+
 ## Where you call it matters
 
 This is the part worth understanding, because it is also the security-relevant

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/seo-files.md

@@ -62,6 +62,51 @@ 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`

package/guides/typed-routes.md

@@ -146,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/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.