@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/docs/learn/11-middleware.mdx

@@ -0,0 +1,164 @@
+---
+title: 'Middleware'
+description: 'proxy.ts for global concerns, middleware.ts for per-segment logic.'
+slug: 'middleware'
+---
+
+# Middleware
+
+```ts title="app/schema.ts" id="schema" hidden
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[userId]': codec.string,
+  },
+});
+```
+
+timber.js has two middleware layers: `proxy.ts` for global concerns and `middleware.ts` for per-segment logic.
+
+## Middleware vs Access
+
+Before diving in, the first question: should this be middleware or `access.ts`?
+
+|               | `middleware.ts`                        | `access.ts`                       |
+| ------------- | -------------------------------------- | --------------------------------- |
+| Runs          | Before rendering                       | Inside React tree                 |
+| Purpose       | Headers, redirects, cache warming      | Auth, data gating                 |
+| `React.cache` | Active — shares scope with the render  | Active — shares scope with layout |
+| Slots         | N/A                                    | Graceful degradation              |
+
+Use `middleware.ts` for request-level decisions: should this request proceed? What headers does it need? Use `access.ts` for auth — it gates each segment, renders status pages with `deny()`, and supports slot degradation.
+
+Both share one `React.cache` scope per request with your layouts and pages. A `React.cache`-wrapped `getUser()` called in middleware, `access.ts`, and a layout runs once. Middleware is a good place to start that fetch early.
+
+If middleware changes a cookie, cached functions that already read it keep their old result. Have them take the cookie value as an argument (see [Fetching Data](/docs/fetching-data)); in development timber warns when this happens.
+
+Middleware runs once, root to leaf, before any `access.ts`. A child `middleware.ts` that returns a `Response` responds before a parent's `access.ts` runs. Put authorization that must cover a whole subtree in `access.ts` or in a parent `middleware.ts`.
+
+## `proxy.ts` — Global Middleware
+
+`app/proxy.ts` runs on every request before route matching:
+
+```ts title="app/proxy.ts"
+export default [
+  cors({ origins: ['https://example.com'] }),
+  rateLimit({ requests: 100, window: '1m' }),
+  securityHeaders(),
+];
+```
+
+```ts title="app/proxy.ts"
+export default async function proxy(req: Request, next: () => Promise<Response>) {
+  const start = performance.now();
+  const res = await next();
+  console.log(`${req.method} ${req.url} — ${performance.now() - start}ms`);
+  return res;
+}
+```
+
+`proxy.ts` has `next()` — it can wrap the entire request lifecycle. This is where you observe and modify responses.
+
+## `middleware.ts` — Per-Segment Middleware
+
+`middleware.ts` files run after route matching, before rendering. They're scoped to their route segment.
+
+```ts title="app/dashboard/middleware.ts"
+import { redirect } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getSession(req: Request): Promise<{ userId: string } | null>;
+
+export default async function middleware(ctx: MiddlewareContext) {
+  const session = await getSession(ctx.req);
+  if (!session) redirect('/login');
+}
+```
+
+**Key differences from proxy.ts:** Middleware does not have `next()`. It's a gate — it either short-circuits (redirect, deny, return a Response) or passes through silently. It cannot observe or modify the render result.
+
+**Key difference from Next.js:** Next.js has a single global `middleware.ts`. timber lets you place `middleware.ts` at any route segment.
+
+## Middleware Context
+
+```ts
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.req;              // The incoming Request
+  ctx.segmentParams;    // Route params (already coerced by schema.ts)
+  ctx.headers;          // Response headers (writable)
+  ctx.requestHeaders;   // Request headers (injectable)
+  ctx.nonce;            // Per-request CSP nonce (see Security → Content Security Policy)
+}
+```
+
+Middleware can inject request headers that components read later:
+
+```ts title="app/middleware.ts"
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function detectLocale(req: Request): string;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const locale = detectLocale(ctx.req);
+  ctx.requestHeaders.set('x-locale', locale);
+}
+```
+
+```tsx title="app/page.tsx"
+import { getHeaders } from '@timber-js/app/server';
+
+declare function Content(props: { locale: string | null }): React.ReactElement;
+
+export default async function Page() {
+  const locale = (getHeaders()).get('x-locale');
+  return <Content locale={locale} />;
+}
+```
+
+## Execution Order
+
+For a request to `/dashboard/settings`:
+
+1. `proxy.ts` (global)
+2. `app/middleware.ts` (root, if exists)
+3. `app/dashboard/middleware.ts` (segment)
+4. `app/dashboard/settings/middleware.ts` (segment)
+5. `access.ts` checks (inside React tree)
+6. Render
+
+## Cache Warming
+
+Use middleware to fire off data fetches before rendering starts:
+
+```ts title="app/users/[userId]/middleware.ts" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getUser(userId: string): Promise<{ id: string; name: string }>;
+declare function getUserPosts(userId: string): Promise<{ id: string; title: string }[]>;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  await Promise.all([
+    getUser(userId),
+    getUserPosts(userId),
+  ]);
+}
+```
+
+```tsx title="app/users/[userId]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+
+export default async function UserPage() {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  const user = await getUser(userId);       // cache hit
+  const posts = await getUserPosts(userId); // cache hit
+  return <Profile user={user} posts={posts} />;
+}
+```
+
+Without cache warming, these fetches waterfall. With middleware, both fire in parallel before rendering begins.
+

