@rsc-kit/mcp 0.14.0 → 0.16.0

package/guides/authorization.md

@@ -0,0 +1,288 @@
+# Authorization
+
+> Protecting pages, server actions and API routes.
+
+There are three ways into your app — a page, a server action, an API route —
+and each needs its own check. Guarding one does not guard the others.
+
+## Protect a page
+
+Put a `middleware.ts` in the directory you want to protect:
+
+```ts title="src/app/admin/middleware.ts"
+import { redirect } from '@rsc-kit/core/redirect';
+import { currentUser } from '../../auth';
+
+export default async function middleware() {
+  const user = await currentUser();
+
+  if (!user?.isAdmin) redirect('/login');
+}
+```
+
+It runs before anything in that directory or below it renders. Return nothing
+to allow; redirect or throw to refuse.
+
+Middleware compose up the tree like layouts — outermost first — and **every**
+request runs the whole chain: a full page load, a navigation, a prefetch, a
+revalidation. There is no flag to remember; the file is the declaration.
+
+<Aside type="caution" title="Do not put the check in a layout">
+  It looks like it works, and it does on a full page load. But a navigation
+  tells the server which layouts the browser already has, and the server skips
+  them — that is what makes navigation fast. A request can claim to have your
+  layout, and then the check never runs.
+
+  `middleware.ts` is never skipped.
+</Aside>
+
+## Protect a server action
+
+An action is a public endpoint. Anyone can call it directly:
+
+```bash
+curl -X POST /_rsc/action \
+  -H 'X-RSC-Action: 0339292364be#placeOrder' \
+  -H 'X-RSC-Content-Type: text/plain;charset=UTF-8' \
+  --data-binary '["a rubber duck"]'
+```
+
+That is not a hole to plug — an action *is* an RPC endpoint and its id is not a
+secret. It means the check goes **inside the action**, not in the component that
+renders the button:
+
+```ts title="src/actions.ts"
+'use server'
+
+import { currentUser } from './auth';
+
+export async function placeOrder(item: string) {
+  const user = await currentUser();
+
+  if (!user) throw new Error('Not signed in');
+
+  // …
+}
+```
+
+<Aside type="caution" title="Middleware does not cover actions">
+  Middleware runs when a route renders. An action renders no route, so none of
+  them run. Each entry point defends itself.
+</Aside>
+
+### Write the check once
+
+One action is fine. Twenty is twenty chances to forget, and the one you forget
+is the one that matters. Put the check on a client and build every action from
+it:
+
+```ts title="src/server/client.ts"
+'use server'
+
+import { createActionClient } from '@rsc-kit/core/action'
+
+export const client = createActionClient()
+  .use(async ({ next }) => {
+    const user = await currentUser()
+
+    if (!user) throw new ServerAuthenticationError()
+
+    return next({ ctx: { user } })
+  })
+```
+
+```ts title="src/server/orders.ts"
+'use server'
+
+import { client } from './client'
+
+export const placeOrder = client.input(schema).handler(async ({ input, ctx }) =>
+  orders.create(ctx.user.id, input),
+)
+
+export const listOrders = client.query(async ({ ctx }) => orders.forUser(ctx.user.id))
+```
+
+`ctx.user` is typed and non-null inside the handler, because the only way to get
+there was through the middleware that put it in. **An action cannot be added
+without the check** — not because a rule says so, but because there is no other
+constructor to reach for.
+
+`.handler()` makes an action, `.query()` makes a [read](/guides/queries/), and
+both run the same chain. Add a second `.use()` for a role check and it applies
+to everything built from that client:
+
+```ts
+export const admin = client.use(async ({ ctx, next }) => {
+  if (!ctx.user.isAdmin) throw new ServerAuthorizationError()
+
+  return next({ ctx })
+})
+```
+
+Authorise on **identity, not arguments**. `cancelOrder(id)` that trusts the id
+is the whole of an IDOR — the caller chooses the id, so the handler has to check
+the row belongs to `ctx.user`.
+
+## Protect an API route
+
+A [route](/guides/api-routes/) runs the same middleware a page in that directory
+would. Put it under a guarded path and it is guarded:
+
+```text
+src/app/admin/
+  middleware.ts          ← guards everything below
+  page.tsx               ← guarded
+  api/export/route.ts    ← guarded too
+```
+
+A refused route answers **401** or **403** rather than redirecting, and names
+the destination in `X-RSC-Redirect` if the middleware wanted one. A `fetch`
+would follow a redirect and hand back a login page as though it were your data.
+
+For a route with no middleware above it, check inside the handler:
+
+```ts title="src/app/api/orders/route.ts"
+import { currentUser } from '../../../auth';
+
+export async function GET(): Promise<Response> {
+  const user = await currentUser();
+
+  if (!user) return new Response('Unauthorized', { status: 401 });
+
+  return Response.json(await orders(user.id));
+}
+```
+
+## Read the session
+
+There is no request object. `headers()` and `cookies()` read the one in flight:
+
+```ts title="src/app/[locale]/middleware.ts"
+import { redirect } from '@rsc-kit/core/redirect';
+import { cookies, headers } from '@rsc-kit/core/request';
+
+export default async function middleware() {
+  const jar = await cookies();
+  const locale = jar.get('locale') ?? negotiate((await headers()).get('accept-language'));
+
+  if (!locale) redirect('/en');
+}
+```
+
+They work anywhere a request is in flight — middleware, server components,
+actions, API routes — so whatever you already use for locale, feature flags or
+tenants works inside a plain async function. `request()` gives you the whole
+`Request` for anything the two do not cover.
+
+They are async for a reason worth knowing: at build time there is no request, so
+a read *suspends*. React freezes the shell above it and only the part that
+wanted a header renders per visitor. A synchronous read would force the whole
+page to re-render for everyone.
+
+### Ask once
+
+Middleware wants to know who you are; the layout wants their name; the page
+wants their permissions. Wrap the lookup in `cache()` and that is one query:
+
+```ts title="src/session.ts"
+import { cache } from '@rsc-kit/core/cache';
+
+export const currentUser = cache(async () => {
+  const id = await sessionId();
+
+  return db.user(id);
+});
+```
+
+The scope is one request. Two requests never see each other's answers, and
+nothing survives between them. Outside a request it just calls through, so
+shared code does not need to know where it is running.
+
+## Set a cookie
+
+Middleware runs before the response exists, which makes it the place to put a
+header or a cookie on it:
+
+```ts title="src/app/account/middleware.ts"
+import { cookies, responseHeaders } from '@rsc-kit/core/request'
+
+// Middleware runs before anything below it renders, which is also before the
+// host has built a response — so this is the one place left where a header or a
+// cookie can still be put on it. A component runs after, while the response is
+// already streaming, and writing from there throws rather than being dropped.
+//
+// The page below is frozen at build time and stays frozen: what is written here
+// is per request, so neither costs the other anything.
+export default async function middleware() {
+  responseHeaders().set('X-Account-Section', 'yes')
+
+  const jar = await cookies()
+
+  if (!jar.get('seen-account')) {
+    jar.set('seen-account', new Date().toISOString(), { httpOnly: true, sameSite: 'lax' })
+  }
+}
+```
+
+Actions can write too, which is the case that matters — signing someone in is a
+mutation that has to leave a cookie behind:
+
+```ts title="src/app/login/actions.ts"
+'use server';
+
+import { action } from '@rsc-kit/core/action';
+import { cookies } from '@rsc-kit/core/request';
+
+export const login = action.input(credentials).handler(async ({ input }) => {
+  const session = await authenticate(input);
+
+  (await cookies()).set('session', session.token, {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'lax',
+    maxAge: 60 * 60 * 24 * 7,
+  });
+});
+```
+
+`get`, `set` and `delete` over the request in flight is the whole surface an
+auth library needs, so you can wire in whichever one you use.
+
+<Aside type="caution" title="A component is too late">
+  By the time a page renders, the status and headers are already on the wire.
+  Writing from a component throws and tells you to move it to middleware —
+  rather than accepting the call and quietly dropping it.
+</Aside>
+
+## A guarded page can still be frozen
+
+Whether the content is the same for everyone, and whether *you* may see it, are
+different questions. The build answers the first; middleware answers the second,
+per request. So an internal page whose bytes never vary is frozen at build time
+and the middleware decides who gets the file:
+
+| Route | Navigation |
+| --- | --- |
+| Guarded and frozen — check, then serve from disk | 6.7 ms |
+| Guarded, rendered on demand | 2626.7 ms |
+| Unguarded, frozen | 0.6 ms |
+
+The check runs before the file is read, so a refusal never touches it.
+
+<Aside type="caution" title="Two places this does not hold">
+  **A static export cannot guard anything.** A static host serves files without
+  running code, so exporting a guarded route publishes it to whoever asks.
+
+  **Do not put a guarded page in a shared cache.** Your origin runs the check; a
+  CDN holding the response serves it to the next caller without asking.
+</Aside>
+
+## Where each check goes
+
+| Question | Where it goes |
+| --- | --- |
+| May this person see this section? | `middleware.ts` in its directory |
+| May this caller run this action? | Inside the action |
+| May this caller use this endpoint? | Inside the route handler |
+| Should the page show different things to different people? | The page — it renders per request anyway |

