@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

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

@@ -0,0 +1,188 @@
+---
+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. MDX status files (`404.mdx`) are the exception — they are server components, rendered ahead of time.
+
+**MDX status files** work best as static content. Exact-code files (`404.mdx`, `503.mdx`) receive consistent props on all rendering paths — `{ status }` from the error-renderer and boundary paths, and `{ status, dangerouslyPassData }` from deny paths. Wildcard files (`4xx.mdx`, `5xx.mdx`, `error.mdx`) receive props only on the deny and error-renderer paths — on the error boundary path, they are pre-rendered before the error occurs and receive empty props. Use exact-code MDX files if you need to reference `props.status`.
+
+**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,
+  reset,
+}: {
+  error: Error;
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+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 `dangerouslyPassData` 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 via `dangerouslyPassData`:
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+if (!product) {
+  deny({
+    status: 404,
+    data: { title: 'Product not found', resourceId: params.id },
+  });
+}
+```
+
+The error boundary receives the structured data via the `dangerouslyPassData` prop, surviving the RSC → client boundary where plain error properties are stripped.

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     |

package/llms.txt

@@ -0,0 +1,55 @@
+# @timber-js/app
+
+> Vite-native React Server Components framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript.
+
+timber.js is a React framework built on Vite and React Server Components. It uses file-system routing (app/ directory), server components by default, and produces real HTTP status codes. It deploys to Cloudflare Workers, Node.js, Vercel, Netlify, and more via adapters.
+
+It is inspired by, but _not_ next.js. Do not assume next.js features work in timber, though the routing is similar, much of the rest diverges.
+
+## Docs
+
+Documentation ships with this package in the `docs/` directory. All files are MDX.
+
+### Learn (core concepts, read in order)
+
+- [Introduction](docs/learn/00-introduction.mdx)
+- [Quick Start](docs/learn/01-quick-start.mdx)
+- [Pages and Layouts](docs/learn/02-pages-and-layouts.mdx)
+- [Fetching Data](docs/learn/03-fetching-data.mdx)
+- [Access Control](docs/learn/03b-access-control.mdx)
+- [Loading States](docs/learn/04-loading-states.mdx)
+- [The Flush Point](docs/learn/04b-the-flush-point.mdx)
+- [Typed Params](docs/learn/05-typed-params.mdx)
+- [Forms and Actions](docs/learn/06-forms-and-actions.mdx)
+- [Streaming](docs/learn/08-streaming.mdx)
+- [Caching](docs/learn/09-caching.mdx)
+- [Middleware](docs/learn/10-middleware.mdx)
+- [Error Handling](docs/learn/11-error-handling.mdx)
+- [Client Navigation](docs/learn/12-client-navigation.mdx)
+- [Configuration](docs/learn/13-configuration.mdx)
+- [Deploying](docs/learn/14-deploying.mdx)
+
+### More (advanced topics)
+
+- [Advanced Routing](docs/more/01-advanced-routing.mdx)
+- [Advanced Forms](docs/more/02-advanced-forms.mdx)
+- [Coming from Next.js](docs/more/03-coming-from-nextjs.mdx)
+- [Metadata and Fonts](docs/more/04-metadata-and-fonts.mdx)
+- [MDX](docs/more/04b-mdx.mdx)
+- [Content Collections](docs/more/05-content-collections.mdx)
+- [Instrumentation & Tracing](docs/more/06-instrumentation.mdx)
+- [Security](docs/more/07-security.mdx)
+
+### API Reference
+
+- [@timber-js/app/server](docs/api/30-api-server.mdx)
+- [@timber-js/app/client](docs/api/31-api-client.mdx)
+- [@timber-js/app/cache](docs/api/32-api-cache.mdx)
+- [Search & Segment Params](docs/api/33-api-search-params.mdx)
+- [timber.config.ts](docs/api/34-api-config.mdx)
+- [TypeScript](docs/api/35-api-typescript.mdx)
+- [CLI](docs/api/36-cli.mdx)
+
+## AI Agent Skill
+
+A Claude Code skill is included at `agent-skill.md`. Load it for guidance on building timber.js applications.