@timber-js/app 0.2.0-alpha.154 → 0.2.0-alpha.155

package/docs/learn/12-client-navigation.mdx

@@ -0,0 +1,168 @@
+---
+title: 'Client Navigation'
+description: 'The Link component, useRouter, segment cache, and scroll restoration.'
+slug: 'client-navigation'
+---
+
+# Client Navigation
+
+timber.js supports client-side navigation via the `<Link>` component. Clicking a link fetches an RSC payload from the server and reconciles the DOM without a full page reload.
+
+## `<Link>`
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>
+<Link href="/products/123">Product</Link>
+<Link href="/dashboard" replace>Dashboard</Link>
+```
+
+`<Link>` type-checks `href` against the generated route map. Invalid routes produce a TypeScript error.
+
+## `useRouter`
+
+For programmatic navigation:
+
+```tsx title="app/components/logout-button.tsx"
+'use client';
+
+import { useRouter } from '@timber-js/app/client';
+
+declare function logout(): Promise<void>;
+
+export function LogoutButton() {
+  const router = useRouter();
+
+  async function handleLogout() {
+    await logout();
+    router.push('/login');
+  }
+
+  return <button onClick={handleLogout}>Log out</button>;
+}
+```
+
+| Method                 | Description                              |
+| ---------------------- | ---------------------------------------- |
+| `router.push(href)`   | Navigate to a new URL                    |
+| `router.replace(href)` | Navigate without adding a history entry |
+| `router.refresh()`    | Re-fetch the current route's RSC payload |
+| `router.back()`       | Go back in history                       |
+| `router.forward()`    | Go forward in history                    |
+
+## `usePathname`
+
+Returns the current pathname:
+
+```tsx
+'use client';
+import { usePathname, Link } from '@timber-js/app/client';
+
+export function NavLink({ href, children }: { href: string; children: React.ReactNode }) {
+  const pathname = usePathname();
+  const isActive = pathname === href;
+  return (
+    <Link href={href} className={isActive ? 'font-bold' : ''}>
+      {children}
+    </Link>
+  );
+}
+```
+
+## `useSelectedLayoutSegment`
+
+Returns the active segment within a layout — useful for highlighting nav items:
+
+```tsx
+'use client';
+import { useSelectedLayoutSegment } from '@timber-js/app/client';
+
+export function DashboardNav() {
+  const segment = useSelectedLayoutSegment();
+  // segment is "settings", "projects", etc.
+}
+```
+
+## `useLinkStatus`
+
+Track per-link pending state during navigation:
+
+```tsx
+'use client';
+import { Link, useLinkStatus } from '@timber-js/app/client';
+
+function NavItemInner({ children }: { children: React.ReactNode }) {
+  const { pending } = useLinkStatus();
+  return <span className={pending ? 'opacity-50' : ''}>{children}</span>;
+}
+
+export function NavItem({ href, children }: { href: string; children: React.ReactNode }) {
+  return (
+    <Link href={href}>
+      <NavItemInner>{children}</NavItemInner>
+    </Link>
+  );
+}
+```
+
+## Segment Cache
+
+The client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
+
+```
+/dashboard/settings → /dashboard/team
+
+  Root Layout       ← sync, mounted → skip
+  Auth Layout       ← sync, mounted → skip
+  Dashboard Layout  ← sync, mounted → skip
+  Team Page         ← new            → fetch from server
+```
+
+Sync layouts stay cached while mounted. Async layouts always re-render. Pages always re-render. Client component state in shared layouts is preserved — counters, form inputs, scroll positions survive navigation.
+
+Back/forward navigation replays cached RSC payloads instantly — no server roundtrip.
+
+## Scroll Restoration
+
+- **Forward navigation** scrolls to the top of the page.
+- **Back/forward** restores the saved scroll position.
+- **Hash fragments** — `<Link href="/docs/api#install">` commits the full URL (including the `#fragment`) to the address bar and scrolls to the matching element after render, just like a plain `<a>` without JavaScript. If no element matches, navigation falls back to scroll-to-top.
+
+Pass `scroll={false}` to `<Link>` or `router.push` to preserve the current scroll position:
+
+```tsx
+<Link href="/dashboard/settings" scroll={false}>Settings</Link>
+```
+
+```tsx
+router.push('/dashboard/settings', { scroll: false });
+```
+
+### Custom Scroll Containers
+
+If your layout uses a custom scrollable container, add `data-timber-scroll-restoration`:
+
+```tsx
+<main className="overflow-y-auto h-screen" data-timber-scroll-restoration>
+  {children}
+</main>
+```
+
+## `Link.onNavigate`
+
+Intercept navigation for view transitions:
+
+```tsx
+<Link
+  href="/gallery"
+  onNavigate={(e) => {
+    if (document.startViewTransition) {
+      e.preventDefault();
+      document.startViewTransition(() => e.navigate());
+    }
+  }}
+>
+  Gallery
+</Link>
+```