package/guides/caching.md

@@ -0,0 +1,57 @@
+# Asking once per request
+
+> cache() — one lookup, however many places need it.
+
+Middleware checks who you are. The layout wants their name. The page wants their
+permissions. That is three calls and one answer.
+
+Wrap the lookup:
+
+```ts
+import { cache } from '@rsc-kit/core/cache'
+
+export const currentUser = cache(async () => db.user(await sessionId()))
+```
+
+Now call it wherever you need it. The first call runs; the rest get the same
+answer:
+
+```tsx
+export async function middleware() {
+  if (!(await currentUser())) redirect('/login')
+}
+
+export default async function Page() {
+  const user = await currentUser()   // already resolved
+
+  return <h1>Hello {user.name}</h1>
+}
+```
+
+## One request, and no further
+
+Two requests in flight never see each other's answers, and nothing survives into
+the next one. The scope opens when the request arrives and is torn down with it.
+
+That is the whole safety story: a table that outlived its request would not be a
+stale cache, it would be one visitor seeing another's data.
+
+## Arguments
+
+Compared the way React compares them — primitives by value, objects by identity:
+
+```ts
+const post = cache(async (id: string) => db.post(id))
+
+post('a')   // runs
+post('a')   // reuses the first
+post('b')   // runs
+```
+
+Two objects that look the same are two different calls, so pass an id rather
+than an object when you want the reuse.
+
+<Aside type="note" title="Not React's cache()">
+  Same idea, wider scope. Middleware runs before any component does, which is
+  exactly where the duplicate lookups start — and React has no scope open yet.
+</Aside>

