npm - @rsc-kit/mcp - Versions diffs - 0.14.0 → 0.16.0 - Mend

@rsc-kit/mcp 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

package/dist/answers.d.ts +7 -0
package/dist/answers.js +28 -0
package/dist/answers.js.map +1 -1
package/dist/bundleGuides.d.ts +27 -0
package/dist/bundleGuides.js +138 -0
package/dist/bundleGuides.js.map +1 -0
package/dist/index.js +21 -1
package/dist/index.js.map +1 -1
package/dist/recipes.js +138 -17
package/dist/recipes.js.map +1 -1
package/dist/report.d.ts +13 -0
package/dist/report.js +1 -1
package/dist/report.js.map +1 -1
package/guides/api-routes.md +168 -0
package/guides/authorization.md +288 -0
package/guides/caching.md +57 -0
package/guides/coming-from-next.md +151 -0
package/guides/connection.md +98 -0
package/guides/edge-caching.md +159 -0
package/guides/errors.md +109 -0
package/guides/file-uploads.md +119 -0
package/guides/fonts.md +117 -0
package/guides/forms.md +528 -0
package/guides/getting-started.md +132 -0
package/guides/images.md +83 -0
package/guides/index.json +187 -0
package/guides/installation.md +338 -0
package/guides/introduction.md +119 -0
package/guides/mcp.md +113 -0
package/guides/metadata.md +289 -0
package/guides/navigation.md +84 -0
package/guides/no-javascript.md +76 -0
package/guides/offline.md +215 -0
package/guides/ppr.md +181 -0
package/guides/pwa.md +260 -0
package/guides/queries.md +340 -0
package/guides/quick-start.md +99 -0
package/guides/react-compiler.md +153 -0
package/guides/redirects.md +143 -0
package/guides/response-headers.md +66 -0
package/guides/route-interception.md +206 -0
package/guides/routing.md +458 -0
package/guides/sections.md +74 -0
package/guides/server-actions.md +444 -0
package/guides/static-generation.md +347 -0
package/guides/testing.md +158 -0
package/guides/third-party-scripts.md +105 -0
package/guides/typed-routes.md +139 -0
package/guides/url-validation.md +143 -0
package/guides/validation.md +175 -0
package/guides/view-transitions.md +120 -0
package/package.json +4 -3

package/guides/static-generation.md ADDED Viewed

