@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/docs/learn/14-deploying.mdx

@@ -0,0 +1,264 @@
+---
+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.
+
+## 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/docs/more/01-advanced-routing.mdx

@@ -0,0 +1,173 @@
+---
+title: 'Advanced Routing'
+description: 'Route groups, parallel routes (slots), intercepting routes, catch-all segments, affixed dynamic segments, and API routes.'
+slug: 'advanced-routing'
+---
+
+# Advanced Routing
+
+This page covers routing patterns beyond the basics in [Pages and Layouts](/docs/pages-and-layouts). It assumes you understand `page.tsx`, `layout.tsx`, and nesting.
+
+## Dynamic Segments
+
+Wrap a directory name in brackets to capture a URL parameter:
+
+```
+app/
+  products/
+    [id]/
+      page.tsx          # /products/42, /products/abc
+```
+
+Access the param with `getSegmentParams(SEGMENT_PATH)` using the `$segment` module — see [Typed Params](/docs/typed-params) for the full codec system.
+
+## Catch-All Segments
+
+```
+app/docs/[...slug]/page.tsx    # /docs/a, /docs/a/b, /docs/a/b/c
+app/docs/[[...slug]]/page.tsx  # Same, plus /docs (zero segments)
+```
+
+With optional catch-all segments (`[[...slug]]`), the param is `undefined` when no segments match — not an empty array:
+
+| URL           | `slug` value      |
+| ------------- | ----------------- |
+| `/docs`       | `undefined`       |
+| `/docs/intro` | `['intro']`       |
+| `/docs/a/b/c` | `['a', 'b', 'c']` |
+
+### Not Supported: Optional Single Segments
+
+timber does not support `[[foo]]` (optional single dynamic segment). Use `[[...foo]]` and check `slug?.[0]`, or create two separate pages:
+
+```
+app/blog/page.tsx           # /blog (index)
+app/blog/[year]/page.tsx    # /blog/2024 (filtered)
+```
+
+## Affixed Dynamic Segments
+
+Dynamic segments can have literal prefixes and/or suffixes:
+
+```
+app/
+  images/
+    [id].png/
+      route.ts             # /images/123.png → id = "123"
+  user-[name]/
+    page.tsx               # /user-alice → name = "alice"
+  img-[id].webp/
+    page.tsx               # /img-photo.webp → id = "photo"
+```
+
+This is useful for CDN-cacheable file-extension routes (e.g. image generation endpoints) and prefixed slugs. The literal parts must match exactly; the dynamic middle is extracted as the param value.
+
+**Rules:**
+- The param must be non-empty — `img-[id].png` does NOT match `img-.png`
+- One param per segment — `[foo]-[bar]` is not supported
+- Affixes cannot be used with catch-all (`[...slug].png`) or optional catch-all segments
+- Matching is greedy: `[id].png` matching `a.png.png` yields `id = "a.png"`
+- `params.ts` codecs use the bare param name (`id`), not the full segment pattern
+
+**Priority:** static → affixed dynamic → bare dynamic → catch-all → optional catch-all. A static `foo.png` always wins over `[id].png`.
+
+`<Link>` interpolates affixed segments automatically:
+
+```tsx
+<Link href="/images/[id].png" segmentParams={{ id: 'photo' }}>
+  {/* renders href="/images/photo.png" */}
+</Link>
+```
+
+## Parallel Routes (Slots)
+
+Directories prefixed with `@` are slots — they render simultaneously within a parent layout:
+
+```
+app/
+  dashboard/
+    layout.tsx          # Receives { children, sidebar }
+    page.tsx            # Renders as children
+    @sidebar/
+      page.tsx          # Renders as sidebar prop
+      default.tsx       # Fallback when no match
+```
+
+```tsx title="app/dashboard/layout.tsx"
+export default function DashboardLayout({
+  children,
+  sidebar,
+}: {
+  children: React.ReactNode;
+  sidebar: React.ReactNode;
+}) {
+  return (
+    <div className="flex">
+      <aside className="w-64">{sidebar}</aside>
+      <main className="flex-1">{children}</main>
+    </div>
+  );
+}
+```
+
+Slots don't add URL depth. Each slot independently matches the current URL and can have its own `access.ts`, `error.tsx`, and layouts. If a slot's access check fails, the slot degrades gracefully — the rest of the page is unaffected (see [Access Control](/docs/access-control)).
+
+Each slot is also its own collision space: a slot page sharing a URL with the parent page is the point of parallel routes, but two route groups inside one slot producing pages at the same URL (`@side/(a)/x/page.tsx` + `@side/(b)/x/page.tsx`) fail the build, just like the same collision outside a slot.
+
+## Intercepting Routes
+
+Intercepting routes show a different component on soft navigation (client-side link click) vs hard navigation (direct URL). This enables the modal pattern:
+
+| Marker     | Meaning       |
+| ---------- | ------------- |
+| `(.)`      | Same level    |
+| `(..)`     | One level up  |
+| `(..)(..)` | Two levels up |
+| `(...)`    | Root level    |
+
+## API Routes
+
+Export HTTP method handlers from `route.ts`:
+
+```ts title="app/api/hello/route.ts"
+export async function GET(ctx: RouteContext) {
+  return Response.json({ message: 'Hello' });
+}
+
+export async function POST(ctx: RouteContext) {
+  const body = await ctx.request.json();
+  return Response.json({ received: body });
+}
+```
+
+## The Segment Tree
+
+Every directory in your `app/` directory is a **segment**. Segments nest into a tree that connects your URL structure, component structure, and HTML structure:
+
+| Concern           | Segment mapping                                               |
+| ----------------- | ------------------------------------------------------------- |
+| URL matching      | Each segment consumes URL segments (except groups and slots)  |
+| Params            | Dynamic segments extract params, accumulate top-down          |
+| Authorization     | `access.ts` per segment, top-down, shallowest failure wins    |
+| Layouts           | `layout.tsx` per segment, persist across navigation           |
+| Streaming         | `<Suspense>` placement controls flush boundary per segment    |
+| Error handling    | `error.tsx` / status files per segment, leaf-to-root fallback |
+| Client navigation | Segment cache mirrors the tree, skips mounted sync layouts    |
+| Slot isolation    | `@slot` branches render independently, fail gracefully        |
+
+## The Request Lifecycle
+
+``` leading="none"
+Request
+  ├── URL canonicalization
+  ├── proxy.ts (global — every request)
+  ├── Route matching
+  ├── Param coercion (schema.ts codecs)
+  ├── middleware.ts chain (root → leaf)
+  └── Single renderToReadableStream call
+        Root Segment → AccessGate → Layout
+          Child Segment → AccessGate → Layout
+            Leaf Segment → Page
+```
+
+The entire route renders in a **single `renderToReadableStream` call**. One React tree, one `React.cache` scope.