package/docs/learn/12-error-handling.mdx

@@ -0,0 +1,192 @@
+---
+title: 'Error Handling'
+description: 'Status codes, deny(), error boundaries, and status-code files.'
+slug: 'error-handling'
+---
+
+# Error Handling
+
+```ts title="app/schema.ts" id="schema" hidden
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': codec.string,
+  },
+});
+```
+
+timber.js distinguishes between two error phases. The phase determines how the error is handled and what HTTP status code the client sees.
+
+## Handler-Phase Errors
+
+Errors thrown before rendering (in middleware, access checks, or the page function before JSX) produce a clean HTTP error. No React involved — the server sends the status code and a minimal body.
+
+## Render-Phase Errors
+
+Errors thrown during React rendering are caught by error boundaries. Because timber buffers until `onShellReady`, errors outside `<Suspense>` still produce correct HTTP status codes.
+
+If rendering fails and the error fallback is unavailable or also crashes, the empty 500 response preserves cookies queued by middleware. It uses `Cache-Control: private, no-store` and removes the abandoned page's cache overrides, validators, and body framing headers so a transient failure does not inherit the successful page's cache lifetime.
+
+RSC hard-navigation error envelopes use the same header cleanup, including when a Flight stream fails during rendering. These JSON responses preserve queued cookies and tell the client to load the error page with a full document navigation.
+
+## `deny()`
+
+`deny()` produces the correct HTTP status and renders the matching status file:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ id: string; name: string } | null>;
+declare function canView(product: { id: string }): boolean;
+declare function ProductView(props: { product: { id: string; name: string } }): React.ReactElement;
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  if (!product) deny(404); // Real HTTP 404
+  if (!canView(product)) deny(); // Default: 403
+
+  return <ProductView product={product} />;
+}
+```
+
+`deny()` called outside `<Suspense>` produces a real HTTP status code on a full page load. Called inside `<Suspense>` (after the flush), it triggers the nearest error boundary and injects `<meta name="robots" content="noindex">`. On a client navigation the status page renders in place either way — the payload the router fetches is always HTTP 200 and carries the denial inside it.
+
+## Status-Code Files
+
+Place status-specific error UIs alongside your routes:
+
+```
+app/
+  dashboard/
+    page.tsx
+    error.tsx      # Catches any unhandled error
+    404.tsx        # "Not found" UI
+    403.tsx        # "Forbidden" UI
+    5xx.tsx        # Catch-all server errors
+    4xx.tsx        # Catch-all client errors
+```
+
+Priority order (innermost to outermost):
+
+1. Specific status files (`403.tsx`, `503.tsx`)
+2. Category catch-alls (`4xx.tsx`, `5xx.tsx`)
+3. `error.tsx` — catches anything unmatched
+4. Parent segments → framework default
+
+Component status files (`.tsx`, `.jsx`, `.ts`, `.js`) and `error.tsx` **must start with `'use client'`**:
+
+```tsx title="app/404.tsx"
+'use client';
+
+export default function NotFound({ status }: { status: number }) {
+  return <h1>Page not found</h1>;
+}
+```
+
+timber hands these components to its error boundary — a client component — as a prop, so a server component there cannot cross the RSC boundary. It is not a degraded error page: every page under that segment fails to render. The build catches it and names the file, so you will not discover it as a serialization error on a page you did not touch.
+
+> **Note:** MDX pages and layouts remain fully supported, but status-code files (`404.tsx`, `4xx.tsx`, etc.), `error.tsx`, and `global-error.tsx` must be script files (`.tsx`/`.jsx`/`.ts`/`.js`). MDX status and error files are not recognized.
+
+**JSON status files** (`401.json`, `4xx.json`) return the file contents verbatim — no React rendering, no layout wrapping. `dangerouslyPassData` from `deny()` is silently dropped. They are useful for API routes that need a structured JSON error body:
+
+```
+app/api/
+  401.json       # {"error": "unauthorized"}
+  4xx.json       # Catch-all for API errors
+  route.ts
+```
+
+If nothing in the chain matches, timber renders a built-in status page: a plain document with the status code and its reason phrase, and nothing else — no request URL, no error message. It is what a static build writes to `404.html` when your app has no not-found page, so a static deploy always ships one. Add a root `app/404.tsx` (or `4xx.tsx` / `error.tsx`) to replace it.
+
+## `error.tsx`
+
+The general error boundary. It's a client component:
+
+```tsx title="app/dashboard/error.tsx"
+'use client';
+
+export default function DashboardError({
+  error,
+  digest,
+  reset,
+}: {
+  error: Error;
+  digest: string | null;
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      {digest && <p>Reference: {digest}</p>}
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+`digest` is the ID the server logged the error with: the `errorId` field on its log line. In production `error.message` is a generic string, so the digest is what a reader can quote to you and what you search your logs for. It is `null` when the boundary is serving a `deny()`, and for an error the server logged without an ID: one thrown in the browser, one a client component throws while the page renders on the server, or one raised before the page renders (a module that fails to load, say).
+
+Error boundaries wrap page content inside layouts — the layout shell (nav, sidebar) stays visible when an error fires.
+
+A status page renders inside the layouts **above and including the segment it lives in**, and none below it. A root `404.tsx` serving a `deny(404)` from `app/docs/[slug]/page.tsx` renders inside the root layout only — `docs/layout.tsx` and `[slug]/layout.tsx` do not appear, because the file that matched lives above them. Co-locate the status file with the segment whose chrome you want kept: move that `404.tsx` to `app/docs/` and the docs layout comes with it.
+
+One exception: **the segment that denied never contributes its own layout**, even when it owns the matched status file. If its `access.ts` denied, that layout sits behind the failed auth check, so running it would let it fetch and serialize data the request was not allowed to see. If the layout itself called `deny()`, it threw instead of returning its chrome, so there is nothing to render. A `deny()` from a page is unaffected — the page's own layout still renders.
+
+When a `deny()` has no matching status-code file, it falls through to the nearest `error.tsx`. The component still receives a real `error` (its message is `Access denied with status <N>`), and additionally receives `status` and `data` so you can render denial-specific UI:
+
+```tsx title="app/error.tsx"
+'use client';
+
+export default function ErrorPage({
+  error,
+  reset,
+  status,
+}: {
+  error: Error;
+  reset: () => void;
+  status?: number; // set when this boundary is serving a deny()
+}) {
+  if (status === 404) {
+    return <h2>Not found</h2>;
+  }
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+The HTTP status stays correct either way — `deny(404)` falling through to `error.tsx` still responds with a 404, never a 500.
+
+## Connection Abort Suppression
+
+When a user refreshes the page or navigates away while Suspense boundaries are still streaming, the aborted connection would normally cause errors in both the RSC and SSR streams. timber detects these aborts and suppresses them at multiple layers:
+
+- **Server-side:** The request's `AbortSignal` is passed to React's `renderToReadableStream`. React stops rendering on abort without firing `onError`. SSR detects the abort and closes the stream silently.
+- **Client-side:** The error boundary checks for page unload (`beforeunload`/`pagehide`) and suppresses error boundary activation. The client router silently discards `AbortError` from aborted fetches.
+
+A page refresh during streaming never shows a flash of an error boundary. This is a common issue in Next.js where mid-stream refreshes can briefly display error UI.
+
+## Structured Error Data
+
+`deny()` accepts optional JSON-serializable data that is passed to the error page as the `data` prop. The opt-in is explicit at the call site — `dangerouslyPassData` signals that this data crosses the RSC → client serialization boundary:
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+if (!product) {
+  deny(404, {
+    dangerouslyPassData: { title: 'Product not found', resourceId: params.id },
+  });
+}
+```
+
+The status-code file receives the structured data as the `data` prop, surviving the RSC → client boundary where plain error properties are stripped. This works for any 4xx or 5xx status: `deny(503, { dangerouslyPassData })` renders `503.tsx` (or `5xx.tsx`, or `error.tsx`) with its `data`. A plain `throw` is for failures you did not plan for: outside `<Suspense>` it renders the error page with a 500, and in production the page gets a generic message and a `digest` to find the log line by.

package/docs/learn/13-deploying.mdx

@@ -0,0 +1,287 @@
+---
+title: 'Deploying'
+description: 'Deploy timber.js to Cloudflare Workers, Node.js, Vercel, Netlify, AWS Lambda, and more.'
+slug: 'deploying'
+---
+
+# Deploying
+
+timber.js uses **adapters** to transform the build output for your platform. There are exactly two first-party adapters.
+
+## The Two Adapters
+
+**`cloudflare()`** — Cloudflare Workers and Pages. Workers are architecturally different from Node.js (no file system, no `node:http`, different lifecycle model), so they get a dedicated adapter with direct binding access and native `waitUntil()`.
+
+**`nitro({ preset })`** — Everything else. Pick the preset that matches your platform:
+
+| Preset            | Platform               | `waitUntil()` |
+| ----------------- | ---------------------- | ------------- |
+| `node-server`     | Node.js, Docker, VPS   | ✅            |
+| `bun`             | Bun.serve()            | ✅            |
+| `vercel`          | Vercel Serverless      | ✅            |
+| `vercel-edge`     | Vercel Edge Functions  | ✅            |
+| `netlify`         | Netlify Functions      | ❌            |
+| `netlify-edge`    | Netlify Edge Functions | ✅            |
+| `aws-lambda`      | AWS Lambda             | ❌            |
+| `deno-deploy`     | Deno Deploy            | ✅            |
+| `azure-functions` | Azure Functions        | ❌            |
+
+## Build Commands
+
+```bash
+timber build      # Production build
+timber preview    # Local preview of the build output
+```
+
+## Cloudflare Workers
+
+```ts title="timber.config.ts"
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  output: 'server',
+  adapter: cloudflare(),
+};
+```
+
+```bash
+timber build
+wrangler deploy
+```
+
+The adapter generates a `wrangler.jsonc` with sensible defaults. Access KV, D1, R2, and Queues bindings via `getCloudflareBindings()`:
+
+```ts
+import { getCloudflareBindings } from '@timber-js/app/adapters/cloudflare';
+
+export default async function Page() {
+  const { MY_KV, MY_DB } = getCloudflareBindings();
+  const data = await MY_KV.get('key');
+  // ...
+}
+```
+
+For caching, use `CloudflareKVCacheHandler`:
+
+```ts title="timber.config.ts"
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  output: 'server',
+  adapter: cloudflare(),
+};
+```
+
+```ts title="timber.cache.ts"
+import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+
+export default new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' });
+```
+
+**Constraints:** no file system, 10ms/30s CPU time limits, 10MB/25MB bundle size.
+
+## Node.js & Docker
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'node-server' }),
+};
+```
+
+```bash
+timber build
+node .timber/dist/nitro/.output/server/index.mjs
+```
+
+A dedicated server is timber's sweet spot: no cold starts, warm in-process cache, and the ability to co-locate with your database. Five sequential fetches that take 1000ms from serverless take 10ms co-located.
+
+### Docker
+
+```dockerfile
+FROM node:24-slim AS build
+RUN corepack enable
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm run build
+
+FROM node:24-slim AS runtime
+RUN corepack enable
+RUN groupadd --system timber && useradd --system --gid timber --create-home timber
+WORKDIR /app
+COPY --from=build --chown=timber:timber /app/.timber/dist/nitro/.output ./.output
+COPY --from=build --chown=timber:timber /app/package.json /app/pnpm-lock.yaml ./
+RUN pnpm install --prod --frozen-lockfile
+USER timber
+ENV NODE_ENV=production PORT=3000 HOST=0.0.0.0
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+For multiple replicas, switch from `MemoryCacheHandler` to `RedisCacheHandler`.
+
+## Vercel
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'vercel' }),
+};
+```
+
+```bash
+timber build
+vercel deploy --prebuilt
+```
+
+Or connect your git repository — Vercel deploys automatically on push. Use `vercel-edge` preset for Edge Functions. Serverless functions are ephemeral — always use an external cache handler.
+
+## Netlify
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'netlify' }),
+};
+```
+
+```bash
+timber build
+netlify deploy --prod
+```
+
+Netlify Functions (Lambda-based) don't support `waitUntil()`. Use `netlify-edge` for Deno-based edge execution with `waitUntil()` support.
+
+## AWS Lambda
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'aws-lambda' }),
+};
+```
+
+Deploy with CDK, SAM, Serverless Framework, or Terraform. Lambda doesn't support `waitUntil()` — use SQS or EventBridge for background work. Use provisioned concurrency to mitigate cold starts.
+
+## Deno, Azure & Bun
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+// Deno Deploy
+export default { output: 'server', adapter: nitro({ preset: 'deno-deploy' }) };
+
+// Azure Functions
+export default { output: 'server', adapter: nitro({ preset: 'azure-functions' }) };
+
+// Bun
+export default { output: 'server', adapter: nitro({ preset: 'bun' }) };
+```
+
+## Static Export
+
+For sites that don't need a server:
+
+```ts title="timber.config.ts"
+export default {
+  output: 'static',
+};
+```
+
+Pre-renders every route to HTML at build time. Add `clientJavascript: false` for zero-JavaScript output. Deploy to any static file host — S3, CloudFront, Cloudflare Pages, GitHub Pages, Netlify, or any HTTP server.
+
+### Serving from a sub-path
+
+To deploy under a path instead of a domain root — `https://user.github.io/repo/` on GitHub Pages, for example — set Vite's `base`:
+
+```ts title="vite.config.ts"
+export default defineConfig({
+  base: '/repo/',
+  plugins: [timber()],
+});
+```
+
+Every URL timber emits picks up the prefix: client assets, fonts, and the RSC payloads behind client-side navigation.
+
+Your own links are not rewritten. `base` prefixes emitted assets, not application URLs, so an `href` must include the prefix itself:
+
+```tsx
+<Link href={`${import.meta.env.BASE_URL}about`}>About</Link>
+```
+
+A plain `href="/about"` points at the domain root, outside your deployment.
+
+A relative base (`'./'`) can't tell timber where the site lives, so payload URLs fall back to the domain root and client-side navigation degrades to full page loads on a sub-path deployment. The build warns when it sees one — use an absolute base like `'/repo/'`.
+
+## CDN Integration
+
+timber.js provides typed helpers for CDN caching headers and tag-based purging. CDN caching is always developer-elected — the framework never sets cache headers automatically.
+
+### Header Helpers
+
+```ts title="app/proxy.ts"
+import { cacheControl, cacheTag } from '@timber-js/app/cdn';
+
+export default async function proxy(ctx) {
+  if (ctx.pathname.startsWith('/products/')) {
+    ctx.headers.set('Cache-Control', cacheControl({
+      public: true,
+      maxAge: 600,
+      staleWhileRevalidate: 60,
+    }));
+    // Use cacheTag for Cloudflare Workers Cache (all plans)
+    ctx.headers.set('Cache-Tag', cacheTag(['products']));
+    // Or surrogateKey for Fastly/Akamai/Varnish
+    // ctx.headers.set('Surrogate-Key', surrogateKey(['products']));
+  }
+}
+```
+
+### Purge on `revalidateTag`
+
+When using the Cloudflare adapter, CDN purge is **automatic** — no configuration needed. The adapter auto-wires `WorkersCachePurge`, which uses `ctx.cache.purge({ tags })` from the Workers runtime. Available on all Cloudflare plans with no API token required. Just set `Cache-Tag` headers on your responses using `cacheTag()`.
+
+For non-Workers Cloudflare zones (Enterprise), or other CDNs, configure a purge handler manually:
+
+```ts title="timber.cache.ts"
+import { CloudflarePurge } from '@timber-js/app/cdn/cloudflare';
+
+// Only needed for non-Workers Cloudflare zones (Enterprise)
+export const cdnPurge = new CloudflarePurge({
+  zoneId: process.env.CF_ZONE_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+});
+```
+
+Fastly:
+
+```ts title="timber.cache.ts"
+import { FastlyPurge } from '@timber-js/app/cdn/fastly';
+
+export const cdnPurge = new FastlyPurge({
+  serviceId: process.env.FASTLY_SERVICE_ID!,
+  apiToken: process.env.FASTLY_API_TOKEN!,
+  softPurge: true,
+});
+```
+
+When `revalidateTag('products')` fires, it clears the application cache **and** calls the CDN purge handler. CDN purge is best-effort — failures are logged but don't break cache invalidation.
+
+## Cache Handler Selection
+
+| Deployment                  | Recommended Handler  | Why                                           |
+| --------------------------- | -------------------- | --------------------------------------------- |
+| Single server (VPS, Docker) | `MemoryCacheHandler` | In-process LRU, no external dependency        |
+| Multi-instance (k8s, ECS)   | `RedisCacheHandler`  | Shared store, tag invalidation across replicas |
+| Cloudflare Workers          | `KVCacheHandler`     | Workers KV, global edge distribution          |
+| Serverless (Vercel, Lambda) | `RedisCacheHandler`  | Ephemeral functions need an external store     |