@rsc-kit/mcp 0.22.9 → 0.24.0

package/dist/recipes.js

@@ -23,6 +23,10 @@ useState + value/onChange per input, and do NOT reach for TanStack Form.
 ONE WAY TO READ A FORM - two words, the same everywhere:
   error('title')  the field's error, or undefined. !!error('title') is invalid.
                   Nested fields are paths: error('address.city'), error('items[0].name').
+  formError       the refusal NOT about a field (serverError - a 402/409 - or a
+                  form-level validation message), or undefined. Render it as
+                  {formError && <p role="alert">{formError}</p>}; do not keep it
+                  from onError in your own state.
   field('title')  a binding to spread - ONLY for a field whose value the UI must
                   hold (a character count, a live preview, a control with no
                   native element). Everything else stays uncontrolled.
@@ -163,6 +167,12 @@ It works before hydration. The action is on the form element as well as in the
 submit handler, so the markup is submittable on its own; a refusal shows on its
 fields through error() even with no javascript.
 
+**components.json needs "rsc": true.** shadcn's init sees a plain Vite
+project and writes false, and then a dialog or dropdown it adds has no
+"use client". create-rsc-kit --shadcn and rsc-kit init --shadcn set it; after
+a bare \`shadcn init\`, set it by hand. \`import { cn } from "cn"\` in its
+components is correct: cn is shadcn's own package (lib/utils re-exports it).
+
 **shadcn/ui works as-is.** Input, Textarea, Button and Label are styled native
 elements, so \`name\` does what it always does. Select, Checkbox, Switch and
 RadioGroup are Radix underneath and render a hidden native control whenever
@@ -473,8 +483,41 @@ stored at all.
 </Suspense>
 \`\`\`
 
-Or a \`loading.tsx\` beside the page, which is the same thing for the whole
-route.
+THE DEFAULT PATTERN - write pages this way: the page is a SYNCHRONOUS
+component; fixed copy, titles and frames go straight in it (they are the
+stored shell); each read is its own async "slot" component under its own
+<Suspense>, with a skeleton the shape of what it replaces:
+
+\`\`\`tsx
+export default function ShopifyPage() {            // not async
+  return (
+    <Card>
+      <CardTitle>Shopify</CardTitle>                {/* in the shell */}
+      <Suspense><ConnectButtonSlot /></Suspense>    {/* nothing until known */}
+      <Suspense fallback={<ConnectionsSkeleton rows={1} />}>
+        <ConnectionSlot />                          {/* async: its own read + check */}
+      </Suspense>
+    </Card>
+  )
+}
+\`\`\`
+
+Each slot does its own read and its own permission check, so a fast part is
+not held back by a slow one, and a slot can move or be revalidated as a
+section on its own.
+
+loading.tsx wraps the WHOLE page in one boundary. Use it only for a page that
+is one read and nothing else (a detail page whose skeleton is the page). Do
+NOT reach for it by default:
+- the heading/copy/frames the page already knows wait with the data;
+- the slowest read holds back every other part;
+- notFound()/redirect() or a backend 404 decided under it may already have a
+  200 on the wire - a check deciding whether the page exists goes in
+  middleware.ts, which runs before anything is sent;
+- it sits BELOW its layout: a layout that awaits (params, session) needs its
+  own <Suspense> inside the layout;
+- a ROOT loading.tsx hides pages waiting in the wrong place (the build only
+  warns "nothing painted without the root loading.tsx").
 
 The build renders every page. Whatever has not resolved when the budget expires
 becomes the hole; everything above it is stored and served instantly. So a page
@@ -485,6 +528,9 @@ so:
        blocks before anything can paint. Add a loading.tsx beside it, or put a
        <Suspense> above the waiting, and it has a skeleton to store.
 
+Fix that by moving the read into a slot under <Suspense>, not by adding a
+loading.tsx.
+
 A painted fallback stays up at least 300 ms - React's rule: content that
 arrives within 300 ms of the fallback painting waits until then. A stored
 shell's holes arrive a moment after the shell, so fast data shows its
@@ -1323,7 +1369,13 @@ The visitor's url is untouched; only the match changes. Only a top-level
 [domain] or [host] directory binds the host; app/[slug] or app/[collection] at
 the top is a path parameter, as in Next. A top-level [domain]
 binds ONLY from a host, never from a path: example.com/nope is a 404, not a
-tenant called "nope". Otherwise [domain] is an ordinary dynamic segment: params.domain in every page/layout under it, typed
+tenant called "nope". A layout gets params too (its own segments' and those above, as a promise),
+and is rendered again when its own value changes. A route listing no urls
+stores one shell for all values, so a layout awaiting params above every
+boundary fails the build: read them under <Suspense> in the layout, or list
+the urls with generateStaticParams. A tenant check that should 404 goes in
+[domain]/middleware.ts - its argument is the params, and notFound() there is
+a real 404. Otherwise [domain] is an ordinary dynamic segment: params.domain in every page/layout under it, typed
 route('/[domain]/settings', { domain }), loading/error files as usual. A
 directory named for a host (app/admin/) wins over [domain].
 
@@ -1390,6 +1442,28 @@ generated secret) and prints the Go wiring; go get github.com/rsc-kit/go.
 A new app: bun create rsc-kit --backend=<url>, or rsc-kit init in an empty
 directory, which starts one there.
 
+The backend writes rsc-host.json at the project root (beside vite.config.ts):
+{ "actions": { jsName: "Function.name" }, "functions": ["Function.name", ...] }.
+actions become "use server" stubs in src/server-actions.generated.ts;
+functions type rpc()'s first argument, so a misspelt name fails tsc. rpc is a
+GLOBAL the build declares in .rsc-kit/rsc-env.d.ts - never import it. Have
+Vite write the manifest so it cannot go stale:
+rscKit({ hostManifest: { command: ['go', 'run', '.', '-manifest', '../rsc-host.json'], cwd: 'backend' } })
+(Go: reg.WriteManifest(path); Laravel: php artisan rsc:host-manifest).
+Go TYPED functions - prefer these: reg.Handle("Orders.recent", func(ctx context.Context, limit int) ([]Order, error) {...})
+and reg.HandleAction(jsName, name, fn). Any positional params (structs, slices,
+maps...), a trailing pointer is optional, variadic takes the rest. Their types
+go into rsc-host.json, so rpc('Orders.recent', 5) is Order[] with no <T>, and
+the action stub is typed and also accepts a FormData (fields -> first param).
+reg.Register(name, func(ctx, args rsckit.Args) (any, error)) stays untyped.
+Laravel: rsc:host-manifest types each app/Rsc method from its PHP signature -
+int/float/string/bool params (nullable, defaults optional, variadic), a
+FormRequest first param from its rules(), and a result that is a scalar, a
+backed enum, or a plain class with public typed properties (a data object ->
+an interface). array/Model/Collection/JsonSerializable stay unknown: give
+those rpc<T>(). Return a data object, not an array, to get a typed result. Tests
+answer the backend with createTestApp({ host }) - how_to testing.
+
 A backend in another language answers that ONE endpoint, POST /__rsc/host-call,
 and the renderer wires itself from two variables in .env: RSC_BACKEND (a
 Laravel app's APP_URL counts) and RSC_HOST_CALL_SECRET. Both or neither.
@@ -1427,15 +1501,15 @@ 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; a slash nests,
 Billing/Invoices). Do NOT hand-write the attributes from memory; the command
-writes the ones the registry reads, and it writes the map
-(rsc-host-actions.json) too - a running dev server restarts on its own when
-the map changes, so the export is importable when the command returns.
+writes the ones the registry reads, and it writes the manifest
+(rsc-host.json) too - a running dev server restarts on its own when it
+changes, so the export is importable when the command returns.
 Server actions are classes in app/Rsc/Actions, found by reflection in PHP;
-\`php artisan rsc:action-manifest\` writes the map and MUST run before
-Vite - the dev and build scripts rsc:install wrote do (\`php artisan
-rsc:action-manifest && vite\`), so a class written by hand is picked up by
-the next \`npm run dev\` or \`npm run build\`, never by Vite alone. The
-build writes the "use server" stubs from the map - import ordersCancel from
+\`php artisan rsc:host-manifest\` writes rsc-host.json - { actions,
+functions } - and vite.config.ts runs it as dev and every build start:
+rscKit({ hostManifest: { command: ['php', 'artisan', 'rsc:host-manifest'] } }).
+functions types rpc()'s first argument, so a misspelt name fails tsc. The
+build writes the "use server" stubs from actions - import ordersCancel from
 the generated actions module in a client component. Rsc::revalidate('orders')
 in the action returns the re-rendered region with the answer.
 
@@ -1867,6 +1941,30 @@ It builds when the source is newer than the last build - the first run pays,
 the rest do not. This is where a guard that never ran or a 404 that came back
 200 shows up.
 
+**A Go or Laravel backend, answered in the test (nothing running):**
+
+\`\`\`ts
+import { createTestApp, hostReply, HOST_MIDDLEWARE } from '@rsc-kit/core/testing'
+const app = await createTestApp({
+  host: {
+    'Apps.list': ({ args, headers }) => [{ id: 1 }],          // rpc('Apps.list', ...)
+    'Apps.create': () => hostReply.invalid({ name: ['Taken.'] }),
+    [HOST_MIDDLEWARE]: ({ args, headers }) =>                  // middleware.ts guards; args[0] = names
+      headers.get('cookie')?.includes('session=') ? true : hostReply.unauthenticated(),
+  },
+})
+\`\`\`
+
+Answers go through the real host-call client, so they behave as the backend's
+would: hostReply.unauthenticated() -> 401, unauthorized() -> 403,
+redirect(to), refuse(status, message), invalid(errors) -> validationErrors,
+revalidating(result, ...regions). A name with no handler fails the call,
+naming it. RSC_BACKEND in .env is not called.
+
+A url the app forwards to the backend (a Go route, /login) is a 502 in a test
+unless createTestApp({ backend: (request) => new Response(...) }) answers it;
+it gets the request as the backend would.
+
 **What still needs a browser:** a server action called OVER THE WIRE (the id is
 React's and private), hydration, navigation. Playwright against vite preview.
 That limit is narrower than Next's: the action's logic is a unit test here.