@rsc-kit/mcp 0.14.0 → 0.16.0

package/guides/queries.md

@@ -0,0 +1,340 @@
+# Queries
+
+> Reading from the server over GET, and letting TanStack Query or SWR own everything above it.
+
+`query()` marks a server function as a read, so the call goes out as a GET
+instead of a POST. Your logs and rate limiters can then tell it apart from a
+mutation, and a cache can hold the answer.
+
+```ts title="src/listings.ts"
+"use server"
+
+import { query } from "@rsc-kit/core/query"
+
+export const getListings = query(async (kind: string) => {
+  return db.listings.where({ kind })
+})
+```
+
+That is the whole feature. There is no cache here, no batching and no
+deduplication: [TanStack Query](https://tanstack.com/query) and
+[SWR](https://swr.vercel.app) already do those and do them better. **This owns
+the transport; they own everything above it.**
+
+You still need `"use server"`, and it is not claiming your function mutates.
+Despite the name it means *this may be called from the browser* — it is what
+gives the function an id and the client a stub to call it through.
+
+Two markers, two jobs. `"use server"` says the function crosses the boundary.
+`query()` says it is a read.
+
+:::caution[The call site picks the method]
+`query()` permits the GET; it does not force it. Calling the function directly
+from a client component is still a POST, because the browser cannot tell a query
+id from an action id — only `fetchQuery` sends a GET.
+
+```tsx
+getListings(kind)                  // POST, even though it is a query
+fetchQuery(getListings, [kind])    // GET
+```
+
+Development warns from the server when a query arrives at the action endpoint,
+so a forgotten `fetchQuery` shows up rather than quietly costing you the method.
+:::
+
+## What it changes
+
+Only the method. Same types, same arguments, same lack of an endpoint to write.
+
+Three things follow from that:
+
+- **Access logs and rate limiters** stop counting your reads as mutations. A
+  limiter that allows 10 writes a minute should not be spending them on a list
+  being refreshed.
+- **A GET is the only shape a cache can keep.** A browser cache, a CDN or a
+  service worker can hold one; a POST can never be held by any of them.
+- **Repeating it is safe by contract**, which is what a prefetcher, a crawler
+  or a retrying proxy assumes when it sees a GET.
+
+TanStack Start makes the same choice from the other side: its `createServerFn()`
+is a GET unless you ask for `{ method: 'POST' }`. We cannot default it that way
+— React gives us one directive for everything, so a GET default would send
+mutations as GET too.
+
+### If you skip it
+
+A plain server action still works as a cache library's fetcher, and nothing
+breaks:
+
+```tsx
+useQuery({ queryKey: ["listings", kind], queryFn: () => getListings(kind) })
+```
+
+You lose the three things above and keep everything else. So this is a
+reasonable place to start, and `query()` is the thing to reach for once a read
+is worth being precise about — anything hot enough to show up in a rate limiter,
+or public enough to be worth caching.
+
+One caveat on the second: data that is the same for everyone usually wants
+[prerendering](/guides/static-generation/) rather than a client read at all, and
+a personal read answers `no-store` and is not cached either way. The caching win
+is real, and narrower than it sounds.
+
+## Reading it
+
+**In a server component, call it.** It is ordinary server code — no HTTP, no
+cache, no client involved:
+
+```tsx
+const listings = await getListings("stay")
+```
+
+**Better still, do not await it.** Pass the promise down and let a client
+component resolve it, and the data streams with the page:
+
+```tsx
+export default function Page() {
+  const listings = getListings("stay")
+
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <List listings={listings} />   {/* "use client": use(listings) */}
+    </Suspense>
+  )
+}
+```
+
+React serialises the promise as a pending row in the payload, so the shell
+paints at once and the rows arrive when the query answers — in the same
+response, with no request from the browser. Nothing in this package is involved;
+`use()` is React's. Reach for this first.
+
+**When the browser decides what to read** — a filter, another page, a refresh —
+hand `fetchQuery` to your cache library:
+
+```tsx
+import { fetchQuery } from "@rsc-kit/core/queryClient"
+
+// TanStack Query
+useQuery({
+  queryKey: ["listings", kind],
+  queryFn: () => fetchQuery(getListings, [kind]),
+})
+
+// SWR
+useSWR(["listings", kind], () => fetchQuery(getListings, [kind]))
+```
+
+`fetchQuery` goes to the server every time. That is what a fetcher needs:
+staleness, revalidation and deduplication belong to the library holding the
+answer, not to the thing that fetches it.
+
+:::caution[Keep the arrow]
+TanStack calls a bare `queryFn` with its own context — `{ client, queryKey,
+meta, signal }` — and a server function serialises whatever it is handed, so
+passing one unwrapped would try to put an `AbortSignal` on the wire. The arrow
+is where you choose what travels.
+:::
+
+### Paging, polling, and the rest
+
+All of it belongs to the library, and all of it works:
+
+```tsx
+// Infinite. The cursor is just an argument.
+useInfiniteQuery({
+  queryKey: ["feed"],
+  queryFn: ({ pageParam }) => fetchQuery(getFeed, [pageParam]),
+  initialPageParam: null,
+  getNextPageParam: (last) => last.nextCursor,
+  initialData: { pages: [first], pageParams: [null] },
+  staleTime: 60_000,
+})
+
+// Data that changes while you watch. No live connection needed.
+useQuery({ queryKey: ["seats"], queryFn: () => fetchQuery(getSeats, []), refetchInterval: 2_000 })
+```
+
+Page one comes from a server component and costs no request; later pages are
+ordinary reads. `/infinite`, `/pagination` and `/polling` in the example app are
+these three patterns end to end.
+
+:::caution[A seed is stale by default]
+TanStack treats `initialData` as stale at its default `staleTime` of `0`, so
+without an explicit `staleTime` it refetches page one on mount and the round
+trip you seeded to avoid happens anyway. SWR's `fallbackData` has the same
+shape of caveat, and `refetchInterval` pauses while the tab is hidden.
+:::
+
+### Where it will not work
+
+`fetchQuery` only works in the browser. React refuses a server-function call
+during the first render, so a component that also renders on the server must not
+call it there.
+
+You will not hit this through TanStack or SWR — they fetch in an effect, after
+hydration.
+
+## Sharing a check across reads
+
+A query has no middleware above it, so each one checks for itself. If that means
+writing the same check in every file, put it on the client you already use for
+actions:
+
+```ts title="src/server/client.ts"
+'use server'
+
+import { createActionClient } from '@rsc-kit/core/action'
+
+export const client = createActionClient({ onError: report })
+  .use(async ({ next }) => {
+    const user = await currentUser()
+
+    if (!user) throw new Error('Not signed in')
+
+    return next({ ctx: { user } })
+  })
+```
+
+```ts title="src/server/posts.ts"
+'use server'
+
+import { client } from './client'
+
+export const createPost = client.input(schema).handler(async ({ input, ctx }) => …)  // POST
+export const getPosts   = client.input(filter).query(async ({ input, ctx }) => …)    // GET
+```
+
+One client, one set of middleware, one `onError`. `.handler()` makes an action;
+`.query()` makes a query. Neither can be added without the check.
+
+### They fail differently, on purpose
+
+An action **returns** its failures, because React strips a thrown message in
+production. A query **throws** — every cache library reports failure by
+rejection, and one that answered with an error-shaped object would look like a
+successful read of something odd.
+
+So a refused read rejects with a real `Error`. A validation failure keeps its
+fields:
+
+```tsx
+const { error } = useQuery({ queryKey: ['posts'], queryFn: () => fetchQuery(getPosts, [filter]) })
+
+error.message   // 'Validation failed'
+error.errors    // { title: ['too short'] }
+```
+
+## Securing a query
+
+A query is a public GET endpoint. Treat it as one.
+
+### Route middleware does not run
+
+`middleware.ts` guards a **route**, and a query has no route — it is reachable
+whoever is asking and whatever page they came from. A query behind a guarded
+page is not guarded.
+
+What you do get is the request: the visitor's cookies and session are bound for
+the call, so a query can check for itself.
+
+One query is fine written by hand:
+
+```ts
+export const getOrders = query(async () => {
+  const user = await currentUser()
+
+  if (!user) throw new Error("Not signed in")
+
+  return db.orders.forUser(user.id)
+})
+```
+
+Twenty is twenty chances to forget, and the one you forget is the one that
+matters. Put the check on the client you already use for actions and build
+every read from it:
+
+```ts title="src/server/orders.ts"
+'use server'
+
+import { client } from './client'
+
+export const getOrders = client.query(async ({ ctx }) => db.orders.forUser(ctx.user.id))
+```
+
+`ctx.user` is typed and non-null because the only way into the handler was
+through the middleware that put it there — so a query **cannot be added without
+the check**. Same client, same middleware, same `onError` as your actions;
+`.handler()` makes a mutation and `.query()` makes a read. See
+[sharing a check across reads](#sharing-a-check-across-reads) below.
+
+Authorise on **identity, not arguments**. `getOrder(id)` that trusts the id is
+the whole of an IDOR: the caller chooses the id.
+
+### Only `query()` is reachable
+
+The endpoint refuses anything that is not a query, which is what keeps every
+action you have registered off a GET url. So export the wrapped value, not the
+bare function beside it.
+
+An unknown id and a real-but-unmarked one get the same 404. Telling them apart
+would let someone probe for your action ids.
+
+### A query must never write
+
+It is a GET. A prefetcher, a crawler or a retry will repeat it.
+
+### What the endpoint does for you
+
+- **Requires `X-RSC-Query`.** A GET with no unusual header is a *simple*
+  request, so any page anywhere could trigger one with
+  `<img src="…/_rsc/query?…">` and it would carry the visitor's cookies — CORS
+  stops them reading the answer, not the read running. That header is not
+  CORS-safelisted, so a browser preflights it and nothing here answers a
+  preflight. It is the same protection a POST carrying `X-RSC-Action` had.
+- Refuses a cross-origin request when an `Origin` is present.
+- Refuses an oversized url with `414` before decoding anything.
+- Sends `Vary: Cookie`, so a cacheable answer is never shared between visitors.
+
+None of that authorises anything. The query does that.
+
+### Arguments are public
+
+They travel in the url, so they reach access logs, browser history and referrer
+headers. Never take a token or a password reset code as a query argument — that
+is an action.
+
+Arguments too large for a url, or containing a `File`, make the read fall back
+to a POST rather than failing. It still works; it simply stops being cacheable,
+and development warns when it happens.
+
+## Caching
+
+Answers default to `private, no-store`. A query may read the session, and a
+cacheable answer to a personal read is how one visitor is served another's data.
+
+```ts
+export const getPricing = query(async () => tiers(), { cache: "public", maxAge: 300 })
+```
+
+### You probably do not need to change it
+
+There are two caches and they solve different problems.
+
+**Your cache library's**, in memory and per tab, decides whether to ask again.
+It needs nothing from this option — `no-store` does not stop TanStack or SWR
+holding an answer, because they are not an HTTP cache.
+
+**The HTTP one**, which `cache` controls, decides whether an answer survives a
+reload, works offline, or can be shared by a CDN.
+
+Most apps want only the first. And note that data which is the same for everyone
+usually wants [prerendering](/guides/static-generation/) rather than a client
+read at all — which is a better answer than any cache. For a personal read you
+want across reloads, persist your cache library rather than widening the read.
+
+## During a build
+
+A query is an ordinary function, so it follows the ordinary rule. One reading a
+database the build machine can reach runs at build time and the page is frozen
+with real data in it. Call `connection()` inside the query to opt out.

package/guides/quick-start.md

@@ -0,0 +1,99 @@
+# Quick start
+
+> A running app in one command, or added to a project you already have.
+
+## A new app
+
+```sh
+bun create rsc-kit@latest my-app
+cd my-app
+bun run dev
+```
+
+That is it. You get a page, a layout, a client component and a Vite config,
+wired together and running. There is no server file — Nitro builds one from the
+preset in that config when you build.
+
+When you are ready to ship:
+
+```sh
+bun run build
+bun run start
+```
+
+The build prints what it did:
+
+```
+  ○  /
+
+  ○  (Static)  prerendered as static content
+
+  1 static
+```
+
+Pages marked `○` are **static**: rendered once at build time rather than for
+each visitor.
+
+## An app you already have
+
+Already have a project? Add rsc-kit to it:
+
+```sh
+bunx rsc-kit@latest init
+```
+
+It reads your `package.json`, works out which server you use and where your
+source lives, and writes only what is missing:
+
+```
+  server      hono
+  source      src
+  react       will be added
+
+  + src/app/layout.tsx
+  + src/app/page.tsx
+  + vite.config.ts
+  ~ package.json  — added @rsc-kit/core, react, react-dom, vite, nitro, …
+  ~ scripts  — dev, build, start, compile, typecheck
+```
+
+No server file. Nitro builds one around the route tree, so the app owns a route
+tree and a vite config and nothing in between.
+
+**It never overwrites anything.** If you already have a `vite.config.ts`, it
+prints the edit to make instead of replacing work you have done. Running it twice is safe — the second run just tells you what is already
+in place.
+
+Then:
+
+```sh
+bun install
+bun run dev
+```
+
+## Add a page
+
+Routes are directories under `src/app`. Create a folder, put a `page.tsx` in
+it, and it exists:
+
+```tsx title="src/app/about/page.tsx"
+export default function AboutPage() {
+  return <h1>About</h1>
+}
+```
+
+```sh
+bun run build   # the route tree is read at build time
+```
+
+## Doing it by hand
+
+If you would rather wire it up yourself — or the CLI cannot reach your
+setup — [Installation](/installation) walks through the same result one file at
+a time.
+
+## Where next
+
+- [Routing](/guides/routing) — layouts, dynamic segments, parallel slots
+- [Server actions](/guides/server-actions) — mutations without an API route
+- [Where it runs](/hosts/where-it-runs) — presets, and compiling to a binary

package/guides/react-compiler.md

@@ -0,0 +1,153 @@
+# React Compiler
+
+> Enabling the compiler in the build.
+
+The React Compiler memoises client components for you, so `useMemo`,
+`useCallback` and `React.memo` mostly stop being things you write.
+
+Nothing here special-cases it. The build runs your project's own Vite config,
+so the compiler is enabled the way it is in any Vite app — by adding
+`@vitejs/plugin-react` after `rscKit()` and turning it on there.
+
+<Aside type="note" title="Order matters">
+  `rscKit()` includes `@vitejs/plugin-rsc`, which has to see modules before
+  any React layer transforms them. The React plugin goes **after** it.
+</Aside>
+
+## Two ways to run it
+
+The compiler has a native implementation and a Babel one. Both produce the same
+transform; they differ in what they cost to run and how settled they are.
+
+### Native, through oxc
+
+The faster path, and the least to install. `compiler: true` is
+[experimental](https://react.dev/learn/react-compiler/installation) and needs
+`oxc-transform-react` present — the plugin looks for it by name:
+
+<PackageManagers pkg="@vitejs/plugin-react oxc-transform-react" dev />
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { rscKit } from '@rsc-kit/core/vite';
+
+export default defineConfig({
+  plugins: [
+    rscKit({ sourceDir: 'src' }),
+    react({ compiler: true }),
+  ],
+});
+```
+
+Pass an object instead of `true` to configure it.
+
+### Babel
+
+The reference implementation. In `@vitejs/plugin-react` 6 the inline `babel`
+option was removed, so the preset is applied through `@rolldown/plugin-babel`:
+
+<PackageManagers pkg="@vitejs/plugin-react @rolldown/plugin-babel babel-plugin-react-compiler" dev />
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
+import babel from '@rolldown/plugin-babel';
+import { rscKit } from '@rsc-kit/core/vite';
+
+export default defineConfig({
+  plugins: [
+    rscKit({ sourceDir: 'src' }),
+    react(),
+    babel({ presets: [reactCompilerPreset()] }),
+  ],
+});
+```
+
+On `@vitejs/plugin-react` 5 and earlier, the inline option still exists:
+
+```ts
+react({
+  babel: { plugins: ['babel-plugin-react-compiler'] },
+})
+```
+
+## Checks worth running first
+
+The compiler only memoises components it can prove are safe to memoise, and it
+skips the rest silently. These are how you find out which is which, and they
+are worth running **before** you turn it on rather than after.
+
+**Type checking.** The compiler assumes your code means what its types say. Run
+`tsc --noEmit` and fix what it reports first — an untyped `any` threading
+through a component is exactly the shape the compiler has to give up on.
+
+```bash
+tsc --noEmit
+```
+
+**The health check.** Reports how many components in your codebase the compiler
+can handle, and why the others are refused:
+
+```bash
+npx react-compiler-healthcheck
+```
+
+**The lint rule.** `eslint-plugin-react-hooks` includes the compiler's own
+diagnostics — the Rules of React violations that make a component
+uncompilable — so they surface as you write rather than as silence in the
+build:
+
+```js title="eslint.config.js"
+import reactHooks from 'eslint-plugin-react-hooks';
+
+export default [reactHooks.configs.recommended];
+```
+
+**StrictMode.** The compiler's assumptions are the Rules of React, and
+StrictMode is what surfaces breaking them at runtime — double-invoked renders
+catch the impure ones.
+
+<Aside type="tip" title="It applies to client components">
+  Server components render once and are thrown away, so there is nothing to
+  memoise in them. The compiler earns its keep in the `"use client"` half of
+  the app.
+</Aside>
+
+## Confirming it ran
+
+The compiler leaves a cache array at the top of every component it compiled.
+Build without minification and look for it:
+
+```js
+function Counter() {
+  const $ = _c(10);                                    // ← compiled
+  const [count, setCount] = useState(0);
+
+  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+    // …
+  }
+}
+```
+
+No `_c(...)` and no `memo_cache_sentinel` means that component was skipped —
+which the health check will explain.
+
+## Opting a component out
+
+```tsx
+"use client";
+
+export default function LegacyWidget() {
+  "use no memo";
+
+  return <div>…</div>;
+}
+```
+
+## Turning it off
+
+Drop `compiler: true`, or remove the plugin. Neither the router nor the build
+depends on it being there.
+
+Further reading: [React Compiler installation](https://react.dev/learn/react-compiler/installation).