@rsc-kit/mcp 0.13.1 → 0.15.0

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.