@rsc-kit/mcp 0.18.1 → 0.19.0

package/dist/recipes.js

@@ -15,8 +15,15 @@
 const RECIPES = [
     {
         topic: 'forms',
-        summary: 'Submitting to a server action, with pending state and field errors',
-        body: `Use <Form>. It takes the server action itself, not a url.
+        summary: 'Submitting to a server action, with pending state and field errors. Uncontrolled by default - no useState per field',
+        body: `THE RULE: forms are UNCONTROLLED. Inputs keep their value in the DOM,
+an initial value is defaultValue, the action reads FormData. Do NOT write
+useState + value/onChange per input, and do NOT reach for TanStack Form.
+Control ONE field only when the UI must react as the user types (a character
+count, a live preview, a dependent select) - bind it with useField, which
+scopes the re-render to that field. Everything else stays uncontrolled.
+
+Use <Form>. It takes the server action itself, not a url.
 
 \`\`\`tsx
 'use client'
@@ -564,17 +571,31 @@ build found:
     import { apiUrl } from '@rsc-kit/core/routes'
     await fetch(apiUrl('/api/posts/' + id))
 
-Pages and api routes are separate unions: Link refuses an api url, apiUrl
-refuses a page. It checks the PATH, not the response type - for types across
-the boundary use a server action or a query, where the return type is the
-function's because it is the same function.
+A route.ts is a Route too (type Route from '@rsc-kit/core/routes' covers pages
+AND route.ts files, as Next's does): Link, visit and redirect accept it. The
+client treats a link to a route as an anchor - never prefetched, a full
+navigation, not a payload fetch. ApiRoute is the narrower union for apiUrl:
+apiUrl refuses a page, because fetching one gets html. It checks the PATH, not
+the response type - for types across the boundary use a server action or a
+query, where the return type is the function's because it is the same function.
 
 They run their directory's \`middleware.ts\`, so an endpoint under a guarded
 path is guarded.
 
 A \`GET\` that reads nothing from the request is answered from disk. Awaiting
 \`searchParams\` says the answer depends on the query; never touching it means
-the stored answer is served for any query at all.
+the stored answer is served for any query at all. NEVER read the query with
+new URL(request.url).searchParams (the Next way): the build cannot see that
+read, and reading request.url at all makes the route dynamic (the table says
+"reads the request - url"). A webhook verification handshake (hub.mode,
+hub.challenge) reads the awaited searchParams. A GET that answers 4xx/5xx to
+the build is never stored either (the table says "answered 403 to the build").
+
+redirect() thrown from a handler is the route's answer: a real 3xx Location
+for whoever asked (a signed-url export, a moved endpoint); notFound() is its
+404. A guard's redirect above a route.ts is a refusal: a browser that
+navigated there gets the Location, code that fetched it gets 401 +
+X-RSC-Redirect (fetch would follow a Location and hand back the login page).
 
 Exporting a \`body\` schema consumes the stream, so \`request.json()\` inside the
 handler will find it already read. Use the parsed value.
@@ -622,7 +643,7 @@ opts out, and the accessors are async:
 \`\`\`ts
 import { cookies, headers, searchParams, connection } from '@rsc-kit/core/request'
 
-const theme = (await cookies()).get('theme')
+const theme = (await cookies()).get('theme')?.value   // { name, value } | undefined, as in Next
 await connection()   // "render this per visitor", said deliberately
 \`\`\`
 
@@ -758,6 +779,61 @@ scores 99. Three moves:
    range you ask for (font-weight: 400 500) so nothing requests a missing file.
 Put the preloads before the <style> with the faces. Measured on rsc-kit.dev:
 Speed Index 1.7s to 0.9s, 99 to a steady 100, fonts 114 kB to 74 kB.
+THE RULE: a font never blocks the page - text paints in the fallback before
+the web font arrives. Three ways to break it, all avoided: a fonts.googleapis
+<link> (render-blocking CSS from a cold origin - self-host via Fontsource
+instead), font-display: block or unset (invisible text for up to 3s - every
+rule says swap or optional), preloading every file (preload only what the
+first paint needs).
+
+AFTER THE ANSWER: after(() => sendEmail(user)) from @rsc-kit/core/request
+queues work to run once the response is on its way - from an action, a
+component, middleware or an api route. Do NOT use a detached promise: on a
+Worker the isolate dies with the response unless work is handed to
+waitUntil, which after() does; on a process it runs detached. Rejections
+are logged, never surfaced.
+
+WRITE THE SCHEMA FOR THE SHAPE IT WANTS. The form is read the way the schema
+means it, on both sides (Zod 4 / ArkType describe themselves as JSON Schema;
+Valibot not yet - its values arrive as strings):
+  notify: z.boolean()             // unchecked posts nothing -> false; "on" -> true
+  limit:  z.number().int()        // "5" -> 5. NOT z.coerce.number()
+  tags:   z.array(z.string())     // one -> ['a'], none ticked -> []
+  policy: z.string().optional()   // hidden behind a switch -> absent when off
+  + .refine((s) => !s.notify || s.policy) for "required when the switch is on"
+Nested names nest: fields[0][name] / fields[0].name -> { fields: [{ name }] };
+auth[kind] picks a discriminated union's branch. No per-checkbox transform,
+no checkbox() helper. The action decodes the same object the form validated.
+Offline (rscKit({ offline: true })): the precache is what boots the app - js,
+css, fonts, manifest, icons, / and /offline with their boot payloads; images,
+wasm and the share card are cached on first use. A frozen page never visited
+falls back to /offline like any other navigation. Do not add a second service
+worker or a precache list; app/sw.js is importScripts'd into this one.
+
+An action that redirect()s RESOLVES with { redirected: '/where' } on the
+client once the navigation starts - it does not throw, so a plain
+startTransition(async () => await logOut()) needs no catch (a rejection
+there unmounts the root). The result is always an object (exactly one of
+data / validationErrors / serverError / redirected is set), so reading any
+field of it is safe. Do NOT wrap actions in a hook to catch
+ServerRedirectError; nothing throws.
+
+Before hydration a submit is a native POST to the page's url (React's hidden
+$ACTION_ fields); the host runs the action and re-renders the page with the
+result seated in the <Form> that posted - a refusal shows on its fields
+without javascript; a redirect() is followed, a cookie lands. Nothing to
+configure; <Form> uses useActionState under a wrapper so the action keeps
+its (formData) signature.
+A blank control is absent for any optional field (z.email().optional()
+accepts it; an optional union is not read as its first branch) and "" for a
+required one (z.string().min(1) refuses it). A leaf
+with no JSON Schema (z.date()) arrives as posted; its siblings still coerce.
+<Form ref={...}> is fine: the caller's ref is filled beside the form's own.
+Render props also carry dirty (anything differs from mount, uncontrolled
+fields included; baseline moves on a successful submit; reset() clears it):
+{({ dirty, reset }) => <Button disabled={!dirty}>Save</Button>} - the RHF
+isDirty gate for Save/Discard.
+
 Full guide: read_guide({ slug: 'fonts' }).`,
     },
     {
@@ -780,15 +856,23 @@ IMPORTS
   Metadata                     -> @rsc-kit/core/metadata (metadataBase, openGraph, twitter, icons as-is)
   app/robots.ts, app/sitemap.ts -> the same files and shapes; app/llms.ts beside them (how_to seo-files)
   middleware.ts subdomain rewrite -> nothing: a host is a route segment (how_to domains)
+  flags/next (Vercel Flags SDK) -> unchanged: the build aliases next/headers to @rsc-kit/core/request
+                                  (how_to feature-flags); precompute() does not carry over
   next/font                    -> Fontsource (how_to fonts)
   next/image                   -> unpic or vite-imagetools (how_to images)
   next/script                  -> a <script> tag (how_to scripts)
   NEXT_PUBLIC_*                -> PUBLIC_* in src/env.ts (how_to env); server vars typed there too
+  import 'server-only'         -> keep it (the build honours it). Under bun test the real package throws on
+                                  import, so the scaffold's tests/preload.ts stubs it: bunfig.toml
+                                  [test] preload = ["./tests/preload.ts"], mock.module('server-only', () => ({})).
+                                  A project without those two files adds them before unit-testing an action.
   next-safe-action             -> createActionClient() (how_to action-client); returnValidationErrors -> return fieldErrors({...})
   cache from 'react'           -> cache from @rsc-kit/core/cache: React's dedupes only inside a render; this one
                                   spans the request (guards, actions, api routes). The build names files still on React's
   @react-email/render, renderToString in an action -> the same call, in a module that starts with "use ssr"
+                                  (the build warns naming the app file and the package; the stub throws when called)
                                   (how_to emails). Next gets away with it only for externalised packages; here it is explicit
+  import type { Route } from 'next' -> import type { Route } from '@rsc-kit/core/routes' (pages AND route.ts; a link to a route.ts is an anchor, never prefetched)
 
 DIFFERENT ON PURPOSE
 - No export const dynamic / revalidate = 60. A page is frozen unless it READS
@@ -798,7 +882,9 @@ DIFFERENT ON PURPOSE
 - Actions return failures ({ validationErrors }, { serverError }), not throw.
 - No image optimizer, no opengraph-image.tsx - put opengraph-image.png in src/app.
 - Tests need no browser: createTestApp() is the deployed handler. It builds
-  with the project's own build script on the runtime the tests run under.
+  with the project's own build script on the runtime the tests run under, and
+  answers files the build wrote to .output/public (assets, sw.js, the
+  manifest, icons) as production does - app.fetch('/sw.js') is a real test.
 - A component library (base-ui, Radix) imports as it did, from server
   components too. A shadcn-style components/ui/ folder keeps "use client" at
   the top of each file, as shipped; without it the server evaluates the
@@ -815,7 +901,40 @@ route that is not ○ names what streams and from which component (a cookies()
 in a layout reaches every page; the build says so) -> decide each action the
 build lists as running no middleware -> check.
 
+CONVERT THE FORMS AND ACTIONS - do not carry them. useActionState +
+useFormStatus, react-hook-form, TanStack Form and useState-per-input all
+still COMPILE here, which is why a port leaves them. Each becomes
+<Form action={…} schema={…}> (how_to forms) and a createActionClient()
+handler (how_to action-client). Remove the form library when the last form
+is converted. A port that keeps two form systems has ported nothing.
+
 Full guide: read_guide({ slug: 'coming-from-next' }).`,
+    },
+    {
+        topic: 'feature-flags',
+        summary: "Vercel's Flags SDK (flags/next) runs unchanged: next/headers is answered by headers()/cookies() here",
+        body: `bun add flags. Then flags/next as written for Next:
+
+  import { flag, dedupe } from 'flags/next'
+  const visitor = dedupe(async ({ cookies, headers }) => ({ id: cookies.get('visitor')?.value ?? 'anon' }))
+  export const showBanner = flag<boolean, { id: string }>({ key: 'show-banner', identify: visitor, decide: ({ entities }) => entities?.id === 'ada' })
+
+  // page.tsx (server component)
+  const on = await showBanner()
+
+The build aliases next/headers to @rsc-kit/core/request - same names, same
+shapes (cookies().get(name)?.value), one object per request, which the SDK's
+dedupe keys on. Nothing to configure, no shim to write.
+
+A flag reads the request, so the page renders per visitor: put a <Suspense>
+or loading.tsx above the read and the build stores the rest as a shell (the
+table says "headers() in run, cookies() in run stream per request").
+
+Discovery endpoint: a route.ts -
+  export const GET = createFlagsDiscoveryEndpoint(async () => getProviderData(flags))
+  export const openapi = false
+precompute() does NOT carry over (it rewrites urls in Next middleware); read
+the flag in the page.`,
     },
     {
         topic: 'emails',
@@ -1024,6 +1143,15 @@ Laravel: composer require rsc-kit/laravel, then php artisan rsc:install. It
 runs rsc-kit init, which writes ONE vite.config.ts (laravel-vite-plugin is
 moved aside - the renderer owns the frontend). Source is resources/js (the route tree is resources/js/app).
 
+rpc() is a global the renderer installs in its own process (never imported,
+never in the browser bundle): one POST to the backend's host-call endpoint
+with { function, args }, the secret and the visitor's cookie; the answer is
+the return value as JSON, typed by rpc<T>(). Refusals arrive as their kind
+(422/401/403/redirect), never a 500; sibling calls in one tick are batched
+and each resolves the moment the backend answers it.
+A BAP server bundle carries no database driver, ORM or auth library - the
+backend owns those.
+
 Reach PHP from a server component - rpc() is a global, typed in
 .rsc-kit/rsc-env.d.ts, server render only:
 
@@ -1040,12 +1168,23 @@ Guard a route in Laravel's vocabulary, no route declared in PHP:
   // resources/js/app/admin/middleware.ts
   export const middleware = ['auth', 'verified', 'can:update,post']
 
+Make one: php artisan make:rsc-action Orders --method=cancel --auth
+--can=update,Order --middleware=throttle:60,1 --revalidate=orders (--rpc for
+an rpc() class under app/Rsc; no --method = invokable). Do NOT hand-write the
+attributes from memory; the command writes the ones the registry reads.
 Server actions are classes in app/Rsc/Actions; \`php artisan
 rsc:action-manifest\` (already in the dev/build scripts) writes the map and
 the build writes server-actions.generated.ts beside the app - import
 ordersCancel from it in a client component. Rsc::revalidate('orders') in the
 action returns the re-rendered region with the answer.
 
+Per url: if the React tree has it, React renders it, otherwise Laravel does
+- including / : the welcome route in routes/web.php answers nothing while
+resources/js/app/page.tsx exists (the package registers the tree's urls from
+bootstrap/rsc/vite/routes.json after routes/web.php). Do NOT tell the user
+to delete the welcome route to make the page show; do not add Laravel routes
+for React pages.
+
 php artisan serve is one worker, which deadlocks the proxy - unless
 PHP_CLI_SERVER_WORKERS=4 in .env AND serve --no-reload (Laravel ignores
 the variable otherwise). Herd, Valet, FPM, Octane are fine as they are. Production: put the renderer in front (bun
@@ -1055,10 +1194,13 @@ the web server.
 Any other language implements the same endpoint - request { function, args },
 reply { result | validationErrors | unauthenticated | unauthorized | redirect
 | error, revalidate }, answers '__rsc.middleware' with true or a refusal, and
-a batch { calls: [...] } with { replies: [{ status, ...reply }] } in order.
-Calls issued in the same render tick travel as one batch, so parallel reads
-are one backend request; the renderer falls back to single calls for a
-backend without batches.
+a batch { calls: [...] } as application/x-ndjson - one line per call AS IT
+FINISHES, { index, status, ...reply }, in any order, flushed each time
+(X-Accel-Buffering: no) - or, less good, one JSON { replies: [...] } in
+order (every call then waits for the slowest). Calls issued in the same
+render tick travel as one batch, so parallel reads are one backend request
+and a fast read still resolves while a slow sibling runs; the renderer falls
+back to single calls for a backend without batches.
 
 Full guides: read_guide({ slug: 'backend-answered-pages' }), read_guide({ slug: 'laravel' }), read_guide({ slug: 'go' }), read_guide({ slug: 'your-own-backend' }).`,
     },
@@ -1113,6 +1255,15 @@ Native dependencies (sharp, bcrypt, better-sqlite3, @prisma/client, puppeteer,
 .output/server/node_modules with their binaries. Add one:
 rscKit({ serverExternalPackages: ['@acme/native'] }). Same as Next's option.
 
+The other direction: a dependency with "use client" files that does NOT
+declare react as a peerDependency (generated wrappers, workspace packages
+with react under dependencies) would be left external by plugin-rsc and its
+directive never read - hooks then run on the server. The build detects direct
+dependencies in that state and bundles them, printing
+"[rsc-kit] bundling <pkg>: it has "use client" files but does not declare
+react as a peer dependency". Nothing to configure; fix the package's
+peerDependencies when it is yours.
+
 Bun's, not the framework's: bun test loads the package .env (use
 --env-file=/dev/null to isolate); Stripe's constructEvent throws on Bun
 (no sync WebCrypto) - use constructEventAsync; Bun's pg puts SQLSTATE in
@@ -1121,7 +1272,62 @@ errno where Node's pg uses code.
 Never NODE_ENV in a .env (the build refuses it, naming the line). Build
 machines without secrets: SKIP_ENV_VALIDATION=1.
 
+reflect-metadata (tsyringe, typeorm, inversify - often under
+@simplewebauthn/server): nothing to import; when the graph has it the build
+loads it in a Nitro plugin ahead of the app, so the "tsyringe requires a
+reflect polyfill" boot error does not happen in a directory or a binary.
+
+Build, then start - NEVER run vite build while bun/node .output/server/index.mjs
+is serving from that .output: services load lazily and a failed import of a
+half-written chunk is cached by the runtime (ENOENT 500s until restart).
+
+Single binary (Bun): bun build --compile .output/server/compile.mjs
+--outfile dist/app (the scaffold's "compile" script). compile.mjs is written
+by the build and embeds the frozen pages; with serveStatic: 'inline' in the
+Nitro plugin the assets (and their .br/.gz) are inside too. Ship dist/app
+alone - a Dockerfile copies nothing else, not .output/public.
+
+Nothing is sent raw: a built bun/node server gzips what it answers
+(documents, streams flushed per chunk, payloads, stored pages, api routes)
+for a request that accepts it, and the build writes .br/.gz beside every
+public asset, served by Nitro. Nothing to configure; a Worker leaves it to
+the platform. Off: compress: false on the handler / compressPublicAssets:
+false in Nitro config; Cache-Control: no-transform exempts one answer. Do
+NOT add a compression middleware or precompress assets yourself.
+
 Full guide: read_guide({ slug: 'bun' }).`,
+    },
+    {
+        topic: 'openapi',
+        summary: 'An OpenAPI document derived from route.ts files - rscKit({ openapi }) - and Scalar\'s page over it, mounted as a route',
+        body: `Do NOT hand-write an OpenAPI spec. rscKit({ openapi: true }) in
+vite.config.ts answers /openapi.json, derived from every route.ts: the
+directory is the path ([id] -> {id}), each method export an operation,
+params/searchParams/body schemas the parameters and request body (Zod 4 and
+ArkType describe themselves as JSON Schema; Valibot not yet), a middleware.ts
+above a route a security requirement + 401/403. Stored at build, no middleware.
+
+Document-level parts go on the option:
+  rscKit({ openapi: { info, servers, security, components: { securitySchemes } } })
+What a route says about itself, beside its handler:
+  export const openapi = { summary, tags, responses: { 200: {...} }, POST: { summary } }
+  export const openapi = false   // leave this route out (the reference page, a webhook)
+  export const openapi = { DELETE: false }  // one method out; HEAD/OPTIONS never documented
+Webhook-heavy app: rscKit({ openapi: { include: 'declared' } }) documents only
+routes that export openapi, so callbacks need no opt-out line.
+Response bodies are declared in openapi.responses until a typed helper exists.
+
+The page: Scalar's own package, one route, nothing shipped by the engine:
+  // src/app/reference/route.ts
+  import { ApiReference } from '@scalar/nextjs-api-reference'
+  export const GET = ApiReference({ url: '/openapi.json' })
+  export const openapi = false
+
+Porting a spec file: delete its paths (they are the routes now, and body
+validates at runtime), move info/servers/security to the option, move a
+route's summary/tags/responses to its openapi export.
+
+Full guide: read_guide({ slug: 'openapi' }).`,
     },
     {
         topic: 'env',
@@ -1143,8 +1349,11 @@ export const env = createEnv({
   },
   clientPrefix: 'PUBLIC_',
   client: { PUBLIC_SITE_URL: z.url() },
-  runtimeEnv: { ...process.env, ...import.meta.env },
+  // No bare process.env: a "use client" file importing this for a PUBLIC_
+  // value has no process, and the spread throws before the first render.
+  runtimeEnv: { ...(typeof process === 'undefined' ? {} : process.env), ...import.meta.env },
   emptyStringAsUndefined: true,
+  skipValidation: typeof process !== 'undefined' && !!process.env.SKIP_ENV_VALIDATION,
 })
 \`\`\`
 
@@ -1152,7 +1361,8 @@ Read env.DATABASE_URL, never process.env.DATABASE_URL: the first is typed and
 was checked at startup (a missing or malformed one fails then, with its name),
 the second is string | undefined. A server variable never reaches the browser;
 a browser-readable one MUST start with PUBLIC_ and is read from import.meta.env
-(Vite), which is why runtimeEnv merges both. Commit .env.example, not .env.
+(Vite; the engine registers PUBLIC_ beside VITE_ as a client prefix, nothing
+to configure), which is why runtimeEnv merges both. Commit .env.example, not .env.
 
 Next: NEXT_PUBLIC_* becomes PUBLIC_*; @t3-oss/env-nextjs becomes
 @t3-oss/env-core with runtimeEnv as above (env-nextjs's experimental__runtimeEnv