@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

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

@@ -0,0 +1,173 @@
+---
+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.
+
+## `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. Called inside `<Suspense>` (after the flush), it triggers the nearest error boundary and injects `<meta name="robots" content="noindex">`.
+
+## 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.
+
+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/12-client-navigation.mdx

@@ -0,0 +1,176 @@
+---
+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 { isPending } = useLinkStatus();
+  return <span className={isPending ? 'opacity-50' : ''}>{children}</span>;
+}
+
+export function NavItem({ href, children }: { href: string; children: React.ReactNode }) {
+  return (
+    <Link href={href}>
+      <NavItemInner>{children}</NavItemInner>
+    </Link>
+  );
+}
+```
+
+## Segment Cache
+
+Opt-in via `clientSegmentCache: true` in `timber.config.ts`. When enabled, the client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
+
+```ts title="timber.config.ts"
+export default {
+  clientSegmentCache: true,
+};
+```
+
+```
+/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.
+
+When disabled (the default), every client navigation gets a full RSC payload from the server. This is simpler and avoids edge cases with stale cached layouts, at the cost of slightly larger payloads on 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,166 @@
+---
+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()` are build errors in static mode — there's no request at the moment components render.
+
+Dynamic routes (`[param]`) must export `generateStaticSegmentParams` when using `output: 'static'` — the build needs to know which URLs to render. API routes (`route.ts`) are also pre-rendered at build time.
+
+For each page, the build generates both HTML (for initial loads) and RSC flight data (for client-side SPA navigation). No server is needed at runtime.
+
+## 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
+
+Cache handler configuration lives in a separate `timber.cache.ts` file (not `timber.config.ts`). This keeps runtime cache instances separate from build-time config, preventing build dependencies from leaking into the server bundle.
+
+```ts title="timber.cache.ts"
+import { MemoryCacheHandler } from '@timber-js/app/cache';
+
+export default new MemoryCacheHandler();
+```
+
+The default export is the `CacheHandler` instance. Export `cdnPurge` as a named export for CDN purge handlers. The default handler is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
+
+## `clientJavascript`
+
+Control whether client-side JavaScript is included in the build. Useful for static content sites, documentation, and marketing pages that don't need interactivity.
+
+```ts title="timber.config.ts"
+// Disable all client JS
+export default {
+  output: 'static',
+  clientJavascript: false,
+};
+```
+
+```ts title="timber.config.ts"
+// No client JS in production, but keep HMR in dev
+export default {
+  output: 'static',
+  clientJavascript: { disabled: true, enableHMRInDev: true },
+};
+```
+
+| Value                                      | Behavior                                                    |
+| ------------------------------------------ | ----------------------------------------------------------- |
+| `true` (default)                           | Client JS enabled — hydration, SPA navigation, etc.         |
+| `false`                                    | All client JS disabled. No hydration, no SPA navigation.    |
+| `{ disabled: true, enableHMRInDev: true }` | No client JS in production, but HMR still works in dev.     |
+
+Server actions still work — HTML forms submit natively via POST without JavaScript.
+
+## All Options
+
+| Option              | Type                        | Default                      | Description                              |
+| ------------------- | --------------------------- | ---------------------------- | ---------------------------------------- |
+| `output`            | `'server' \| 'static'`     | `'server'`                   | Output mode                              |
+| `debug`             | `boolean`                   | `false`                      | Enable timber debug logging in prod      |
+| `buildDir`          | `string`                    | `'.timber/dist'`             | Build output directory                   |
+| `clientJavascript`  | `boolean \| object`         | `true`                       | Control client-side JS                   |
+| `adapter`           | `TimberPlatformAdapter`     | —                            | Deployment adapter                       |
+| `serverTiming`      | `'detailed' \| 'total' \| false` | `'detailed'` / `'total'` | Server-Timing header                     |
+| `allowedOrigins`    | `string[]`                  | —                            | CORS / CSRF allowed origins              |
+| `csrf`              | `boolean`                   | `true`                       | CSRF protection                          |
+| `limits`            | `object`                    | —                            | Request body size limits                 |
+| `actions`           | `object`                    | —                            | Server action behavior                   |
+| `forms`             | `object`                    | —                            | Form handling (sensitive field stripping) |
+| `pageExtensions`    | `string[]`                  | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages                |
+| `slowRequestMs`     | `number`                    | `3000`                       | Slow request warning threshold (ms)      |
+| `renderTimeoutMs`   | `number`                    | `30000`                      | Render abort timeout (ms)                |
+| `devBrowserLogs`    | `string`                    | `'warn'`                     | Forward browser console to server in dev |
+| `dev`               | `object`                    | —                            | Dev-mode options                         |
+| `budget`            | `object`                    | —                            | Build-time performance budgets           |
+| `appDir`            | `string`                    | auto-detected                | Override app directory location          |
+| `mdx`               | `object`                    | —                            | MDX remark/rehype plugins                |
+| `actionEncryption`  | `object`                    | —                            | Server action bound args encryption      |
+| `reactCompiler`     | `boolean \| object`         | `false`                      | React Compiler auto-memoization          |
+| `sitemap`           | `object`                    | —                            | Auto-generated sitemap.xml               |
+| `clientSegmentCache`| `boolean`                   | `false`                      | Opt-in client segment cache for partial nav |
+| `topLoader`         | `object`                    | enabled                      | Navigation progress bar                  |
+
+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.