@rsc-kit/mcp 0.14.0 → 0.15.0

package/guides/queries.md

@@ -0,0 +1,340 @@
+# Queries
+
+> Reading from the server over GET, and letting TanStack Query or SWR own everything above it.
+
+`query()` marks a server function as a read, so the call goes out as a GET
+instead of a POST. Your logs and rate limiters can then tell it apart from a
+mutation, and a cache can hold the answer.
+
+```ts title="src/listings.ts"
+"use server"
+
+import { query } from "@rsc-kit/core/query"
+
+export const getListings = query(async (kind: string) => {
+  return db.listings.where({ kind })
+})
+```
+
+That is the whole feature. There is no cache here, no batching and no
+deduplication: [TanStack Query](https://tanstack.com/query) and
+[SWR](https://swr.vercel.app) already do those and do them better. **This owns
+the transport; they own everything above it.**
+
+You still need `"use server"`, and it is not claiming your function mutates.
+Despite the name it means *this may be called from the browser* — it is what
+gives the function an id and the client a stub to call it through.
+
+Two markers, two jobs. `"use server"` says the function crosses the boundary.
+`query()` says it is a read.
+
+:::caution[The call site picks the method]
+`query()` permits the GET; it does not force it. Calling the function directly
+from a client component is still a POST, because the browser cannot tell a query
+id from an action id — only `fetchQuery` sends a GET.
+
+```tsx
+getListings(kind)                  // POST, even though it is a query
+fetchQuery(getListings, [kind])    // GET
+```
+
+Development warns from the server when a query arrives at the action endpoint,
+so a forgotten `fetchQuery` shows up rather than quietly costing you the method.
+:::
+
+## What it changes
+
+Only the method. Same types, same arguments, same lack of an endpoint to write.
+
+Three things follow from that:
+
+- **Access logs and rate limiters** stop counting your reads as mutations. A
+  limiter that allows 10 writes a minute should not be spending them on a list
+  being refreshed.
+- **A GET is the only shape a cache can keep.** A browser cache, a CDN or a
+  service worker can hold one; a POST can never be held by any of them.
+- **Repeating it is safe by contract**, which is what a prefetcher, a crawler
+  or a retrying proxy assumes when it sees a GET.
+
+TanStack Start makes the same choice from the other side: its `createServerFn()`
+is a GET unless you ask for `{ method: 'POST' }`. We cannot default it that way
+— React gives us one directive for everything, so a GET default would send
+mutations as GET too.
+
+### If you skip it
+
+A plain server action still works as a cache library's fetcher, and nothing
+breaks:
+
+```tsx
+useQuery({ queryKey: ["listings", kind], queryFn: () => getListings(kind) })
+```
+
+You lose the three things above and keep everything else. So this is a
+reasonable place to start, and `query()` is the thing to reach for once a read
+is worth being precise about — anything hot enough to show up in a rate limiter,
+or public enough to be worth caching.
+
+One caveat on the second: data that is the same for everyone usually wants
+[prerendering](/guides/static-generation/) rather than a client read at all, and
+a personal read answers `no-store` and is not cached either way. The caching win
+is real, and narrower than it sounds.
+
+## Reading it
+
+**In a server component, call it.** It is ordinary server code — no HTTP, no
+cache, no client involved:
+
+```tsx
+const listings = await getListings("stay")
+```
+
+**Better still, do not await it.** Pass the promise down and let a client
+component resolve it, and the data streams with the page:
+
+```tsx
+export default function Page() {
+  const listings = getListings("stay")
+
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <List listings={listings} />   {/* "use client": use(listings) */}
+    </Suspense>
+  )
+}
+```
+
+React serialises the promise as a pending row in the payload, so the shell
+paints at once and the rows arrive when the query answers — in the same
+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:
+
+```tsx
+import { fetchQuery } from "@rsc-kit/core/queryClient"
+
+// TanStack Query
+useQuery({
+  queryKey: ["listings", kind],
+  queryFn: () => fetchQuery(getListings, [kind]),
+})
+
+// SWR
+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
+passing one unwrapped would try to put an `AbortSignal` on the wire. The arrow
+is where you choose what travels.
+:::
+
+### Paging, polling, and the rest
+
+All of it belongs to the library, and all of it works:
+
+```tsx
+// Infinite. The cursor is just an argument.
+useInfiniteQuery({
+  queryKey: ["feed"],
+  queryFn: ({ pageParam }) => fetchQuery(getFeed, [pageParam]),
+  initialPageParam: null,
+  getNextPageParam: (last) => last.nextCursor,
+  initialData: { pages: [first], pageParams: [null] },
+  staleTime: 60_000,
+})
+
+// Data that changes while you watch. No live connection needed.
+useQuery({ queryKey: ["seats"], queryFn: () => fetchQuery(getSeats, []), refetchInterval: 2_000 })
+```
+
+Page one comes from a server component and costs no request; later pages are
+ordinary reads. `/infinite`, `/pagination` and `/polling` in the example app are
+these three patterns end to end.
+
+:::caution[A seed is stale by default]
+TanStack treats `initialData` as stale at its default `staleTime` of `0`, so
+without an explicit `staleTime` it refetches page one on mount and the round
+trip you seeded to avoid happens anyway. SWR's `fallbackData` has the same
+shape of caveat, and `refetchInterval` pauses while the tab is hidden.
+:::
+
+### Where it will not work
+
+`fetchQuery` only works in the browser. React refuses a server-function call
+during the first render, so a component that also renders on the server must not
+call it there.
+
+You will not hit this through TanStack or SWR — they fetch in an effect, after
+hydration.
+
+## Sharing a check across reads
+
+A query has no middleware above it, so each one checks for itself. If that means
+writing the same check in every file, put it on the client you already use for
+actions:
+
+```ts title="src/server/client.ts"
+'use server'
+
+import { createActionClient } from '@rsc-kit/core/action'
+
+export const client = createActionClient({ onError: report })
+  .use(async ({ next }) => {
+    const user = await currentUser()
+
+    if (!user) throw new Error('Not signed in')
+
+    return next({ ctx: { user } })
+  })
+```
+
+```ts title="src/server/posts.ts"
+'use server'
+
+import { client } from './client'
+
+export const createPost = client.input(schema).handler(async ({ input, ctx }) => …)  // POST
+export const getPosts   = client.input(filter).query(async ({ input, ctx }) => …)    // GET
+```
+
+One client, one set of middleware, one `onError`. `.handler()` makes an action;
+`.query()` makes a query. Neither can be added without the check.
+
+### They fail differently, on purpose
+
+An action **returns** its failures, because React strips a thrown message in
+production. A query **throws** — every cache library reports failure by
+rejection, and one that answered with an error-shaped object would look like a
+successful read of something odd.
+
+So a refused read rejects with a real `Error`. A validation failure keeps its
+fields:
+
+```tsx
+const { error } = useQuery({ queryKey: ['posts'], queryFn: () => fetchQuery(getPosts, [filter]) })
+
+error.message   // 'Validation failed'
+error.errors    // { title: ['too short'] }
+```
+
+## Securing a query
+
+A query is a public GET endpoint. Treat it as one.
+
+### Route middleware does not run
+
+`middleware.ts` guards a **route**, and a query has no route — it is reachable
+whoever is asking and whatever page they came from. A query behind a guarded
+page is not guarded.
+
+What you do get is the request: the visitor's cookies and session are bound for
+the call, so a query can check for itself.
+
+One query is fine written by hand:
+
+```ts
+export const getOrders = query(async () => {
+  const user = await currentUser()
+
+  if (!user) throw new Error("Not signed in")
+
+  return db.orders.forUser(user.id)
+})
+```
+
+Twenty is twenty chances to forget, and the one you forget is the one that
+matters. Put the check on the client you already use for actions and build
+every read from it:
+
+```ts title="src/server/orders.ts"
+'use server'
+
+import { client } from './client'
+
+export const getOrders = client.query(async ({ ctx }) => db.orders.forUser(ctx.user.id))
+```
+
+`ctx.user` is typed and non-null because the only way into the handler was
+through the middleware that put it there — so a query **cannot be added without
+the check**. Same client, same middleware, same `onError` as your actions;
+`.handler()` makes a mutation and `.query()` makes a read. See
+[sharing a check across reads](#sharing-a-check-across-reads) below.
+
+Authorise on **identity, not arguments**. `getOrder(id)` that trusts the id is
+the whole of an IDOR: the caller chooses the id.
+
+### Only `query()` is reachable
+
+The endpoint refuses anything that is not a query, which is what keeps every
+action you have registered off a GET url. So export the wrapped value, not the
+bare function beside it.
+
+An unknown id and a real-but-unmarked one get the same 404. Telling them apart
+would let someone probe for your action ids.
+
+### A query must never write
+
+It is a GET. A prefetcher, a crawler or a retry will repeat it.
+
+### What the endpoint does for you
+
+- **Requires `X-RSC-Query`.** A GET with no unusual header is a *simple*
+  request, so any page anywhere could trigger one with
+  `<img src="…/_rsc/query?…">` and it would carry the visitor's cookies — CORS
+  stops them reading the answer, not the read running. That header is not
+  CORS-safelisted, so a browser preflights it and nothing here answers a
+  preflight. It is the same protection a POST carrying `X-RSC-Action` had.
+- Refuses a cross-origin request when an `Origin` is present.
+- Refuses an oversized url with `414` before decoding anything.
+- Sends `Vary: Cookie`, so a cacheable answer is never shared between visitors.
+
+None of that authorises anything. The query does that.
+
+### Arguments are public
+
+They travel in the url, so they reach access logs, browser history and referrer
+headers. Never take a token or a password reset code as a query argument — that
+is an action.
+
+Arguments too large for a url, or containing a `File`, make the read fall back
+to a POST rather than failing. It still works; it simply stops being cacheable,
+and development warns when it happens.
+
+## Caching
+
+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.
+
+```ts
+export const getPricing = query(async () => tiers(), { cache: "public", maxAge: 300 })
+```
+
+### You probably do not need to change it
+
+There are two caches and they solve different problems.
+
+**Your cache library's**, in memory and per tab, decides whether to ask again.
+It needs nothing from this option — `no-store` does not stop TanStack or SWR
+holding an answer, because they are not an HTTP cache.
+
+**The HTTP one**, which `cache` controls, decides whether an answer survives a
+reload, works offline, or can be shared by a CDN.
+
+Most apps want only the first. And note that data which is the same for everyone
+usually wants [prerendering](/guides/static-generation/) rather than a client
+read at all — which is a better answer than any cache. For a personal read you
+want across reloads, persist your cache library rather than widening the read.
+
+## During a build
+
+A query is an ordinary function, so it follows the ordinary rule. One reading a
+database the build machine can reach runs at build time and the page is frozen
+with real data in it. Call `connection()` inside the query to opt out.

package/guides/react-compiler.md

@@ -0,0 +1,153 @@
+# React Compiler
+
+> Enabling the compiler in the build.
+
+The React Compiler memoises client components for you, so `useMemo`,
+`useCallback` and `React.memo` mostly stop being things you write.
+
+Nothing here special-cases it. The build runs your project's own Vite config,
+so the compiler is enabled the way it is in any Vite app — by adding
+`@vitejs/plugin-react` after `rscKit()` and turning it on there.
+
+<Aside type="note" title="Order matters">
+  `rscKit()` includes `@vitejs/plugin-rsc`, which has to see modules before
+  any React layer transforms them. The React plugin goes **after** it.
+</Aside>
+
+## Two ways to run it
+
+The compiler has a native implementation and a Babel one. Both produce the same
+transform; they differ in what they cost to run and how settled they are.
+
+### Native, through oxc
+
+The faster path, and the least to install. `compiler: true` is
+[experimental](https://react.dev/learn/react-compiler/installation) and needs
+`oxc-transform-react` present — the plugin looks for it by name:
+
+<PackageManagers pkg="@vitejs/plugin-react oxc-transform-react" dev />
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { rscKit } from '@rsc-kit/core/vite';
+
+export default defineConfig({
+  plugins: [
+    rscKit({ sourceDir: 'src' }),
+    react({ compiler: true }),
+  ],
+});
+```
+
+Pass an object instead of `true` to configure it.
+
+### Babel
+
+The reference implementation. In `@vitejs/plugin-react` 6 the inline `babel`
+option was removed, so the preset is applied through `@rolldown/plugin-babel`:
+
+<PackageManagers pkg="@vitejs/plugin-react @rolldown/plugin-babel babel-plugin-react-compiler" dev />
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
+import babel from '@rolldown/plugin-babel';
+import { rscKit } from '@rsc-kit/core/vite';
+
+export default defineConfig({
+  plugins: [
+    rscKit({ sourceDir: 'src' }),
+    react(),
+    babel({ presets: [reactCompilerPreset()] }),
+  ],
+});
+```
+
+On `@vitejs/plugin-react` 5 and earlier, the inline option still exists:
+
+```ts
+react({
+  babel: { plugins: ['babel-plugin-react-compiler'] },
+})
+```
+
+## Checks worth running first
+
+The compiler only memoises components it can prove are safe to memoise, and it
+skips the rest silently. These are how you find out which is which, and they
+are worth running **before** you turn it on rather than after.
+
+**Type checking.** The compiler assumes your code means what its types say. Run
+`tsc --noEmit` and fix what it reports first — an untyped `any` threading
+through a component is exactly the shape the compiler has to give up on.
+
+```bash
+tsc --noEmit
+```
+
+**The health check.** Reports how many components in your codebase the compiler
+can handle, and why the others are refused:
+
+```bash
+npx react-compiler-healthcheck
+```
+
+**The lint rule.** `eslint-plugin-react-hooks` includes the compiler's own
+diagnostics — the Rules of React violations that make a component
+uncompilable — so they surface as you write rather than as silence in the
+build:
+
+```js title="eslint.config.js"
+import reactHooks from 'eslint-plugin-react-hooks';
+
+export default [reactHooks.configs.recommended];
+```
+
+**StrictMode.** The compiler's assumptions are the Rules of React, and
+StrictMode is what surfaces breaking them at runtime — double-invoked renders
+catch the impure ones.
+
+<Aside type="tip" title="It applies to client components">
+  Server components render once and are thrown away, so there is nothing to
+  memoise in them. The compiler earns its keep in the `"use client"` half of
+  the app.
+</Aside>
+
+## Confirming it ran
+
+The compiler leaves a cache array at the top of every component it compiled.
+Build without minification and look for it:
+
+```js
+function Counter() {
+  const $ = _c(10);                                    // ← compiled
+  const [count, setCount] = useState(0);
+
+  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+    // …
+  }
+}
+```
+
+No `_c(...)` and no `memo_cache_sentinel` means that component was skipped —
+which the health check will explain.
+
+## Opting a component out
+
+```tsx
+"use client";
+
+export default function LegacyWidget() {
+  "use no memo";
+
+  return <div>…</div>;
+}
+```
+
+## Turning it off
+
+Drop `compiler: true`, or remove the plugin. Neither the router nor the build
+depends on it being there.
+
+Further reading: [React Compiler installation](https://react.dev/learn/react-compiler/installation).

package/guides/redirects.md

@@ -0,0 +1,143 @@
+# Redirects
+
+> Leaving a page from inside the render, and what that costs.
+
+```tsx title="src/app/products/[slug]/page.tsx"
+import { redirect } from '@rsc-kit/core/redirect';
+import { findProduct } from '../../../data';
+
+export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const product = await findProduct(slug);
+
+  if (!product) redirect('/products');
+
+  return <h1>{product.name}</h1>;
+}
+```
+
+`redirect` never returns — it throws, which is what stops the component. The
+default status is `307`, because it preserves the method: a redirect out of a
+`POST` does not silently become a `GET` of the target.
+
+A redirect during a navigation stays a navigation. The document does not reload,
+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.
+
+## Where you call it matters
+
+This is the part worth understanding, because it is also the security-relevant
+part. Headers flush early on purpose — that is what makes the first paint fast
+— so a redirect decided late has no status line left to use. There are two
+windows, and nothing you write chooses between them:
+
+| Called | Answered with | What the browser saw first |
+| --- | --- | --- |
+| Above every `<Suspense>` boundary | A real `3xx`, or `X-RSC-Redirect` on a navigation | Nothing at all |
+| Inside a boundary | The shell, then the redirect | Layouts, and the fallbacks standing in for what never arrived |
+
+Neither buffers the response. Before anything is written the host is still
+waiting on the shell, so a component that redirects instead of rendering is
+caught there. After that, React already carries an error digest to the client
+and the destination rides along in it.
+
+<Aside type="caution" title="Middleware belongs above the boundaries">
+  A `loading.tsx` wraps the whole page in `<Suspense>`. That is usually what you
+  want — it is how a page gets a frozen shell — but it also means an `await` at
+  the top of that page is *inside* a boundary, and a redirect after it arrives
+  in the second window.
+
+  Nothing from inside the boundary was shown, so a not-found redirect is fine
+  there. An authorization check is different: the layouts above it already
+  rendered and already went out. If a page must reveal nothing at all, the
+  check has to run somewhere that blocks the shell.
+</Aside>
+
+## Where to put an authorization check
+
+In order of preference:
+
+**In `middleware.ts`.** A file beside the layout, run before anything at or below it
+renders, on every path. This is the one built for the job.
+
+
+<Aside type="danger" title="A layout is not a security boundary">
+  It is tempting — a layout renders above the page's boundary, so on a full
+  page load a redirect there happens before anything is sent. But a navigation
+  tells the server which layouts the client already has, in `X-RSC-Segments`,
+  and the server skips re-rendering those. A client that *claims* to hold your
+  layout skips the check:
+
+  ```bash
+  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout' /guarded
+  # 204, X-RSC-Redirect: /orders        ← the middleware ran
+
+  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout,app/guarded/layout' /guarded
+  # 200, and the page's content         ← it did not
+  ```
+
+  The header is not verified and cannot be. Put the check in a `middleware.ts`
+  beside the layout instead — it runs before anything below it renders, on
+  every path. See [Authorization](/guides/authorization).
+</Aside>
+
+**At the top of a page with no `loading.tsx`.** Runs on every render of that
+page, so it is not skippable the way a layout is — but fragile in a different
+way: adding a `loading.tsx` later silently moves the check into the second
+window, and nothing warns.
+
+<Aside type="danger" title="Never catch it and continue">
+  `redirect` communicates by throwing. A `try`/`catch` that swallows everything
+  turns the redirect into a blank region — the component stops, and nothing
+  takes its place. If you must wrap the call, rethrow what you do not
+  recognise:
+
+  ```ts
+  import { isRedirectSignal } from '@rsc-kit/core/redirect';
+
+  try {
+    await mightRedirect();
+  } catch (error) {
+    if (isRedirectSignal(error)) throw error;
+    // …
+  }
+  ```
+</Aside>
+
+## From a server action
+
+An action is not a render, so there is no shell to be on either side of. Throw
+from the action and the client follows it:
+
+```ts title="src/actions.ts"
+'use server'
+
+import { redirect } from '@rsc-kit/core/redirect';
+
+export async function createPost(title: string) {
+  const post = await savePost(title);
+
+  redirect(`/posts/${post.slug}`);
+}
+```
+
+## A route that only redirects
+
+The redirect itself is stored, so it costs no render at all:
+
+```text
+○  /old-pricing   (redirects to /pricing)
+```
+
+The build writes the status and the location, and the host answers from that
+file — a document gets the status code, a navigation gets `X-RSC-Redirect` and
+does it as an SPA navigation. Nothing is rendered per request, and a static
+export can carry it.
+
+## Loops
+
+A navigation follows at most **8** redirects before throwing. A page that
+redirects to itself is a mistake someone will make, and without a ceiling it is
+an unbounded run of full renders rather than an error you can see.

package/guides/response-headers.md

@@ -0,0 +1,66 @@
+# Headers and cookies
+
+> Setting response headers and cookies during a render.
+
+## Reading
+
+Anywhere in a server component or action:
+
+```tsx
+import { headers, cookies, searchParams } from '@rsc-kit/core/request'
+
+export default async function Page() {
+  const h = await headers()
+  const jar = await cookies()
+
+  return <p>Hello {jar.get('name')?.value ?? 'stranger'}</p>
+}
+```
+
+## Writing
+
+```tsx
+import { responseHeaders, cookies } from '@rsc-kit/core/request'
+
+export async function middleware() {
+  responseHeaders().set('X-Frame-Options', 'DENY')
+
+  const jar = await cookies()
+  jar.set('last-seen', new Date().toISOString(), { httpOnly: true, path: '/' })
+}
+```
+
+**Writing only works in middleware.** Middleware runs before the render, while
+the response line has not been sent yet. A component runs *during* streaming,
+when the headers are already on the wire — writing from one throws rather than
+being silently dropped, so you find out immediately.
+
+A redirect carries them too, which is what lets middleware remember where
+someone was going before sending them to log in:
+
+```tsx
+export async function middleware() {
+  const jar = await cookies()
+
+  if (!jar.get('session')) {
+    jar.set('intended', '/dashboard', { path: '/' })
+    redirect('/login')
+  }
+}
+```
+
+## Cookie options
+
+```ts
+jar.set('name', 'value', {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',      // 'strict' | 'lax' | 'none'
+  path: '/',
+  maxAge: 60 * 60 * 24,
+  expires: new Date('2027-01-01'),
+})
+```
+
+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.