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

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

@@ -0,0 +1,156 @@
+---
+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. Next.js-compatible files: `not-found.tsx` (404), `forbidden.tsx` (403), `unauthorized.tsx` (401)
+4. `error.tsx` — catches anything unmatched
+5. Parent segments → framework default
+
+## `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.
+
+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 { 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
+
+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,162 @@
+---
+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
+
+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.