@rsc-kit/mcp 0.14.0 → 0.16.0

package/guides/images.md

@@ -0,0 +1,83 @@
+# Images
+
+> Responsive images with no optimizer to run — unpic for a CDN, imagetools for files in the repo.
+
+There is no image component and no image server. `next/image` is two things
+glued together: a component that writes `srcset` and `sizes` for you, and an
+optimizer that resizes on the fly — a process with sharp in it, a cache to
+manage, and a CPU bill on every cold hit. The first half is worth having. The
+second belongs to whatever already serves your images.
+
+## Images on a CDN
+
+If the file lives on Cloudinary, imgix, Cloudflare Images, Bunny, Vercel,
+Netlify or any of the [other providers unpic knows](https://unpic.pics/img/react/),
+it already has a resizing url. [unpic](https://unpic.pics) writes the `srcset`
+against it:
+
+```tsx title="src/app/page.tsx"
+import { Image } from '@unpic/react';
+
+<Image
+  src="https://res.cloudinary.com/demo/image/upload/sample.jpg"
+  layout="constrained"
+  width={800}
+  height={600}
+  alt="A sample"
+/>
+```
+
+It is a plain component, so it renders in a server component and the browser
+receives an `<img>` — `srcset` from 640w up, `sizes`, `aspect-ratio`,
+`loading="lazy"`, `decoding="async"` — and none of unpic's code. The route's
+javascript does not change. The CDN is detected from the url; nothing to
+configure.
+
+TanStack Start and Astro point at the same library, for the same reason.
+
+## Images in the repository
+
+A file under `src/` is resized once, at build time, by
+[vite-imagetools](https://github.com/JonasKruckenberg/imagetools). Query
+parameters on the import say what you want:
+
+```ts title="vite.config.ts"
+import { imagetools } from 'vite-imagetools';
+
+export default defineConfig({
+  plugins: [imagetools(), rscKit(), ...],
+});
+```
+
+```tsx title="src/app/page.tsx"
+import hero from '../hero.png?w=400;800;1200&format=webp&as=srcset';
+import heroSrc from '../hero.png?w=800&format=webp';
+
+<img srcSet={hero} src={heroSrc} sizes="(min-width: 800px) 800px, 100vw" width={800} height={600} alt="…" />
+```
+
+The build emits `hero-<hash>.webp` at each width into `assets/`, hashed and
+cacheable forever, and a page that is frozen carries the urls. It costs the
+build what resizing costs, once per image per width, and nothing at request
+time. It is opt-in for that reason: a hundred hero images at four widths is a
+noticeable build, and most of them belong on a CDN.
+
+Declare the query so TypeScript stops asking:
+
+```ts title="src/images.d.ts"
+declare module '*?*' {
+  const value: string;
+  export default value;
+}
+```
+
+## What to pick
+
+| the image is | use |
+| --- | --- |
+| user-uploaded, or on a CDN already | unpic |
+| in the repo, a handful | imagetools |
+| in the repo, hundreds | put them on a CDN and use unpic |
+| an icon or a logo | `<img>`, or inline the svg |
+
+Neither one runs at request time, and neither is on the page's javascript.

package/guides/index.json

@@ -0,0 +1,187 @@
+[
+  {
+    "slug": "api-routes",
+    "title": "API routes",
+    "description": "Web-standard endpoints, colocated with your pages, with no configuration."
+  },
+  {
+    "slug": "authorization",
+    "title": "Authorization",
+    "description": "Protecting pages, server actions and API routes."
+  },
+  {
+    "slug": "caching",
+    "title": "Asking once per request",
+    "description": "cache() — one lookup, however many places need it."
+  },
+  {
+    "slug": "coming-from-next",
+    "title": "Coming from Next.js",
+    "description": "What carries over unchanged, what to rename, and what is different on purpose."
+  },
+  {
+    "slug": "connection",
+    "title": "Rendering per request",
+    "description": "Marking work that belongs to the visitor, not to the build."
+  },
+  {
+    "slug": "edge-caching",
+    "title": "Serving shells from a CDN",
+    "description": "Putting build-time shells on the edge, and what rsc-kit does not do."
+  },
+  {
+    "slug": "errors",
+    "title": "Errors and 404s",
+    "description": "What a visitor sees when a page throws, or asks for a url nothing answers."
+  },
+  {
+    "slug": "file-uploads",
+    "title": "File uploads",
+    "description": "Sending files through a server action without encoding them."
+  },
+  {
+    "slug": "fonts",
+    "title": "Fonts",
+    "description": "Self-hosted fonts from npm, and what next/font was doing for you."
+  },
+  {
+    "slug": "forms",
+    "title": "Forms",
+    "description": "Progressive forms, pending state and validation errors."
+  },
+  {
+    "slug": "getting-started",
+    "title": "Getting started",
+    "description": "Serve React Server Components from any JavaScript backend."
+  },
+  {
+    "slug": "images",
+    "title": "Images",
+    "description": "Responsive images with no optimizer to run — unpic for a CDN, imagetools for files in the repo."
+  },
+  {
+    "slug": "installation",
+    "title": "Installation",
+    "description": "From an empty directory to a streaming RSC app."
+  },
+  {
+    "slug": "introduction",
+    "title": "Introduction",
+    "description": "React Server Components as a Vite plugin, deployed wherever you like."
+  },
+  {
+    "slug": "mcp",
+    "title": "Working with an AI agent",
+    "description": "An MCP server that answers from your actual build, and the AGENTS.md written into every project."
+  },
+  {
+    "slug": "metadata",
+    "title": "Page metadata",
+    "description": "Titles, descriptions and Open Graph tags, exported from the page."
+  },
+  {
+    "slug": "navigation",
+    "title": "Navigation",
+    "description": "What happens when someone clicks a link, and why state survives it."
+  },
+  {
+    "slug": "no-javascript",
+    "title": "A page with no JavaScript",
+    "description": "Rendering a route to HTML and stopping there."
+  },
+  {
+    "slug": "offline",
+    "title": "Offline",
+    "description": "Knowing when the server cannot be reached, and carrying on without it."
+  },
+  {
+    "slug": "ppr",
+    "title": "Partial prerendering",
+    "description": "Storing what every visitor sees the same, and rendering the rest per request."
+  },
+  {
+    "slug": "pwa",
+    "title": "Progressive web apps",
+    "description": "Making the app installable, and adding push notifications and background sync."
+  },
+  {
+    "slug": "queries",
+    "title": "Queries",
+    "description": "Reading from the server over GET, and letting TanStack Query or SWR own everything above it."
+  },
+  {
+    "slug": "quick-start",
+    "title": "Quick start",
+    "description": "A running app in one command, or added to a project you already have."
+  },
+  {
+    "slug": "react-compiler",
+    "title": "React Compiler",
+    "description": "Enabling the compiler in the build."
+  },
+  {
+    "slug": "redirects",
+    "title": "Redirects",
+    "description": "Leaving a page from inside the render, and what that costs."
+  },
+  {
+    "slug": "response-headers",
+    "title": "Headers and cookies",
+    "description": "Setting response headers and cookies during a render."
+  },
+  {
+    "slug": "route-interception",
+    "title": "Route interception",
+    "description": "Opening a route as a modal over the page you were on."
+  },
+  {
+    "slug": "routing",
+    "title": "Routing",
+    "description": "File-based routes, layouts, loading states and parallel slots."
+  },
+  {
+    "slug": "sections",
+    "title": "Sections",
+    "description": "Refreshing one region of a page without re-rendering the rest."
+  },
+  {
+    "slug": "server-actions",
+    "title": "Server actions",
+    "description": "Calling the server from a client component, as an ordinary function."
+  },
+  {
+    "slug": "static-generation",
+    "title": "Static generation",
+    "description": "Rendering pages ahead of time, and exporting a site of files."
+  },
+  {
+    "slug": "testing",
+    "title": "Testing",
+    "description": "Three tiers, and the one thing that still needs a browser."
+  },
+  {
+    "slug": "third-party-scripts",
+    "title": "Third-party scripts",
+    "description": "Analytics, tag managers and widgets — and why there is no Script component."
+  },
+  {
+    "slug": "typed-routes",
+    "title": "Typed routes",
+    "description": "Links that fail the typecheck instead of the browser."
+  },
+  {
+    "slug": "url-validation",
+    "title": "Typed URLs",
+    "description": "Checking and typing params, query strings and request bodies with a schema you already write."
+  },
+  {
+    "slug": "validation",
+    "title": "Validation",
+    "description": "Surfacing server-side validation errors in a form."
+  },
+  {
+    "slug": "view-transitions",
+    "title": "View transitions",
+    "description": "What React's ViewTransition animates in an app built with this, and what it does not."
+  }
+]

package/guides/installation.md

@@ -0,0 +1,338 @@
+# Installation
+
+> From an empty directory to a streaming RSC app.
+
+There is no scaffolding command. An app is a Vite project with one plugin and
+one request handler, so this is the whole of it.
+
+## Create an app
+
+One command, and it asks the rest:
+
+```sh
+bun create rsc-kit@latest my-app
+```
+
+It asks where it will run (Bun, Node or Cloudflare Workers), whether you want the
+React Compiler and which implementation, and whether to include Tailwind. Every
+answer has a flag, so it also runs unattended:
+
+```sh
+bun create rsc-kit@latest my-app --host=bun --compiler=oxc --tailwind
+```
+
+What comes out builds, prerenders, typechecks and serves before you edit it.
+
+The rest of this page is for adding rsc-kit to an app you already have.
+
+## Install
+
+<PackageManagers pkg="@rsc-kit/core react react-dom" />
+
+<PackageManagers pkg="vite @vitejs/plugin-rsc @vitejs/plugin-react @types/react @types/react-dom" dev />
+
+`@rsc-kit/core` brings the Vite plugin, the render engine and the client
+runtime. React 19 and Vite 8 are peer dependencies — the versions the RSC build
+needs, not ones this package pins for you.
+
+<Aside type="note" title="What @vitejs/plugin-react is for">
+  Fast Refresh: edit a client component and React keeps its state, instead of
+  the page reloading and losing it. Put it *after* `rscKit()`.
+</Aside>
+
+## Configure Vite
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { nitro } from 'nitro/vite'
+import { rscKit } from '@rsc-kit/core/vite'
+
+/**
+ * The full route tree, built the way every scaffolded app is built.
+ *
+ * Nitro owns the server and the entry is generated — there is no server file
+ * in this directory, which is the point.
+ */
+export default defineConfig({
+  plugins: [
+    nitro({ preset: 'bun', serveStatic: 'inline' }),
+    rscKit({
+      sourceDir: 'src',
+      outDir: 'build',
+      viewTransitions: true,
+      offline: true,
+    }),
+    react(),
+  ],
+})
+```
+
+`sourceDir` is where your route tree lives. The defaults are plain Vite ones —
+`src/app` in, `dist/client` and `.rsc` out — so a project that adopts them can
+call `rscKit()` with nothing at all.
+
+<Aside type="note" title="Add your own plugins after it">
+  `rscKit()` includes `@vitejs/plugin-rsc`, which has to see modules before
+  any React layer transforms them. Tailwind, the React Compiler and anything
+  else go after it in the array.
+</Aside>
+
+## Write a root layout
+
+The root layout renders the **whole document** — there is no separate HTML
+template, and the build injects the bootstrap script and stylesheet links into
+what you return here.
+
+```tsx title="src/app/layout.tsx"
+import './styles.css'
+// Preloaded so the browser finds it before the stylesheet does. ?url is Vite's
+// and hands back the hashed path the build serves.
+import frauncesLatin from '@fontsource-variable/fraunces/files/fraunces-latin-full-normal.woff2?url'
+import type { ReactNode } from 'react'
+import { Nav } from '../components/Nav'
+import type { Metadata } from '@rsc-kit/core/metadata'
+
+export const metadata: Metadata = {
+  title: { template: '%s · rsc-kit', default: 'rsc-kit' },
+  description: 'React Server Components as a Vite plugin',
+  // Once, here. A share-card scraper needs an absolute image url, and this is
+  // what turns the opengraph-image.png in app/ into one.
+  metadataBase: new URL('https://example.rsc-kit.dev'),
+  openGraph: {
+    siteName: 'rsc-kit example',
+    type: 'website',
+  },
+  twitter: {
+    card: 'summary_large_image',
+    site: '@rsckit',
+  },
+}
+
+// `modal` is a parallel slot: the @modal directory beside this file fills it.
+// It renders alongside children, not instead of them.
+export default function RootLayout({ children, modal }: { children: ReactNode; modal?: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <link rel="preload" href={frauncesLatin} as="font" type="font/woff2" crossOrigin="anonymous" />
+      </head>
+      <body>
+        <Nav />
+        <main>{children}</main>
+        {modal}
+      </body>
+    </html>
+  )
+}
+```
+
+## Write a page
+
+```tsx title="src/app/page.tsx"
+export default function HomePage() {
+  return <h1>Hello</h1>;
+}
+```
+
+`app/page.tsx` serves `GET /`, wrapped in `app/layout.tsx`. Nothing registers
+it — the plugin reads the directory at build time. See
+[Routing](/guides/routing) for the rest of the conventions.
+
+## Serve it
+
+There is no server file to write. Nitro builds one around the route tree, and
+`npm run build` leaves it in `.output/`:
+
+```sh
+npm run build
+npm run start
+```
+
+Where it runs is the preset in `vite.config.ts` — see [Where it
+runs](/hosts/where-it-runs).
+
+## Scripts
+
+```json title="package.json"
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "start": "bun .output/server/index.mjs",
+    "compile": "bun build --compile .output/server/index.mjs --outfile my-app"
+  }
+}
+```
+
+`build` freezes every page it can, so there is no separate prerender step and
+no command for one — freezing runs the app, which needs the bundle the build
+just wrote, and only the build knows where that is. Turn it off with
+`rscKit({ prerender: false })`.
+
+`start` runs what the build wrote. There is no server file in a scaffolded app —
+Nitro builds the server around the route tree, and where it runs is a preset in
+`vite.config.ts`. See [Where it runs](/hosts/where-it-runs).
+
+`compile` produces a standalone binary containing the engine, the route tree,
+the frozen pages **and** the assets. That last part is `serveStatic: 'inline'`
+in the vite config; without it the binary serves pages and 404s every asset.
+
+<Aside type="note" title="Do not set NODE_ENV">
+  The build stamps its mode into the bundle, so `npm run start` is
+  production because it was *built* that way. Setting `NODE_ENV` yourself adds a
+  second source of truth that can disagree — and when it disagrees, every page
+  renders and none of them become interactive.
+
+  For a development build with React's real error messages, use
+  `vite build --mode development`.
+</Aside>
+
+Then:
+
+```bash
+npm run build   # bundles, and freezes every page it can
+npm run start
+```
+
+Worth adding a `typecheck` script beside them (`tsc --noEmit`) and running it
+in CI. Server components are ordinary functions and pages are ordinary
+modules, so the typechecker sees the whole route tree — a page whose props do
+not match its `[param]` segment is a compile error rather than a blank page.
+
+## TypeScript
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": [
+      "@types/bun",
+      "vite/client"
+    ]
+  },
+  "include": ["src/**/*", "server/**/*", ".rsc-kit/**/*", "vite.config.ts"]
+}
+```
+
+`vite/client` is doing real work in that list: without it a side-effect import
+of a stylesheet (`import './styles.css'` in the root layout) is an error, and
+`import.meta.env` is untyped.
+
+### Environment variables
+
+There is nothing to install and nothing this package adds — Vite already owns
+this. Two rules and one declaration.
+
+Anything named `VITE_*` is **inlined into the client bundle** and ships to the
+browser, whether or not a browser file reads it. Everything else stays on the
+server, read through `process.env`.
+
+The prefix is the whole boundary, so never put a secret behind it.
+`VITE_STRIPE_KEY` is a published key.
+
+Declare the ones you use, and Vite types them:
+
+```ts title="src/env.d.ts"
+interface ViteTypeOptions {
+  // Turns an unknown import.meta.env key into an error instead of `any`.
+  strictImportMetaEnv: unknown;
+}
+
+interface ImportMetaEnv {
+  readonly VITE_API_URL: string;
+}
+```
+
+<Aside type="caution" title="On Bun, a misspelled variable still compiles">
+  `@types/bun` declares its own `ImportMetaEnv`, which cancels out the strictness
+  Vite's option adds. You still get autocomplete and `string` instead of
+  `string | undefined` — but a typo is `any`, not an error.
+</Aside>
+
+#### When they are read
+
+`import.meta.env.VITE_*` is a literal in the bundle: changing one means a
+rebuild. `process.env.*` is a live read, so the deploy's environment wins —
+with one exception the build makes for you. A route that reads an environment
+variable and nothing request-bound is frozen at build time, value included,
+because nothing marked it as needing a request. That is the right answer for
+`PUBLIC_SITE_NAME` and the wrong one for a feature flag flipped per deploy. For
+the second kind, read it after `await connection()`, which keeps the route on
+the server. See [Static generation](/guides/static-generation).
+
+#### Validating them
+
+Vite checks the prefix and nothing else: a missing `DATABASE_URL` is
+`undefined` until the first query fails. There is nothing native for this
+because nothing native is needed — [t3-env](https://env.t3.gg/docs/core) works
+unchanged, with any Standard Schema validator:
+
+```ts title="src/env.ts"
+import { createEnv } from '@t3-oss/env-core';
+import { z } from 'zod';
+
+export const env = createEnv({
+  server: { DATABASE_URL: z.string().url() },
+  clientPrefix: 'VITE_',
+  client: { VITE_API_URL: z.string().url() },
+  runtimeEnv: typeof process === 'undefined' ? import.meta.env : { ...import.meta.env, ...process.env },
+  emptyStringAsUndefined: true,
+});
+```
+
+Read `env.DATABASE_URL` instead of `process.env.DATABASE_URL` and three things
+follow. It is a `string`, not `string | undefined`. A server variable touched
+from a client component throws by name rather than being silently `undefined`.
+And because the module validates when it is first imported, a missing variable
+fails the **build** — the prerender imports it — instead of the first request
+in production.
+
+The build writes its declaration files into `.rsc-kit/` at the project root,
+not among your own source. Three of them:
+
+- `rsc-routes.d.ts` — the routes it found, which is what makes `Link` and
+  `redirect()` [typed](/guides/routing#typed-links)
+- `rsc-env.d.ts` — the host global
+- `rsc-engine.d.ts` — the generated bundle
+
+Only what has to be generated is. Anything you can import, you import —
+[`Metadata`](/guides/metadata/) comes from the package and works before you have
+built anything.
+
+These are ambient, which needs only that they are inside the project and that
+the typechecker is told the directory exists:
+
+```json title="tsconfig.json"
+{ "include": ["src/**/*", ".rsc-kit/**/*"] }
+```
+
+A scaffolded app has that line, and `rsc-kit init` adds it. Leave it out and
+the build says so — otherwise typed routes fall back to plain `string` and
+nothing else would tell you.
+
+Add `.rsc-kit/` to `.gitignore`.
+
+## Where next
+
+<CardGrid>
+  <Card title="Routing" icon="ph:tree-structure">
+    [Pages, layouts, slots and navigation →](/guides/routing)
+  </Card>
+  <Card title="Server actions" icon="ph:lightning">
+    [Calling the server from a client component →](/guides/server-actions)
+  </Card>
+  <Card title="Static generation" icon="ph:snowflake">
+    [Rendering ahead of time, and exporting →](/guides/static-generation)
+  </Card>
+</CardGrid>