package/docs/learn/13-configuration.mdx

@@ -0,0 +1,117 @@
+---
+title: 'Configuration'
+description: 'timber.config.ts — output mode, adapters, caching, and the two-phase model.'
+slug: 'configuration'
+---
+
+# Configuration
+
+timber.js is configured through `timber.config.ts` at the project root. Vite configuration lives separately in `vite.config.ts`.
+
+## Minimal Config
+
+```ts title="timber.config.ts"
+export default {
+  output: 'server',
+};
+```
+
+That's it for most projects. The defaults are sensible.
+
+## How the Config Is Loaded
+
+`timber.config.ts` is loaded by Node.js itself using built-in type stripping — it is not bundled by Vite. This requires Node.js 22.18 or newer, and the file must stick to erasable TypeScript syntax: type annotations, interfaces, and `satisfies` are fine, but enums, namespaces, and constructor parameter properties will fail to load. Your `package.json` should declare `"type": "module"` (the default for new timber projects) so the `export default` syntax parses correctly.
+
+If the config file fails to load for any reason, every command — `timber dev`, `timber build`, and `timber preview` — stops with an error naming the file. A broken config never silently falls back to defaults.
+
+## Output Modes
+
+| Mode                                   | Server required | Client JS                 | Server Actions |
+| -------------------------------------- | --------------- | ------------------------- | -------------- |
+| `'server'`                             | Yes             | Yes                       | Yes            |
+| `'static'`                             | No              | Yes (hydration + SPA nav) | Via adapter    |
+| `'static'` + `clientJavascript: false` | No              | None                      | Build error    |
+
+```ts title="timber.config.ts"
+// Static site with no JavaScript
+export default {
+  output: 'static',
+  clientJavascript: false,
+};
+```
+
+## Build Time vs Request Time
+
+The `output` field shifts work between two phases:
+
+**Build time** happens once when you run `timber build`. There's no request, no user, no cookies. Route scanning, client boundary discovery, server action extraction, font downloading, and asset bundling all happen here.
+
+**Request time** happens per incoming HTTP request. Middleware, access checks, server components, caching, cookies, and server actions all run here.
+
+| `output`   | `middleware.ts`       | Server components              | Server actions                              |
+| ---------- | --------------------- | ------------------------------ | ------------------------------------------- |
+| `'server'` | Request time          | Request time                   | Request time                                |
+| `'static'` | **Build time only**   | **Build time** (once, to HTML) | **Request time**, split-deployed as endpoints |
+
+This is why `cookies()` and `headers()` raise warnings during a static build — there's no request at the moment components render.
+
+## Adapters
+
+Adapters transform the build output for your deployment platform:
+
+```ts title="timber.config.ts"
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  output: 'server',
+  adapter: cloudflare(),
+};
+```
+
+```ts title="timber.config.ts"
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+export default {
+  output: 'server',
+  adapter: nitro({ preset: 'node-server' }),
+};
+```
+
+`cloudflare()` for Cloudflare Workers. `nitro({ preset })` for everything else — Node.js, Vercel, Netlify, AWS Lambda, Deno, Bun, Azure.
+
+## Cache Handler
+
+```ts title="timber.config.ts"
+import { MemoryCacheHandler } from '@timber-js/app/cache';
+
+export default {
+  output: 'server',
+  cacheHandler: new MemoryCacheHandler(),
+};
+```
+
+The default is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
+
+## All Options
+
+| Option             | Type                    | Default                      | Description               |
+| ------------------ | ----------------------- | ---------------------------- | ------------------------- |
+| `output`           | `'server' \| 'static'` | `'server'`                   | Output mode               |
+| `adapter`          | `TimberPlatformAdapter` | —                            | Deployment adapter        |
+| `cacheHandler`     | `CacheHandler`          | `MemoryCacheHandler`         | Cache backend             |
+| `clientJavascript` | `boolean \| object`     | `true`                       | Control client-side JS    |
+| `pageExtensions`   | `string[]`              | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages |
+| `mdx`              | `object`                | —                            | MDX remark/rehype plugins |
+
+For the full type definition, see the [Config API Reference](/docs/api-config).
+
+## .gitignore
+
+Add these to your `.gitignore` — they're generated at build/dev time and should not be committed:
+
+```txt title=".gitignore"
+.timber
+.content-collections
+```
+
+`.timber` contains the build output (default `.timber/dist`). `.content-collections` contains generated modules from [content collections](/docs/content-collections). `create-timber-app` adds both automatically.

package/docs/learn/14-deploying.mdx

@@ -0,0 +1,206 @@
+---
+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';
+import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+
+export default {
+  output: 'server',
+  adapter: cloudflare(),
+  cacheHandler: 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.
+
+## 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,139 @@
+---
+title: 'Advanced Routing'
+description: 'Route groups, parallel routes (slots), intercepting routes, catch-all 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)
+```
+
+## 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.