package/guides/coming-from-next.md

@@ -0,0 +1,151 @@
+# Coming from Next.js
+
+> What carries over unchanged, what to rename, and what is different on purpose.
+
+Most of a Next.js app directory moves over as it is. This page is the rest,
+in the order a port meets it.
+
+## What is the same
+
+The `app/` conventions are the same conventions: `layout.tsx`, `page.tsx`,
+`loading.tsx`, `error.tsx`, `not-found.tsx`, `route.ts`, `[slug]`,
+`[...path]`, `(group)`, `@slot` and `(.)intercept`. `"use client"` and
+`"use server"` mean what they mean in React. `cookies()` and `headers()` are
+async and have the same names. `redirect()`, `notFound()`,
+`generateStaticParams()` and `export const metadata` all exist. Streaming
+through `<Suspense>` works the same way, because it is React doing it.
+
+Copy `src/app` across first and fix imports second. Most files need only the
+imports.
+
+## Imports
+
+| Next.js | here |
+| --- | --- |
+| `next/link` | `@rsc-kit/core/Link` — `href` is typed to your routes, and `search` to the page's schema |
+| `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` |
+| `redirect()` from `next/navigation` | `@rsc-kit/core/redirect` |
+| `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.config.js` | `vite.config.ts` — Tailwind, aliases and plugins are Vite's |
+| `next-safe-action` | `createActionClient()` — same shape, [below](#actions) |
+
+## Different on purpose
+
+### Nothing is dynamic by declaration
+
+There is no `export const dynamic = 'force-dynamic'` and no `revalidate = 60`.
+A page is frozen at build time unless it **reads the request** — `cookies()`,
+`headers()`, `searchParams`, `await connection()` — and then it renders per
+request, or as a shell with the reading part streamed in. The build prints
+which, and why:
+
+```
+  ○  /about               no js
+  ◐  /orders              85 kB
+     dynamic — called cookies()
+```
+
+`await connection()` is the one explicit mark, for a page that must render per
+visitor and does not happen to read anything. Time-based ISR does not exist:
+a frozen page changes when you build, a dynamic one on every request, and
+[edge caching](/guides/edge-caching) covers the middle.
+
+### Middleware is per directory, not one file at the edge
+
+Next has one `middleware.ts` that runs on a matcher, on the edge runtime, with
+a restricted API. Here a `middleware.ts` sits in the directory it protects,
+runs on the server with the full API, and covers everything below it:
+
+```ts title="src/app/admin/middleware.ts"
+export default async function middleware() {
+  if (!(await currentUser())?.isAdmin) redirect('/login');
+}
+```
+
+It does not run for actions — an action renders no route — which is why the
+check for an action belongs in the action. See [Authorization](/guides/authorization).
+
+### Actions
+
+`next-safe-action` users will find the same shape under a different name.
+`createActionClient()` chains middleware, validates with any Standard Schema,
+and **returns** failures as `{ validationErrors }` or `{ serverError }` rather
+than throwing them across the wire:
+
+```ts
+export const client = createActionClient().use(async ({ next }) => {
+  const user = await currentUser();
+  if (!user) throw new ServerAuthenticationError();
+  return next({ ctx: { user } });
+});
+
+export const createPost = client.input(schema).handler(async ({ input, ctx, fieldErrors }) => {
+  if (await slugTaken(input.slug)) return fieldErrors({ slug: 'Already taken' });
+  return save(input, ctx.user);
+});
+```
+
+`returnValidationErrors(schema, { email: { _errors: [...] } })` becomes
+`return fieldErrors({ email: 'Account not found' })`. `useAction` from
+next-safe-action is `useActionState`, or a `<Form action={createPost}>` that
+reads the returned errors on its own. The build lists any action not built
+from a client, because nothing checks who calls those.
+
+### Revalidation is targeted
+
+`revalidatePath('/orders')` re-renders the page. `revalidate('orders')`
+re-renders the [section](/guides/sections) registered under that name and
+sends it back **with the action's own response** — one request, the rest of
+the page untouched, a half-typed input elsewhere on it still typed. Wrap the
+region in `section('orders', Orders)` and name it from the action.
+
+### Forms
+
+`<Form>` from `@rsc-kit/core/form` submits to an action, shows pending state,
+places field errors, and works before hydration. It is uncontrolled by
+default like React Hook Form's `register`, with `field()` for a controlled
+binding and `useField()` for a value read anywhere. shadcn's `Field`
+components fit as they are. See [Forms](/guides/forms).
+
+### Query strings are typed
+
+Export a schema beside the page and the values arrive parsed; the same schema
+types every `<Link search={…}>` to it. `Number(searchParams.get('page'))` is
+not a thing you write here. See [URL validation](/guides/url-validation).
+
+### There is no image optimizer, and no `opengraph-image.tsx`
+
+Both are processes Next runs for you at request time. Put `opengraph-image.png`
+in `src/app` and it is picked up; generate one at build time if it has to be
+generated. Images: [unpic or imagetools](/guides/images).
+
+### Testing does not need a browser
+
+`createTestApp()` hands back the deployed `Request → Response` handler.
+Actions, queries and api routes are plain functions. There is no equivalent
+in Next; see [Testing](/guides/testing).
+
+## The porting order that worked
+
+1. `bun create rsc-kit@latest` and copy `src/app` over the scaffold's.
+2. Fix imports from the table. `bun run typecheck` finds the rest.
+3. `bun run build` and **read the output**: every route that is not `○` says
+   why. Most surprises are a `cookies()` in a layout making everything
+   dynamic — 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.
+
+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
+version, and the build report is what it reads instead of guessing.

package/guides/connection.md

@@ -0,0 +1,98 @@
+# Rendering per request
+
+> Marking work that belongs to the visitor, not to the build.
+
+Most pages can be rendered once, at build time, and served as files. Some work
+cannot: a query whose database the build machine cannot reach, or a value that
+has to differ per visitor.
+
+`connection()` marks that work.
+
+```tsx title="src/app/orders/page.tsx"
+import { connection } from '@rsc-kit/core/request'
+
+export default async function OrdersPage() {
+  await connection()
+
+  const rows = await db.query('select * from orders')
+
+  return <ul>{rows.map((r) => <li key={r.id}>{r.reference}</li>)}</ul>
+}
+```
+
+At build time it never resolves, so **nothing after it runs** — the query is not
+made, and the build needs no database. At request time it resolves immediately
+and the component runs normally.
+
+## Call it once
+
+This is the mistake worth avoiding:
+
+```tsx
+await connection()
+
+const orders = await db.orders()
+await connection()          // ← does nothing
+const customers = await db.customers()
+await connection()          // ← does nothing
+```
+
+It is a **barrier, not a wrapper**. Everything after it in that component
+belongs to the request, however many calls that turns out to be. The second and
+third calls are already covered by the first.
+
+One call, as early as the work begins. That is the whole API.
+
+## It needs a boundary above it
+
+The build stores what it *can* paint. If `connection()` is reached before
+anything has painted, there is nothing to store:
+
+```tsx
+export default async function Page() {
+  await connection()        // nothing above it has rendered
+
+  return <h1>{await something()}</h1>
+}
+```
+
+Give it a boundary and the page becomes a shell — the layout and headings are
+stored, and the marked part arrives per request:
+
+```tsx
+export default function Page() {
+  return (
+    <>
+      <h1>Orders</h1>
+      <Suspense fallback={<p>Loading orders…</p>}>
+        <Orders />          {/* calls connection() inside */}
+      </Suspense>
+    </>
+  )
+}
+```
+
+A `loading.tsx` beside the page does the same thing for everything below it.
+Without either, the build refuses the route rather than storing a blank page,
+and tells you which one to add.
+
+## When you do not need it
+
+A query the build **can** run, whose answer is the same for every visitor, wants
+none of this. Let it freeze — that is the whole benefit of prerendering, and
+marking it per-request gives every visitor a render they did not need.
+
+Use it when the build genuinely should not do the work:
+
+- the database or API is not reachable from the build machine
+- the value must differ per visitor
+- the data changes faster than you deploy
+
+## Same as Next.js
+
+Same name and same behaviour as Next's `connection()`, so there is nothing new
+to learn if you have used it.
+
+You will reach for it less often here, though. The build classifies routes by
+rendering them rather than asking you to declare, so most dynamic pages are
+already understood without a marker.