@rsc-kit/mcp 0.14.0 → 0.16.0

package/guides/edge-caching.md

@@ -0,0 +1,159 @@
+# Serving shells from a CDN
+
+> Putting build-time shells on the edge, and what rsc-kit does not do.
+
+A prerendered page is a file. So is a PPR shell. Both can sit on a CDN and be
+served without touching your origin.
+
+## What the build gives you
+
+```
+build/static/
+  about.html            a whole page, frozen
+  posts/hello.html      likewise
+  posts/[slug].ppr.html a shell — static parts frozen, holes still empty
+  about.flight          the payload for a client-side navigation
+  about.seg1.flight     the same, for a client already holding one layout
+```
+
+`.html` is a finished page. `.ppr.html` is a shell: the layout, nav and
+everything outside a `<Suspense>` boundary, with the fallbacks still in place.
+Neither contains per-visitor data — they were rendered at build time, in no
+request's context, which is what makes them safe for a shared cache.
+
+## Caching them
+
+The host already sends the right header:
+
+```
+Cache-Control: public, max-age=0, must-revalidate
+```
+
+`public` says a shared cache may store it. `max-age=0, must-revalidate` says
+**check with the origin first**. So a CDN in front of this holds the bytes but
+still asks every time — which saves bandwidth and nothing else.
+
+To actually serve from the edge, add a cache rule for the paths you want held,
+and give the CDN an edge TTL. On Cloudflare that is a Cache Rule with *Edge TTL
+→ Override origin*.
+
+**Do not blanket-cache the whole site.** A route with middleware is deliberately
+sent as:
+
+```
+Cache-Control: private, no-store
+```
+
+because middleware runs per visitor — that is a page whose content depends on
+who asked. A zone-wide "cache everything" rule overrides that and serves one
+person's gated page to everyone. Scope the rule to the paths you know are
+static.
+
+Deployments are handled for you: cached responses carry a build version, so a
+new deploy does not leave old shells being served against a new payload.
+
+## Finishing a shell at the edge
+
+A shell has holes in it, and something has to fill them. That happens at your
+origin, into the same response — the shell is written first, then the
+boundaries it could not finish.
+
+You get this with no configuration: request a PPR route and the document you
+receive already contains its dynamic content.
+
+A small inline script from React moves each hole into place as the HTML parses.
+So the content appears without waiting for the app bundle or for hydration — on
+a slow connection, the difference between a spinner and a page. It also means
+the content is in the HTML a crawler reads.
+
+This is not the same as working without JavaScript: with scripting off, the
+fallbacks stay.
+
+To serve the shell itself from a CDN, two endpoints exist for an edge worker:
+
+```
+GET  /_rsc/ppr-shell?url=/dashboard    the build-time shell, cacheable
+POST /_rsc/ppr-resume?url=/dashboard   the holes, for this visitor
+```
+
+There is a complete Cloudflare implementation in
+[`examples/cloudflare-ppr-worker`](https://github.com/rsc-kit/rsc-kit/tree/main/examples/cloudflare-ppr-worker),
+with no KV and no build step. The cache fills itself from the shell endpoint: a
+miss goes to the origin while the shell warms behind it, and a hit streams the
+shell then pipes the resumed holes onto the same response.
+
+### What the response looks like on the wire
+
+Measured on a deployed worker, for a page whose hole takes 2.5 s:
+
+```
+headers          55 ms
+first body byte  56 ms
+shell heading    56 ms      ← the page is on screen here
+fallback markup  56 ms
+hole content   2549 ms      ← same response, no second request
+stream complete 2549 ms
+```
+
+Before this, the same document finished in 2 ms and contained no hole at all —
+the content arrived later, on a separate payload fetch, after React had
+hydrated.
+
+**The trade is that the response stays open until the holes finish.** Previously
+the document closed immediately and `load` fired early; now it fires when the
+slowest boundary resolves. Nothing a visitor sees is slower — the shell paints
+at the same moment either way — but page-level metrics that key on `load` will
+read differently, and a proxy with a short response timeout needs to allow for
+the whole render rather than just the shell.
+
+## Guarded routes are never cached
+
+The shell endpoint answers `404` for any route that declares middleware. Such a
+page is not cacheable by a shared cache at all, so it never becomes a cache
+entry — refused at the source rather than checked at the edge.
+
+The resume endpoint runs that route's middleware against **the caller's own
+cookies**, and refuses before rendering anything. An edge worker must therefore
+forward the visitor's request rather than making one of its own; a resume asked
+for with no cookies is an anonymous visitor and gets an anonymous answer.
+
+## What stays on your origin
+
+Next's PPR protocol hands the postponed blob to the CDN and takes it back on the
+resume, which means the resume endpoint parses something an attacker can write.
+That is the shape of a known denial-of-service against it.
+
+Here the endpoint takes a **url**. The origin reads its own state from disk, and
+a body posted to it is ignored. This is only possible because — unlike a generic
+CDN — the origin already has the artifact, so there is nothing to hand out and
+take back.
+
+## When a CDN owns the response
+
+Everything above rests on one fact: on this host, a per-visitor response head
+can only come from middleware. `responseHeaders()` and `cookies().set()` throw
+outside it, so a route that declares no middleware has no way to acquire one —
+which is why "declares middleware" is a safe answer to "is this cacheable".
+
+An auth proxy in front of the app breaks that, and quietly. One with sliding
+expiry re-issues the session on an ordinary `200`, so the response leaving your
+CDN carries a `Set-Cookie` this host never sent. Marked `public`, that is one
+visitor's session handed to the next.
+
+**Give any path your proxy covers a `middleware.ts`**, even an empty one. That
+is what makes a route covered here, and covered routes are excluded from every
+cache decision: `private, no-store` on the page, and refused outright by the
+shell endpoint.
+
+Two things worth knowing about this failure if you go looking for it.
+
+You cannot detect this by inspecting the response. Nothing added a
+`Vary: Cookie`, and looking for `Set-Cookie` only catches the cookie version —
+an `x-user-id`, a CSRF token or a locale header leaks the same way.
+
+The reliable question is structural: who owns the response head on this route?
+
+It fails both ways. The loud one is a session leaking to the next visitor. The
+quiet one is the reverse — an anonymous response cached first, then served to
+someone who should have had a session, silently signing them out. The first gets
+reported; the second looks like a flaky login.

package/guides/errors.md

@@ -0,0 +1,109 @@
+# Errors and 404s
+
+> What a visitor sees when a page throws, or asks for a url nothing answers.
+
+Two files, both optional, both following the same rule as `loading.tsx`: the
+nearest one wins.
+
+## When a page throws
+
+Put an `error.tsx` in the directory you want to cover:
+
+```tsx title="src/app/orders/error.tsx"
+'use client'
+
+import type { RouteErrorProps } from '@rsc-kit/core/RouteErrorBoundary'
+
+export default function OrdersError({ error, reset }: RouteErrorProps) {
+  return (
+    <section>
+      <h1>That did not work</h1>
+      <p>{error.message}</p>
+      <button type="button" onClick={reset}>Try again</button>
+    </section>
+  )
+}
+```
+
+Anything below it that throws renders this instead. The layouts above stay on
+screen — only the segment that failed is replaced.
+
+`reset()` renders the segment again, for a failure that might not happen twice.
+Navigating away clears it on its own.
+
+:::caution[It has to be a client component]
+`'use client'` at the top, or the build refuses it. Catching a render error is
+a class component's job, it runs in the browser, and `reset` is a callback the
+browser calls — none of which a server component can do.
+:::
+
+### What `error.message` says in production
+
+React replaces it with a generic sentence and puts a hash on `error.digest`.
+That is React, not this package: the real message could name a table, a query or
+a path, and none of that should reach a browser.
+
+Log the digest where you log the error, and the two line up.
+
+### It does not catch everything
+
+- **Errors in the layout above it.** The boundary sits inside that layout, so a
+  layout that throws needs an `error.tsx` a directory up.
+- **The build.** A page that throws every time it renders fails the build
+  rather than shipping a stored error page. The boundary is for a request that
+  goes wrong, not a page that is broken.
+
+## When nothing answers the url
+
+`src/app/not-found.tsx` is rendered for any url no route matches:
+
+```tsx title="src/app/not-found.tsx"
+import Link from '@rsc-kit/core/Link'
+
+export default function NotFound() {
+  return (
+    <main>
+      <h1>No such page</h1>
+      <p>Nothing answers that url. <Link href="/">Go home</Link>.</p>
+    </main>
+  )
+}
+```
+
+It renders through your root layout like any other page, and is served with a
+real **404** — a page that says "not found" under a `200` is a page search
+engines index.
+
+An ordinary server component, so it can be `async` and read whatever it likes.
+Without one, an unmatched url gets a plain `Not found` string.
+
+### When the page has to decide
+
+A url can match a route and still name nothing — `/posts/42` is a real route
+and there may be no post 42. Only the page can know that, so the page says so:
+
+```tsx title="src/app/posts/[slug]/page.tsx"
+import { notFound } from '@rsc-kit/core/not-found'
+
+export default async function PostPage({ params }) {
+  const post = await findPost((await params).slug)
+
+  if (!post) notFound()
+
+  return <article>{post.title}</article>
+}
+```
+
+Same page, same **404**. It throws, so nothing after it runs — and if you wrap
+the call in a `try`/`catch`, rethrow what you do not recognise, or a missing
+page becomes a blank region.
+
+:::caution[Where you call it decides the status]
+Called above every Suspense boundary — at the top of a page, in a layout —
+nothing has been written yet, so the response is a real 404.
+
+Called deeper, inside a boundary, the shell has already gone out with the
+status line on it. The boundary shows its fallback instead and the status stays
+`200`. If the status matters — and for anything a crawler or a cache sees, it
+does — do the lookup above the boundary.
+:::

package/guides/file-uploads.md

@@ -0,0 +1,119 @@
+# File uploads
+
+> Sending files through a server action without encoding them.
+
+A `File` is a value a server action can take. React's Flight format carries it
+as binary, so there is nothing to encode on the way out and nothing to decode
+on the way in.
+
+## One file
+
+```tsx title="src/components/AvatarUpload.tsx"
+"use client";
+
+import { useState } from 'react';
+import { uploadAvatar } from '../actions';
+
+export function AvatarUpload() {
+  const [url, setUrl] = useState<string | null>(null);
+
+  async function submit(formData: FormData) {
+    const file = formData.get('avatar') as File;
+
+    if (!file || file.size === 0) return;
+
+    setUrl(await uploadAvatar(file));
+  }
+
+  return (
+    <form action={submit}>
+      <input type="file" name="avatar" accept="image/*" />
+      <button type="submit">Upload</button>
+      {url && <img src={url} alt="" />}
+    </form>
+  );
+}
+```
+
+The action receives the `File` itself — name, type, size and all:
+
+```ts title="src/actions.ts"
+'use server'
+
+import { writeFile } from 'node:fs/promises';
+
+export async function uploadAvatar(file: File): Promise<string> {
+  const bytes = new Uint8Array(await file.arrayBuffer());
+
+  await writeFile(`./public/avatars/${file.name}`, bytes);
+
+  return `/avatars/${file.name}`;
+}
+```
+
+Nothing about that is upload-specific: it is the same call, the same
+serialisation and the same round trip as [any other server
+action](/guides/server-actions).
+
+## The whole form at once
+
+An action can take the `FormData` instead of individual arguments, which is
+usually simpler when the form mixes files and fields:
+
+```tsx
+"use client";
+
+import { createPost } from '../actions';
+
+export function NewPost() {
+  return (
+    <form action={createPost}>
+      <input name="title" />
+      <textarea name="body" />
+      <input type="file" name="cover" accept="image/*" />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+```ts title="src/actions.ts"
+'use server'
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+  const cover = formData.get('cover') as File;
+
+  // …
+}
+```
+
+## Several files
+
+`formData.getAll` gives every file from a `multiple` input, and an array of
+`File` serialises as readily as one:
+
+```tsx
+const files = formData.getAll('photos') as File[];
+
+await uploadPhotos(files);
+```
+
+```ts title="src/actions.ts"
+'use server'
+
+export async function uploadPhotos(files: File[]) {
+  for (const file of files) {
+    // …
+  }
+}
+```
+
+## Size
+
+The whole body is buffered before the action runs — it is one `POST`, not a
+stream — so an upload occupies memory for as long as it takes. Two consequences
+worth planning for:
+
+- Keep any limit your host imposes as low as the app actually needs.
+- For genuinely large files, do not send them through an action at all. Have the action mint a pre-signed URL and let the browser upload straight to storage; the bytes never touch your server.

package/guides/fonts.md

@@ -0,0 +1,117 @@
+# Fonts
+
+> Self-hosted fonts from npm, and what next/font was doing for you.
+
+Install the font, import its CSS, name it in a variable. Vite does the rest.
+
+```sh
+bun add @fontsource-variable/fraunces @fontsource-variable/geist
+```
+
+```css title="src/app/styles.css"
+@import '@fontsource-variable/fraunces/full.css';
+@import '@fontsource-variable/fraunces/full-italic.css';
+@import '@fontsource-variable/geist';
+
+:root {
+  --font-display: 'Fraunces Variable', ui-serif, Georgia, Cambria, 'Times New Roman', serif;
+  --font-sans: 'Geist Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+    'Helvetica Neue', Arial, sans-serif,
+    'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+}
+```
+
+Put your font in *front* of a full stack rather than in place of one. Two things
+the rest of the stack does that a bare `sans-serif` does not:
+
+- **Emoji.** Geist has no emoji glyphs, so an emoji falls through to whatever is
+  named after it. With nothing there, some Linux and older Android setups draw a
+  monochrome glyph or a box. The four emoji fonts at the end are consulted only
+  for characters the main font cannot draw, so they cost nothing.
+- **A closer fallback.** During the `swap` window the browser shows the next
+  font. `-apple-system` and `Segoe UI` are nearer Geist in width and x-height
+  than Helvetica or Arial, so the moment of swap is a smaller jolt.
+
+Those are Tailwind's own defaults, and shadcn's generated `--font-sans:
+'Geist Variable', sans-serif` drops both. Keep the stack.
+
+[Fontsource](https://fontsource.org) packages every Google font — and many
+others — as woff2 files with the `@font-face` rules already written. Vite
+hashes the files and serves them beside your other assets, so **nothing is
+fetched from Google at runtime**, and nothing is downloaded at build time
+either. The files are in `node_modules`.
+
+## Porting from `next/font`
+
+```ts
+// before
+const fraunces = Fraunces({
+  variable: '--font-display',
+  subsets: ['latin'],
+  style: ['normal', 'italic'],
+  axes: ['SOFT', 'opsz'],
+  display: 'swap',
+})
+```
+
+Every option there is something Fontsource already did:
+
+| `next/font` | Fontsource |
+| --- | --- |
+| `variable: '--font-display'` | the `:root` rule above — you write the variable, once |
+| `subsets: ['latin']` | every subset ships, each with a `unicode-range`; the browser fetches only the ones the page uses |
+| `style: ['normal', 'italic']` | `full.css` and `full-italic.css` |
+| `axes: ['SOFT', 'opsz']` | `full.css` — every axis of the variable font; `standard.css` is weight alone |
+| `display: 'swap'` | already in every rule |
+| `className={fraunces.variable}` | nothing — the variable is on `:root` |
+
+So the layout loses its font imports and the `className` gains nothing:
+
+```tsx title="src/app/layout.tsx"
+import './styles.css'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className="h-full antialiased dark font-sans">
+      …
+    </html>
+  )
+}
+```
+
+The subsetting is worth a second look, because it is *better* than what you
+had. `next/font` asks you to name subsets at build time and ships those.
+Fontsource ships all of them, each behind a `unicode-range`, and the browser
+downloads only the ones a page's text actually needs — a Latin-only page
+fetches one file whatever else is installed.
+
+## Preloading
+
+The one thing `next/font` did that needs a line here. It added a `<link
+rel="preload">` for each font so the browser finds it before the stylesheet
+does. Without one, the font is discovered when the CSS is parsed, and the text
+shows in the fallback face for a moment longer.
+
+Import the file for its url, and React hoists the link:
+
+```tsx title="src/app/layout.tsx"
+import fraunces from '@fontsource-variable/fraunces/files/fraunces-latin-full-normal.woff2?url'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <link rel="preload" href={fraunces} as="font" type="font/woff2" crossOrigin="anonymous" />
+      </head>
+      …
+```
+
+`?url` is Vite's — it hands back the hashed path the build will serve. Preload
+the one file the first paint needs, usually the Latin regular; preloading all
+of them defeats the subsetting.
+
+## A font that is not on npm
+
+A file you own goes in `public/` and gets its own `@font-face` in your CSS, the
+same as anywhere. Or in `src/` and imported with `?url` as above, which hashes
+it.