@rsc-kit/mcp 0.13.1 → 0.15.0

package/guides/offline.md

@@ -0,0 +1,215 @@
+# Offline
+
+> Knowing when the server cannot be reached, and carrying on without it.
+
+```tsx
+'use client'
+
+import { useOffline } from '@rsc-kit/core/useOffline'
+
+export function ConnectionBanner() {
+  const offline = useOffline()
+
+  if (!offline) return null
+
+  return <p role="status">You are offline. Changes will not be saved.</p>
+}
+```
+
+## What "online" means here
+
+Whether the **router could reach the server**, as of its last attempt — not
+`navigator.onLine`.
+
+That distinction matters. `navigator.onLine` only tells you the network
+interface is up — a laptop on café wifi that needs a login is "online" by that
+measure and can reach nothing.
+
+This reports what the router actually observed on its own requests, which is
+what a person means by offline.
+
+It follows that the value only changes when something is attempted. A tab
+sitting idle with a dead connection reports online until the next navigation,
+prefetch or action tries and fails.
+
+## On the server
+
+`useOffline()` returns `false` during a server render, and deliberately: the
+server can reach itself. Returning anything else would render an offline state
+into the HTML and then mismatch when the browser hydrated and disagreed.
+
+## `useOnline`
+
+The same reading, the other way round, for when that is what the markup wants:
+
+```tsx
+'use client';
+
+import { useOnline } from '@rsc-kit/core/useOnline';
+
+export function Status() {
+  return <span>{useOnline() ? 'connected' : 'reconnecting…'}</span>;
+}
+```
+
+It returns `true` on the server, for the same reason `useOffline()` returns
+`false` there. Both read the one store, so they cannot disagree.
+
+## Working with no network at all
+
+The hooks above report. A service worker is what lets the app keep working,
+and it is off by default:
+
+```ts title="vite.config.ts"
+rscKit({ offline: true })
+```
+
+The build writes `sw.js` beside the assets and the generated entry registers
+it. With it on, a page you have visited survives a full reload with no network
+at all — not just a navigation, a reload — and comes back interactive.
+
+Everything else lives in one page's memory — the pages a boundary keeps
+mounted, the prefetch cache. Reload with no network and the browser shows its
+own error page: no script runs, so nothing held in JavaScript is reachable.
+
+A service worker is the only thing that survives that.
+
+### What is cached, and when
+
+| | |
+| --- | --- |
+| hashed assets | at install, and answered from the cache forever after — the name changes when the bytes do |
+| a page you loaded | its document, and the payload it boots from |
+| a page you reached by link | its payload, and its document fetched once to go with it |
+| a page you never visited | nothing |
+
+The last two rows are the same mechanism from either end. A hard load fetches a
+document and never the payload; a link fetches a payload and never the document.
+Either alone is half a page.
+
+So whichever arrives first fetches the other, **once per url**. A page costs one
+extra request the first time you reach it, and none after.
+
+A url you have never opened cannot be served, and is not faked. An earlier
+version answered with the cached root, which put the home page's markup under
+the address someone asked for and did not hydrate — a wrong page pretending to
+be the right one. It fails now, which is true.
+
+### What is deliberately not cached
+
+Anything the server sent with `Cache-Control: no-store`, whatever else it is.
+
+The Cache API files responses by url and knows nothing about who asked. So a
+guarded page, or a [query](/guides/queries/) that read the session, would be
+handed to whoever opens the app next on that machine — signed in as someone
+else. `no-store` is the server saying so, and the worker obeys it.
+
+This is why a query does **not** work offline by default. Queries answer
+`private, no-store` precisely because they may read the session, and widening
+that is a decision about who may see the answer:
+
+```ts
+// Cacheable, and offline, because the answer is the same for everyone.
+export const getPricing = query(async () => tiers(), { cache: "private", maxAge: 300 })
+```
+
+For a personal read you want across reloads, do not widen it — persist your
+cache library instead. TanStack's `persistQueryClient` writes to storage that
+belongs to that browser, which gets you the same result without putting one
+visitor's data somewhere the next one can be served it.
+
+### Updating
+
+The cache name is a hash of what it holds. A build that changed nothing keeps
+the same name and leaves a visitor's cache alone; a build that changed anything
+gets a new one, and the new worker sweeps the old caches away.
+
+There is no version to set, and no way to strand someone on a stale worker.
+
+A new worker takes over as soon as it installs rather than waiting for every
+tab to close. That is safe here because assets are addressed by content: a page
+already open goes on asking for the names it was built with.
+
+<Aside type="note" title="The first visit still needs a reload">
+  A worker does not control the page that registered it. So the first visit
+  caches what it needs and the *second* is the one that survives being offline.
+  That is how service workers work everywhere, not something particular here.
+
+  Development is left alone entirely — a worker answering from a cache in front
+  of the dev server turns every edit into a question about which copy you are
+  looking at.
+</Aside>
+
+<Aside type="caution" title="It can hide a server that is down">
+  Serving from a cache asks nothing of the network, so an app can look healthy
+  while its backend is not. That is the same edge the reveal window has, and it
+  is what `useOffline()` above is for: with this on, saying so in the interface
+  stops being a nicety.
+</Aside>
+
+## When nothing can answer
+
+A reload with no network, on a page the worker has never cached, fails. It does
+not fall back to the cached home page — that was tried, and it was worse than
+failing: the document *is* the page here, so the visitor got the home page's
+markup under the address they asked for, and it did not hydrate.
+
+Add a route at `/offline` and that page is served instead:
+
+```tsx title="src/app/offline/page.tsx"
+export default function Offline() {
+  return (
+    <main>
+      <h1>You are offline</h1>
+      <p>Try again once you are back.</p>
+    </main>
+  )
+}
+```
+
+Nothing in the file makes it special. It is an ordinary route, and what makes it
+the fallback is that the build stored it and the worker precached it. It is also
+the one page that can honestly stand in for another, because it is about being
+offline rather than about the url it appears under.
+
+**It has to be static.** A fallback that renders per request cannot be served
+when there is no request to be made, so the build checks and says when it will
+not work:
+
+```text
+[rsc-kit] offline: /offline cannot be the fallback, because it called cookies(),
+          headers(). A fallback has to be servable with no network at all.
+```
+
+It is served for navigations only — a payload request answered with a document
+would be handed to the Flight decoder, which throws.
+
+## When a new version is live
+
+The worker takes over as soon as it installs rather than waiting for every tab
+to close, and taking over sweeps the previous build's cache. A page that has
+been open across a deploy is therefore running javascript whose remaining chunks
+are gone. It works until it navigates somewhere that needs one.
+
+Only the worker knows this happened, so it says so:
+
+```tsx
+'use client'
+import { useAppUpdate } from '@rsc-kit/core/useAppUpdate'
+
+export function UpdateBanner() {
+  const { updated, reload } = useAppUpdate()
+
+  if (!updated) return null
+
+  return <button onClick={reload}>A new version is ready — reload</button>
+}
+```
+
+Reported rather than acted on. Reloading out from under someone mid-form is
+worse than the staleness it fixes, so this package will not do it for you.
+
+## Going further
+
+Installing, push notifications and background sync are in
+[Progressive web apps](/guides/pwa/).