@@ -0,0 +1,347 @@
+# Static generation
+> Rendering pages ahead of time, and exporting a site of files.
+Pages that do not need the request can be rendered once, at build time, and
+served from disk — no render per request, no round trip to a database.
+## The build decides by rendering
+Nothing declares whether a route is stored. The build renders each one with a
+budget and watches what happens:
+| Outcome | What the probe saw |
+| --- | --- |
+| The whole page | It rendered to completion. Stored and served from disk. |
+| A shell | Something was still waiting when the budget expired, but the static parts had painted. The shell is stored; the rest is rendered per request. |
+| A redirect | The route only redirects, so the redirect itself is stored — status and location. |
+| Refused | Nothing painted before the page blocked. The build fails. |
+The budget is 2 seconds, and `RSC_PPR_TIMEOUT_MS` changes it. A page whose data
+resolves inside it is stored whole — including one that called `fetch()`, as
+long as the answer arrived.
+There is no way to opt out, and that is the point: a route the build cannot
+store has its boundary in the wrong place. Put the part that waits inside
+`<Suspense>`, or add a `loading.tsx` beside the page, and it becomes a shell.
+<Aside type="caution" title="Stored means stored">
+  Whatever a page read at build time is in the file. If it should reflect the
+  current state of the world on every request, it needs to read the request —
+  `params`, `searchParams`, `headers()`, `cookies()` — which suspends, and puts
+  it behind a boundary rather than in the stored bytes.
+</Aside>
+## Listing the URLs of a parameterised route
+A route with a `[param]` cannot be frozen unless something says which values
+exist. Export `generateStaticParams` from the page:
+```tsx title="src/app/direct/[slug]/page.tsx"
+import { Suspense } from 'react'
+import { allSlugs, findPost, SECRET } from '../../../data'
+import type { Metadata } from '@rsc-kit/core/metadata'
+// Which urls exist. The one thing the build cannot work out for itself — and
+// the reason this route is frozen per url, while /posts/[slug], which declares
+// nothing, is frozen once as a shell.
+export function generateStaticParams() {
+  return allSlugs().map((slug) => ({ slug }))
+}
+export const metadata: Metadata = { title: 'Direct import' }
+async function Body({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  const post = await findPost(slug)
+  // Referenced so the bundler cannot tree-shake the module away — the point is
+  // that it is in the server graph and not the client one.
+  const proof = SECRET.length
+  if (!post) return <h1>No such post: {slug}</h1>
+  return (
+    <>
+      <h1>{post.title}</h1>
+      <p>{post.body}</p>
+      <p className="muted">secret length on the server: {proof}</p>
+    </>
+  )
+}
+export default function DirectPage({ params }: { params: Promise<{ slug: string }> }) {
+  return (
+    <Suspense fallback={<p className="muted">Loading…</p>}>
+      <Body params={params} />
+    </Suspense>
+  )
+}
+```
+Each object it returns is one URL to build. For a route with several params,
+return every combination:
+```tsx title="src/app/blog/[year]/[slug]/page.tsx"
+export function generateStaticParams() {
+  return [
+    { year: '2025', slug: 'hello-world' },
+    { year: '2025', slug: 'getting-started' },
+  ];
+}
+```
+A route that lists nothing is rendered on demand. That is a decision, not a
+failure — `/posts/[slug]` in the example app declares no params precisely so
+the two paths can be compared side by side.
+## Running the prerender
+`vite build` does it, at the end, once every bundle exists — prerendering is
+the app rendering itself, so it needs the thing the build just produced.
+```bash
+bun run build
+#  ○  /
+#  ○  /about
+#  ◔  /account
+#
+#  2 stored, 1 shell
+```
+### Turning it off
+```ts title="vite.config.ts"
+rscKit({ sourceDir: 'src', prerender: false });
+```
+**Try [`connection()`](/guides/connection) first.** It is almost always the
+better answer, and this is almost always too big a hammer.
+Prerendering **runs your application code**, so it needs whatever that code
+needs — a page that queries a database needs that database reachable from the
+build. When it is not, marking that one query is a smaller and more accurate
+statement than switching prerendering off for every route in the app:
+```tsx
+await connection()
+const rows = await db.query('select * from orders')
+```
+The build then skips that work, stores everything around it, and the page still
+gets a shell. Turning prerendering off stores nothing, anywhere, and every page
+renders for every visitor forever.
+Reach for this switch when the reason is about the *build itself* rather than
+any page:
+Two other reasons: a large site adds real time to every build, and a deploy
+that has to run migrations first may want to prerender at a later stage
+entirely. `RSC_PRERENDER=0` does the same thing for a host that drives the
+build out of process and cannot pass an option.
+It is off in watch mode regardless — a rebuild on every keystroke that also
+re-renders every route is not a feedback loop anyone wants.
+### Doing it yourself
+`prerender` is also a plain function, exported from `@rsc-kit/core/prerender`,
+so it runs wherever your build does. `write` is a callback rather than a
+directory, because not every place this runs has a filesystem — `writeTo` is
+the `node:fs` implementation of it, and a platform without one passes its own.
+You should not need it. The build calls it for you, with the engine bundle it
+just produced — a path only the build knows, since Nitro builds the rsc
+environment under `node_modules`.
+## What gets written
+Per route, keyed by its URL — `/` becomes `index`, `/docs/install` becomes
+`docs/install`:
+| File | For |
+| --- | --- |
+| `{key}.html` | A full page load. |
+| `{key}.flight` | An SPA navigation that replaces the whole document. |
+| `{key}.seg1.flight`, `{key}.seg2.flight`, … | An SPA navigation that keeps that many layouts. |
+| `{key}.meta.json` | The client chunks and build version the payload belongs to. |
+| `{key}.ppr.html` | A shell, stored per route *pattern* rather than per URL. |
+The `.seg{n}` variants are what make a prerendered route participate in partial
+navigation. Without them every arrival at a frozen page would replace the
+document root, unmounting the pages retained behind it — the form you were
+filling in would not survive going back to it.
+## Serving them
+The host checks for a frozen file before it matches a route. `prerendered` is
+the source it checks, and like `write` it is a callback:
+The generated server does this for you: the build freezes pages into
+`.output/server/rsc-static`, and the entry reads them from beside itself.
+Nothing found, and the request falls through to a live render.
+## A value that must not be frozen
+A stored page keeps whatever it rendered, which includes whatever the clock
+said at build time. So this renders once, during the build, and serves that
+same instant to everyone until the next one:
+```tsx
+export default function Page() {
+  // Frozen. Not "a few seconds stale" — the moment your CI ran.
+  return <p>Rendered at {new Date().toISOString()}</p>;
+}
+```
+The build says so rather than leaving you to notice:
+```
+○  /
+   ⚠  froze new Date() — a stored page keeps whatever that returned at build
+      time. If it should differ per visitor, await connection() so the page
+      renders per request; if only the browser needs it, use(browser()) keeps
+      it out of the build entirely.
+```
+`new Date()`, `Date.now()`, `Math.random()` and `crypto.randomUUID()` are all
+watched.
+<Aside type="caution" title="Suspense alone does not fix this">
+  Wrapping it in a boundary changes nothing: prerendering renders straight
+  through a component that never awaits, so the value is captured exactly as
+  before — same `○`, same warning. A boundary becomes a hole only when
+  something inside it *waits* for what the build cannot finish — a read that
+  outlasts the build's budget, or a page that has said `await connection()`.
+</Aside>
+Moving it into a client component makes it worse, not better. Hydration is not
+React attaching handlers to existing markup — it *runs* the component, because
+that is the only way it learns what the tree should be.
+So the body executes twice, once where the HTML came from and once in the
+browser, and a clock read inside gives two different answers.
+Where the value comes from is what decides it, not whether the component is a
+client one:
+| the value is | result |
+| --- | --- |
+| read in a server component | frozen at build time, and the build warns |
+| read in a client component's body | produced twice, and the two disagree |
+| computed on the server, passed as a prop | travels in the payload, so both renders read the same string |
+| read only in the browser | nothing on the server to disagree with |
+The third row is the ordinary answer for anything the server can decide. It
+does hydrate the client component, and there is no mismatch, because the value
+arrived rather than being recomputed. It is still frozen with the page, which
+is fine for a build stamp and wrong for a clock.
+## Rendering something in the browser only
+For a value that is genuinely per-visitor and needs no server — a clock,
+`localStorage`, a map, an editor — say so, and React will skip the component on
+the server:
+```tsx
+'use client';
+import { Suspense, use, useState } from 'react';
+import { browser } from 'react-dom';
+function SavedDraft() {
+  use(browser('the draft lives in localStorage'));
+  const [draft] = useState(() => localStorage.getItem('draft') ?? '');
+  return <p>{draft || 'Nothing saved yet'}</p>;
+}
+```
+The page it sits on stays frozen at build time. React stops the server render
+at that component and puts the nearest Suspense boundary's fallback into the
+HTML; everything around it rendered normally, so there is still a finished
+document to store.
+```tsx
+<Suspense fallback={<p>Loading draft…</p>}>
+  <SavedDraft />
+</Suspense>
+```
+That fallback is what visitors see in the first paint, and the real thing
+replaces it once the browser renders. There is no mismatch to have, because
+only one side ever ran.
+Three things to know:
+- **The Suspense boundary is required.** Without one, the server render fails
+  rather than degrading.
+- **It has to be a client component.** `browser()` is about skipping the server
+  render of something that will render in the browser; a server component has
+  no browser render to fall back to.
+- **`browser()` alone does nothing.** Pass it to `use()`. Do not throw it.
+The `reason` is optional and only ever read on the server, where it shows up in
+the renderer's bailout callback. Give it one anyway — it is the sentence the
+next person needs. Pass a function if building it is expensive.
+<Aside type="note" title="This replaced a workaround">
+  The old answer was an empty first render plus a `useEffect`, which worked by
+  making both renders agree on nothing. `browser()` lands the same outcome with
+  the fallback in the HTML instead of a blank, and says in the component why.
+  It is in `react-dom` 19.3.
+  This package ships no `ClientOnly` of its own, and now never will — the
+  boundary was always React's to draw.
+</Aside>
+## Exporting a site
+Build with `output: 'export'` and the build writes a directory a static host
+can serve with no origin at all:
+```bash
+RSC_OUTPUT=export npm run build
+# Exported 9 pages to dist
+```
+It refuses unless every route came out static. A shell on a static host is a
+page that loads and then stays empty forever, because there is nothing running
+to fill it in. `RSC_EXPORT_FORCE=1` writes the site anyway and reports what it
+left out, which is how you move an app towards being exportable.
+A route that only redirects is written as a meta refresh, which is the one
+redirect every static host performs without being configured.
+## Customising the document
+There is no separate shell template. The root `layout.tsx` renders the whole
+document, and the build injects the bootstrap script and stylesheet links into
+it. The same layout serves streamed and frozen pages.
+```tsx title="src/app/layout.tsx"
+import './styles.css';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+<Aside type="tip" title="Fonts and global CSS belong in the root layout">
+  The root layout renders once and survives every SPA navigation, so its
+  `<link>` tags load a single time. The same tags in a nested layout or a page
+  are re-injected on every navigation.
+</Aside>
+Per-page titles and meta tags come from the page, not the layout — see
+[Page metadata](/guides/metadata).

package/guides/testing.md ADDED Viewed

@@ -0,0 +1,158 @@
+# Testing
+> Three tiers, and the one thing that still needs a browser.
+Almost everything here is a function, and functions are tested by calling them.
+Any test runner works — Bun's, Vitest, Jest — because nothing below needs a
+runtime of ours. The examples use `bun:test`.
+## Actions, queries and api routes are functions
+`"use server"` is a directive for the bundler. In a test file it is a string, and
+the function it marks is importable:
+```ts title="tests/actions.test.ts"
+import { placeOrder } from '../src/actions'
+import { getListings } from '../src/queries'
+test('placeOrder accepts an item', async () => {
+  expect(await placeOrder('a rubber duck')).toEqual({ ok: true })
+})
+test('getListings answers with a list', async () => {
+  expect(await getListings('stay')).toBeInstanceOf(Array)
+})
+```
+An action built on the [action client](/guides/authorization/) runs its whole
+middleware chain when called, so a check that refuses a stranger is testable by
+calling it as one. It **returns** its failures, so assert on the result:
+```ts
+const result = await createPost({ title: '' })
+expect(result.validationErrors).toEqual({ title: ['too short'] })
+```
+An api route is the same. Hand it a `Request` and the context the engine would:
+```ts title="tests/api.test.ts"
+import { GET } from '../src/app/api/greet/[name]/route'
+test('greets by name', async () => {
+  const res = await GET(new Request('https://app.test/api/greet/ada'), {
+    params: Promise.resolve({ name: 'ada' }),   // a promise, as the engine gives it
+  })
+  expect(await res.json()).toEqual({ greeting: 'Hello, ada' })
+})
+```
+:::note[This is more than Next offers]
+Next's advice for server actions is end-to-end, because the interesting part
+there is the round trip. Here the function *is* the interesting part — the
+validation, the middleware, the authorisation — and it is a unit test.
+:::
+### Reading the request
+`cookies()`, `headers()` and the rest read from a scope the host opens per
+request. In a test there is no host, so open it yourself:
+```ts title="tests/session.test.ts"
+import { withRequest } from '@rsc-kit/core/request'
+import { currentUser } from '../src/session'
+test('a signed-in cookie is a user', async () => {
+  const user = await withRequest(
+    new Request('https://app.test/', { headers: { Cookie: 'session=abc' } }),
+    currentUser,
+  )
+  expect(user?.name).toBe('Ada')
+})
+test('and no cookie is nobody', async () => {
+  expect(await withRequest(new Request('https://app.test/'), currentUser)).toBeNull()
+})
+```
+The scope is per call, so two requests in flight in the same test do not see
+each other's cookies.
+## The whole app, as it is deployed
+The tier between a function and a browser, and the one that is ours to offer:
+the app as `Request → Response`, through the real router, the real middleware,
+the real api routes and the pages the build stored — with no port and no
+process.
+```ts title="tests/app.test.ts"
+import { createTestApp } from '@rsc-kit/core/testing'
+const app = await createTestApp()
+test('a stored page is served', async () => {
+  const res = await app.fetch('/orders')
+  expect(res.status).toBe(200)
+})
+test('a guarded page turns a stranger away', async () => {
+  const res = await app.fetch('/admin', { redirect: 'manual' })
+  expect(res.status).toBe(307)
+  expect(res.headers.get('Location')).toBe('/login')
+})
+test('a method a route does not export is 405', async () => {
+  const res = await app.fetch('/api/health', { method: 'DELETE' })
+  expect(res.headers.get('Allow')).toContain('GET')
+})
+```
+This is where a route that renders fine and is served wrong shows up: a guard
+that never ran, a stored page that should not have been, a `404` that came back
+`200`.
+`createTestApp()` builds when your source is newer than the last build, and not
+otherwise — the first run pays for it, the rest do not, and an edit is picked
+up. It runs your own `vite build`, so what is tested is what ships. Pass
+`{ build: false }` in a ci step that already built.
+One build and one loaded module per test run, shared across files. That is both
+the fast path and the correct one: two copies of the server bundle in one
+process would be two client-reference registries.
+## Components
+`<Form>`, `useField`, `useOnline` and the rest are client components. Test them
+with React's own tools and any DOM — the package's own suite uses `happy-dom`
+with `react-dom/client` and `act`, and so can yours. Testing Library works the
+same way.
+## What still needs a browser
+One thing: **a server action called over the wire.** The function is testable
+directly, and every url is testable through `createTestApp()` — but the wire
+call carries an id that React keeps private, so a test holding the source
+function cannot address the built one.
+That is the same limit Next has, and it is narrower here: it is the encoding of
+one round trip, not the action. Everything the action *does* is a unit test
+above. For the round trip itself, and for anything that depends on hydration —
+`useField` re-rendering, a navigation, an optimistic update reverting — use
+Playwright against `vite preview`, which serves the real build.
+## What to test where
+| what | how |
+| --- | --- |
+| an action's logic, validation, middleware | call it |
+| a query | call it |
+| an api route | call `GET`/`POST` with a `Request` |
+| anything that reads cookies or headers | `withRequest()` |
+| routing, guards, stored pages, status codes | `createTestApp().fetch()` |
+| a client component | React + a DOM |
+| an action over the wire, hydration, navigation | Playwright |

package/guides/third-party-scripts.md ADDED Viewed

@@ -0,0 +1,105 @@
+# Third-party scripts
+> Analytics, tag managers and widgets — and why there is no Script component.
+Write the tag. React 19 does the rest, and it does the parts Next's `<Script>`
+component existed for.
+## An external script
+```tsx title="src/app/layout.tsx"
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <script async src="https://www.clarity.ms/tag/abc123" />
+      </body>
+    </html>
+  )
+}
+```
+Rendered from a server component, React **hoists** it into `<head>` and
+**deduplicates** it — render the same `src` in three components and one tag
+goes out. `async` means it never blocks the page. That is `afterInteractive`,
+without an import.
+## An inline snippet
+Most analytics ship one — a few lines that stub a global and load the real
+thing:
+```tsx title="src/app/layout.tsx"
+<script
+  id="ms-clarity"
+  dangerouslySetInnerHTML={{
+    __html: `(function(c,l,a,r,i,t,y){c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+      t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+      y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
+    })(window, document, "clarity", "script", "abc123");`,
+  }}
+/>
+```
+It renders where you wrote it and runs during parse, **before hydration**. For
+a snippet whose job is to start recording as early as possible, that is the
+earlier of the two moments and the one its authors intended. Next's
+`Script` with `strategy="afterInteractive"` would have made it later.
+:::note[Put it in the root layout]
+The root layout renders once and is kept across navigations, so the snippet
+runs once. In a *page*, a client-side navigation to it re-renders the tag, and
+whether the browser runs a script inserted that way is not something to rely on
+either way. Site-wide scripts go in the layout; that is where they belong
+anyway.
+:::
+## Porting from Next
+| Next's `Script strategy` | here |
+| --- | --- |
+| `beforeInteractive` | `<script src>` without `async` — the browser blocks on it, which is what that strategy meant |
+| `afterInteractive` | `<script async src>`, or the inline snippet above |
+| `lazyOnload` | the effect below, inside `requestIdleCallback` |
+| `worker` | not supported — that was Partytown, a separate project |
+The `id` prop carries across unchanged. `onLoad` and `onReady` are the one
+thing that needs a component, because they need to run in the browser:
+## When a script has to run after hydration
+Rare, and specific: a script that touches DOM React rendered, and would find it
+missing if it ran during parse. A ten-line client component covers it, and it is
+yours rather than ours because there is nothing to abstract:
+```tsx title="src/components/AfterHydration.tsx"
+'use client'
+import { useEffect } from 'react'
+export function AfterHydration({ src, onLoad }: { src: string; onLoad?: () => void }) {
+  useEffect(() => {
+    const tag = document.createElement('script')
+    tag.src = src
+    tag.async = true
+    if (onLoad) tag.onload = onLoad
+    document.head.append(tag)
+    return () => tag.remove()
+  }, [src, onLoad])
+  return null
+}
+```
+Wrap the body in `requestIdleCallback` and it is `lazyOnload`.
+## Why nothing ships for this
+A `Script` component would be a wrapper around a `script` tag whose two
+useful behaviours — hoisting and deduplication — React already provides. The
+package's own tests pin that React does, so the day it stops, this page is
+what changes rather than your app.