@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/docs/learn/10-middleware.mdx

@@ -0,0 +1,157 @@
+---
+title: 'Middleware'
+description: 'proxy.ts for global concerns, middleware.ts for per-segment logic.'
+slug: 'middleware'
+---
+
+# Middleware
+
+```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: {
+    '[userId]': codec.string,
+  },
+});
+```
+
+timber.js has two middleware layers: `proxy.ts` for global concerns and `middleware.ts` for per-segment logic.
+
+## Middleware vs Access
+
+Before diving in, the first question: should this be middleware or `access.ts`?
+
+|               | `middleware.ts`                        | `access.ts`                       |
+| ------------- | -------------------------------------- | --------------------------------- |
+| Runs          | Before rendering                       | Inside React tree                 |
+| Purpose       | Headers, redirects, cache warming      | Auth, data gating                 |
+| `React.cache` | Not available                          | Active — shares scope with layout |
+| Slots         | N/A                                    | Graceful degradation              |
+
+Use `middleware.ts` for request-level decisions: should this request proceed? What headers does it need? Use `access.ts` for auth — it has `React.cache` and supports slot degradation.
+
+## `proxy.ts` — Global Middleware
+
+`app/proxy.ts` runs on every request before route matching:
+
+```ts title="app/proxy.ts"
+export default [
+  cors({ origins: ['https://example.com'] }),
+  rateLimit({ requests: 100, window: '1m' }),
+  securityHeaders(),
+];
+```
+
+```ts title="app/proxy.ts"
+export default async function proxy(req: Request, next: () => Promise<Response>) {
+  const start = performance.now();
+  const res = await next();
+  console.log(`${req.method} ${req.url} — ${performance.now() - start}ms`);
+  return res;
+}
+```
+
+`proxy.ts` has `next()` — it can wrap the entire request lifecycle. This is where you observe and modify responses.
+
+## `middleware.ts` — Per-Segment Middleware
+
+`middleware.ts` files run after route matching, before rendering. They're scoped to their route segment.
+
+```ts title="app/dashboard/middleware.ts"
+import { redirect } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getSession(req: Request): Promise<{ userId: string } | null>;
+
+export default async function middleware(ctx: MiddlewareContext) {
+  const session = await getSession(ctx.req);
+  if (!session) redirect('/login');
+}
+```
+
+**Key differences from proxy.ts:** Middleware does not have `next()`. It's a gate — it either short-circuits (redirect, deny, return a Response) or passes through silently. It cannot observe or modify the render result.
+
+**Key difference from Next.js:** Next.js has a single global `middleware.ts`. timber lets you place `middleware.ts` at any route segment.
+
+## Middleware Context
+
+```ts
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.req;              // The incoming Request
+  ctx.segmentParams;    // Route params (already coerced by schema.ts)
+  ctx.headers;          // Response headers (writable)
+  ctx.requestHeaders;   // Request headers (injectable)
+}
+```
+
+Middleware can inject request headers that components read later:
+
+```ts title="app/middleware.ts"
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function detectLocale(req: Request): string;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const locale = detectLocale(ctx.req);
+  ctx.requestHeaders.set('x-locale', locale);
+}
+```
+
+```tsx title="app/page.tsx"
+import { getHeaders } from '@timber-js/app/server';
+
+declare function Content(props: { locale: string | null }): React.ReactElement;
+
+export default async function Page() {
+  const locale = (getHeaders()).get('x-locale');
+  return <Content locale={locale} />;
+}
+```
+
+## Execution Order
+
+For a request to `/dashboard/settings`:
+
+1. `proxy.ts` (global)
+2. `app/middleware.ts` (root, if exists)
+3. `app/dashboard/middleware.ts` (segment)
+4. `app/dashboard/settings/middleware.ts` (segment)
+5. `access.ts` checks (inside React tree)
+6. Render
+
+## Cache Warming
+
+Use middleware to fire off data fetches before rendering starts:
+
+```ts title="app/users/[userId]/middleware.ts" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getUser(userId: string): Promise<{ id: string; name: string }>;
+declare function getUserPosts(userId: string): Promise<{ id: string; title: string }[]>;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  await Promise.all([
+    getUser(userId),
+    getUserPosts(userId),
+  ]);
+}
+```
+
+```tsx title="app/users/[userId]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+
+export default async function UserPage() {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  const user = await getUser(userId);       // cache hit
+  const posts = await getUserPosts(userId); // cache hit
+  return <Profile user={user} posts={posts} />;
+}
+```
+
+Without cache warming, these fetches waterfall. With middleware, both fire in parallel before rendering begins.
+

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,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,145 @@
+---
+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.
+
+## `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               |
+| `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.