package/guides/ppr.md

@@ -0,0 +1,181 @@
+# Partial prerendering
+
+> Storing what every visitor sees the same, and rendering the rest per request.
+
+A page usually has two halves: markup that is the same for everybody, and data
+that is not. The build stores the first and renders the second per request, so
+the browser paints immediately and fills in as the data arrives.
+
+There is nothing to switch on, and no mode to pick. Every route goes through
+the same probe, and this is one of the things it can find.
+
+## How the build decides
+
+```text
+Build time
+  → the page is rendered with a budget
+  → anything still waiting when the budget expires is postponed
+  → React has already flushed what did not need the request: layouts, static
+    markup, and the Suspense fallbacks standing in for the rest
+  → that markup is stored as the route's shell, and beside it, where it stopped
+Request time
+  → the shell is served straight from disk — fast, no render
+  → the render is picked up from where it stopped, against data that exists now
+  → only the unfinished boundaries are written, onto the same response
+  → a script React emits beside each one moves it into place as the HTML parses
+```
+
+**Postponed, not merely abandoned.** The difference matters. Aborting a render
+gives you the bytes that flushed and nothing else — React has no record of
+where it got to, so the holes can only be filled later by the browser.
+Postponing keeps that record, which is what lets the boundaries be finished
+at the origin and arrive with the document.
+
+So the content is in the first response. It appears without waiting for the app
+bundle or for hydration — on a slow connection, the difference between a spinner
+and a page — and it is in the HTML a crawler reads.
+
+This is not the same as working with scripting off: with JavaScript disabled the
+fallbacks stay.
+
+If anything goes wrong — the engine cannot resume, or the render fails — the
+shell is served on its own and the client fills the boundaries when it
+hydrates, exactly as it did before any of this existed. A slower hole, never a
+wrong page.
+
+The shell is stored per route **pattern**, not per url. `/posts/[slug]` has one
+shell serving every slug, because everything that varies by slug is behind a
+boundary the request fills.
+
+## What makes a page dynamic
+
+Anything the build cannot know:
+
+- **`await params`** — the url, for a route that has not listed its urls
+- **`await searchParams`** — the query string
+- **`await headers()` / `await cookies()`** — the request
+- **a host call**, on a host that has one
+- **slow work of your own** that outlasts the budget
+
+All of them behave the same way: the read suspends, the nearest fallback above
+it goes into the shell, and the real value arrives per request.
+
+## Where to put the boundaries
+
+Only content inside a `<Suspense>` boundary can stream. Content above every
+boundary has to finish before anything paints — which is the difference between
+a route the build can store and one it refuses.
+
+```tsx title="src/app/posts/[slug]/page.tsx"
+import { Suspense } from 'react';
+import { findPost } from '../../../data';
+
+async function Body({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = await findPost(slug);
+
+  return <article><h1>{post.title}</h1><p>{post.body}</p></article>;
+}
+
+export default function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  return (
+    <Suspense fallback={<p>Loading…</p>}>
+      <Body params={params} />
+    </Suspense>
+  );
+}
+```
+
+`Body` is still waiting when the budget expires, so the shell holds the
+fallback. At request time the slug resolves and React replaces it.
+
+## loading.tsx instead
+
+Rather than wrapping every page by hand, put a `loading.tsx` beside it. The
+build wraps the page in `<Suspense fallback={<Loading />}>` for you, and the
+page can await at its top level:
+
+```tsx title="src/app/posts/[slug]/loading.tsx"
+export default function Loading() {
+  return <div className="h-6 w-50 animate-pulse rounded-lg bg-zinc-800" />;
+}
+```
+
+```tsx title="src/app/posts/[slug]/page.tsx"
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+
+  return <h1>{(await findPost(slug)).title}</h1>;
+}
+```
+
+### It is hierarchical
+
+Like `layout.tsx`, the nearest `loading.tsx` to the page wins, and several in
+one chain stack as nested boundaries:
+
+```text
+src/app/
+  layout.tsx
+  loading.tsx           fallback for everything without a closer one
+  docs/
+    loading.tsx         fallback for /docs/*
+    [slug]/
+      page.tsx          uses docs/loading.tsx
+  dashboard/
+    page.tsx            uses app/loading.tsx
+```
+
+### A root loading.tsx catches everything, including mistakes
+
+It wraps every page, so a page that waits above any boundary of its own is
+still caught and still stored — and the build has nothing to refuse. It looks
+exactly like a page whose boundary is in the right place.
+
+So the build says so:
+
+```text
+◐  /locale
+   ⚠  nothing painted without the root loading.tsx — the fallback the whole app
+      shares is standing in for this page. Put a boundary where the waiting is.
+```
+
+Worked out by rendering the route a second time without the root fallback: a
+page with a boundary of its own paints immediately, and a page leaning on the
+root paints nothing. Only routes with no closer `loading.tsx` are asked, so it
+costs nothing for the rest.
+
+It is a warning rather than an error because the page does work. What it costs
+is shared: every page in the app shows the same fallback while this one waits,
+and the fallback cannot say anything about what is loading. Moving the boundary
+to where the waiting is fixes both.
+
+## When nothing can be frozen
+
+If nothing was flushed before the page blocked, there is no shell to store —
+and the build says so rather than filing the route under a category:
+
+```text
+Some routes could not be prerendered:
+
+  /dashboard — reaches for the host before anything can paint, so there is no shell to store
+
+Each one reads request data — params, headers, cookies, or the host —
+above every Suspense boundary, so nothing can paint without it.
+
+Put the part that waits inside <Suspense>, or add a loading.tsx beside
+the page, so there is something to store while the rest arrives.
+```
+
+Fixed the same way every time, and there is no way to declare it away. A route
+the build cannot store has its boundary in the wrong place; moving the boundary
+is the fix.
+
+## If the build hangs
+
+`RSC_PPR_TIMEOUT_MS` sets it; the default is 2 seconds. Raising it lets slow
+pages be stored whole; lowering it pushes more of them to shells.
+
+A page whose data resolves inside the budget is stored **whole**, even one that
+called `fetch()`. If a page must reflect the world at request time, what makes
+it so is reading the request — not a flag.