package/docs/more/02-advanced-forms.mdx

@@ -0,0 +1,137 @@
+---
+title: 'Advanced Forms'
+description: 'Coercion helpers, parseFormData, form flash internals, and sensitive field stripping.'
+slug: 'advanced-forms'
+---
+
+# Advanced Forms
+
+This page covers advanced form patterns beyond [Forms and Actions](/docs/forms-and-actions): coercion helpers, raw FormData parsing, form flash internals, and sensitive field stripping.
+
+## Coercing FormData Values
+
+HTML forms send everything as strings. Use `coerce` helpers to convert FormData values before schema validation:
+
+```ts
+import { coerce } from '@timber-js/app/server';
+import { z } from 'zod/v4';
+
+const eventSchema = z.object({
+  title: z.string().min(1),
+  maxAttendees: z.preprocess(coerce.number, z.number().min(1)),
+  isPublic: z.preprocess(coerce.checkbox, z.boolean()),
+  date: z.preprocess(coerce.date, z.date()),
+});
+```
+
+| Helper            | Input               | Output              |
+| ----------------- | ------------------- | ------------------- |
+| `coerce.number`   | `"42"`, `""`        | `42`, `undefined`   |
+| `coerce.checkbox` | `"on"`, `undefined` | `true`, `false`     |
+| `coerce.json`     | `'{"a":1}'`         | `{ a: 1 }`          |
+| `coerce.date`     | `"2024-01-15"`      | `Date`              |
+| `coerce.file`     | `File`, empty input | `File`, `undefined` |
+
+`coerce.file` accepts options for validation:
+
+```ts
+z.preprocess(
+  coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
+  z.instanceof(File)
+);
+```
+
+## `parseFormData`
+
+For advanced cases, `parseFormData` converts raw `FormData` into a plain object before schema validation:
+
+```ts
+import { parseFormData } from '@timber-js/app/server';
+
+const obj = parseFormData(formData);
+```
+
+It handles common patterns:
+
+- **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
+- **Dot-path nesting**: `user.name=Alice` → `{ user: { name: "Alice" } }`
+- **Empty strings → undefined**: Enables `.optional()` semantics
+- **Empty file inputs → undefined**: File inputs with no selection become `undefined`
+
+`createActionClient` calls `parseFormData` automatically — you only need it for manual FormData handling.
+
+## Form Flash Internals
+
+When JavaScript is disabled and a server action returns validation errors, timber re-renders the page with flash data available via `getFormFlash()`:
+
+```ts
+interface FormFlashData {
+  validationErrors: Record<string, string[]>;
+  submittedValues: Record<string, unknown>;
+  serverError?: { code: string; data?: Record<string, unknown> };
+}
+```
+
+- `validationErrors` — field-level errors keyed by field name
+- `submittedValues` — raw input for repopulating form fields (File objects excluded, sensitive fields stripped)
+- `serverError` — present if an `ActionError` was thrown
+
+Flash data is server-side only — stored in AsyncLocalStorage for the duration of the re-render. Never serialized to cookies or headers.
+
+## Sensitive Field Stripping
+
+On validation failure timber echoes submitted form values back so users don't re-type everything. To prevent plaintext passwords or credit-card numbers from leaking through the RSC payload or into HTML `defaultValue` attributes, timber automatically strips a deny-list of sensitive field names.
+
+**Built-in deny-list** (case-insensitive, nested objects walked recursively):
+
+- `password`, `passwd`, `pwd` (and variants like `currentPassword`, `newPassword`)
+- `secret`, `apiKey`, `accessToken`, `refreshToken`, `privateKey`
+- `cvv`, `cvc`, `cardNumber`, `cardCvc`
+- `ssn`, `socialSecurityNumber`
+- `otp`, `totp`, `mfaCode`, `twoFactorCode`
+- `token` (exact match only — `csrfToken` is preserved)
+
+Stripped fields are omitted from `submittedValues` entirely — not replaced with empty strings.
+
+### Global Configuration
+
+```ts title="timber.config.ts"
+import { defineConfig } from '@timber-js/app';
+
+export default defineConfig({
+  forms: {
+    // true / omitted — use built-in deny-list (default)
+    // false — disable all stripping (NEVER in prod)
+    // string[] — extra field names merged with built-in list
+    stripSensitiveFields: ['internalCode', 'bankAccount'],
+  },
+});
+```
+
+### Per-Action Override
+
+```ts
+import { createActionClient } from '@timber-js/app/server';
+
+const action = createActionClient({
+  stripSensitiveFields: (name) => name.startsWith('secret_'),
+});
+```
+
+Per-action config takes precedence over global config, which takes precedence over the built-in default.
+
+## Shared Schemas for Client + Server Validation
+
+Define Zod schemas in shared files and import them on both sides for instant client-side validation while keeping the server as the source of truth:
+
+```ts title="lib/schemas/contact.ts"
+import { z } from 'zod/v4';
+
+export const contactSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100),
+  email: z.string().email('Invalid email address'),
+  message: z.string().min(10).max(2000),
+});
+```
+
+Use in the server action via `.schema(contactSchema)` and in the client form for `onBlur` validation. Client validation is a UX enhancement — always validate on the server.