package/guides/pwa.md

@@ -0,0 +1,260 @@
+# Progressive web apps
+
+> Making the app installable, and adding push notifications and background sync.
+
+An installable app is a manifest plus a service worker. The
+[offline guide](/guides/offline/) covers the worker; this covers everything
+that makes the app feel like one the operating system knows about.
+
+## The manifest
+
+A service worker makes an app survive a dead network. It does not make a
+browser offer to put it on a home screen — that needs a web app manifest, which
+is a file beside your routes:
+
+```ts title="src/app/manifest.ts"
+import type { WebManifest } from '@rsc-kit/core/manifest-file'
+
+export default {
+  name: 'Orders',
+  shortName: 'Orders',
+  themeColor: '#0b0b0c',
+  backgroundColor: '#ffffff',
+  icons: ['icon-192.png', 'icon-512.png'],
+} satisfies WebManifest
+```
+
+A file rather than a `vite.config.ts` key, and rather than `metadata` in a
+layout. It is not build configuration — it is one more thing the app declares
+about itself, so it lives where the app is, next to `layout.tsx` and
+`not-found.tsx`.
+
+Not `metadata` either, and for a reason worth stating: `metadata` is resolved
+per route and can be computed per request. A manifest is one file for the whole
+app and has to exist before anything renders. Putting it in an inheritable,
+dynamic mechanism would invite a question — *can I override it for this route?*
+— whose only honest answer is no.
+
+The build reads it, writes `manifest.webmanifest`, and links it from every
+page. **There is no layout to edit** — React hoists the `<link>` and the
+`theme-color` meta into `<head>` from wherever they are rendered, so this works
+on an app that already has its own root layout.
+
+It is read at build time, before there is a module graph to evaluate it in, so
+it must be an object literal — not computed, not imported from elsewhere. A
+file that is not gets a build error rather than an app that is quietly not
+installable.
+
+Icons are paths in your `public/` directory, and **their sizes are read from
+the filename** — `icon-192.png` and `icon-192x192.png` both mean 192. Declaring
+the size in the config as well would be the same number written twice, and the
+one that drifts is the one nobody looks at.
+
+Every icon is marked `any maskable`, because without it Android crops a square
+icon into a circle and takes the corners off whatever was in them.
+
+### The build tells you if it will not work
+
+This is the failure worth guarding: a manifest with no icon is *valid*. It
+parses, it links, it sets the theme colour, and no browser ever offers to
+install it. Nothing is wrong and nothing works.
+
+```text
+[rsc-kit] manifest: no icons, so no browser will offer to install this. Add a 192px and a 512px png.
+[rsc-kit] manifest: Orders is installable
+```
+
+A warning rather than a failed build — the manifest still does its other job —
+but it is said out loud, because someone who wrote `manifest: {…}` meant
+installable and would otherwise find out months later.
+
+## Your own worker code
+
+Push, notification clicks and background sync are events the generated worker
+does not handle, and there is nowhere to put them in a file that says *do not
+edit*. So it will import yours:
+
+```js title="src/app/sw.js"
+// Plain javascript. The browser evaluates this in a worker scope with no build
+// step in front of it, so what you write is what runs.
+
+self.addEventListener('push', (event) => {
+  const payload = event.data ? event.data.json() : {}
+
+  event.waitUntil(
+    self.registration.showNotification(payload.title ?? 'Update', {
+      body: payload.body,
+      data: { url: payload.url ?? '/' },
+    }),
+  )
+})
+
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close()
+  event.waitUntil(self.clients.openWindow(event.notification.data.url))
+})
+```
+
+The build copies it beside the generated worker and imports it first, so your
+listeners are registered before anything of ours can answer an event. It is
+precached like everything else — a worker whose import fails does not start, and
+then nothing is cached at all.
+
+```text
+[rsc-kit] offline: 32 files precached as rsc-kit-3d9785e4, falling back to /offline, with app/sw.js
+```
+
+There is no option for this. The file is there or it is not.
+
+:::caution[`.js`, not `.ts`]
+It is evaluated by the browser, not built. TypeScript would not run.
+:::
+
+## Push notifications
+
+Four pieces, and only one of them is ours.
+
+### 1. Keys
+
+Push needs a VAPID key pair — the public half identifies your server to the
+browser, the private half signs what you send.
+
+```sh
+npx web-push generate-vapid-keys
+```
+
+Keep the private key wherever you keep secrets. The public one reaches the
+browser, so it can be a plain environment variable.
+
+### 2. Ask, and subscribe
+
+```tsx title="src/components/EnableNotifications.tsx"
+'use client'
+
+export function EnableNotifications() {
+  async function enable() {
+    if (await Notification.requestPermission() !== 'granted') return
+
+    const registration = await navigator.serviceWorker.ready
+    const subscription = await registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
+    })
+
+    await saveSubscription(subscription.toJSON())
+  }
+
+  return <button onClick={enable}>Enable notifications</button>
+}
+```
+
+**Ask when they have a reason to say yes.** A permission prompt on first load is
+how an app gets denied permanently — the browser remembers a refusal, and there
+is no second chance.
+
+### 3. Store the subscription
+
+An ordinary [server action](/guides/server-actions/), so it is one function and
+no endpoint:
+
+```ts title="src/server/push.ts"
+'use server'
+
+import { client } from './client'
+
+export const saveSubscription = client.input(subscriptionSchema).handler(
+  async ({ input, ctx }) => db.pushSubscriptions.upsert(ctx.user.id, input),
+)
+```
+
+Store it against a **user**, not a session. A subscription outlives the session
+that created it, and that is the point of one.
+
+### 4. Send
+
+From wherever the event happens — a queue, a cron, a webhook:
+
+```ts
+import webpush from 'web-push'
+
+webpush.setVapidDetails('mailto:you@example.com', PUBLIC_KEY, PRIVATE_KEY)
+
+for (const subscription of await db.pushSubscriptions.forUser(userId)) {
+  try {
+    await webpush.sendNotification(subscription, JSON.stringify({
+      title: 'Your order shipped',
+      url: '/orders/42',
+    }))
+  } catch (error) {
+    // 404 and 410 mean the subscription is dead — the app was uninstalled, or
+    // the browser rotated it. Delete it rather than retrying forever.
+    if (error.statusCode === 404 || error.statusCode === 410) {
+      await db.pushSubscriptions.remove(subscription.endpoint)
+    }
+  }
+}
+```
+
+That last branch is the one people skip, and it is why push senders accumulate
+dead endpoints until they are mostly dead endpoints.
+
+:::note[Not ours, deliberately]
+This package ships no push helper. Everything above is the web API and
+`web-push`, and the only part we could own — a place to put the listener — is
+`app/sw.js`. A wrapper would be a thin layer over a stable standard, and one
+more thing to keep current.
+:::
+
+## Background sync
+
+For work that must happen even if the person closes the tab — a queued message,
+an offline edit.
+
+```js title="src/app/sw.js"
+self.addEventListener('sync', (event) => {
+  if (event.tag === 'outbox') event.waitUntil(flushOutbox())
+})
+
+async function flushOutbox() {
+  const db = await openDB()
+
+  for (const item of await db.getAll('outbox')) {
+    const response = await fetch('/api/messages', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(item.body),
+    })
+
+    // Left in the queue on failure, so the browser retries the whole sync
+    // later. Removed only once the server has it.
+    if (response.ok) await db.delete('outbox', item.id)
+  }
+}
+```
+
+Register it from the page after queueing the work:
+
+```ts
+const registration = await navigator.serviceWorker.ready
+await registration.sync.register('outbox')
+```
+
+:::danger[Make the endpoint idempotent]
+The browser decides when a sync runs and may run it more than once — a request
+that succeeded on the server but whose response never arrived gets retried. If
+that posts a message twice, the person sent it twice.
+
+Give each queued item an id the client generates, and have the endpoint ignore
+one it has already seen. Nothing else about background sync is hard; this is,
+and no framework can do it for you because only your data model knows what
+"already seen" means.
+:::
+
+Support is narrower than the rest of this page — Chromium has it, Safari and
+Firefox do not. Treat it as an optimisation over an ordinary retry, never as the
+only path:
+
+```ts
+if ('sync' in registration) await registration.sync.register('outbox')
+else await flushNow()
+```