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

package/docs/api/34-api-config.mdx

@@ -0,0 +1,325 @@
+---
+title: 'API: timber.config.ts'
+description: 'All configuration options for timber.config.ts.'
+slug: 'api-config'
+---
+
+# timber.config.ts
+
+Project-wide configuration. Export a default object from `timber.config.ts` at the project root.
+
+## Full Type
+
+```ts
+interface TimberUserConfig {
+  output?: 'server' | 'static';
+  debug?: boolean;
+  buildDir?: string;
+  clientJavascript?: boolean | ClientJavascriptConfig;
+  adapter?: TimberPlatformAdapter;
+  serverTiming?: 'detailed' | 'total' | false;
+  allowedOrigins?: string[];
+  csrf?: boolean;
+  limits?: {
+    actionBodySize?: string;
+    uploadBodySize?: string;
+    maxFields?: number;
+  };
+  forms?: {
+    stripSensitiveFields?: boolean | readonly string[];
+  };
+  pageExtensions?: string[];
+  slowRequestMs?: number;
+  renderTimeoutMs?: number;
+  devBrowserLogs?: 'error' | 'warn' | 'info' | 'none';
+  dev?: {
+    slowPhaseMs?: number;
+  };
+  budget?: {
+    firstLoadJs?: number;
+  };
+  appDir?: string;
+  mdx?: {
+    remarkPlugins?: any[];
+    rehypePlugins?: any[];
+    recmaPlugins?: any[];
+    remarkRehypeOptions?: any;
+  };
+  actionEncryption?: {
+    disableInDev?: boolean;
+  };
+  reactCompiler?: boolean | { compilationMode?: string; target?: string };
+  sitemap?: {
+    enabled?: boolean;
+    baseUrl?: string;
+    defaultChangeFrequency?: string;
+    defaultPriority?: number;
+    includeProtected?: boolean;
+  };
+  topLoader?: {
+    enabled?: boolean;
+    color?: string;
+    height?: number;
+    shadow?: boolean;
+    delay?: number;
+    zIndex?: number;
+  };
+}
+```
+
+## Options
+
+### `output`
+
+- **Type:** `'server' | 'static'`
+- **Default:** `'server'`
+
+Server mode runs on every request. Static mode pre-renders at build time.
+
+### `buildDir`
+
+- **Type:** `string`
+- **Default:** `'.timber/dist'`
+
+Override the build output directory. Relative to the project root. Timber config takes precedence over Vite's `build.outDir`. If neither is set, defaults to `.timber/dist`.
+
+```ts
+buildDir: 'build';       // outputs to <root>/build/
+buildDir: '.output';     // outputs to <root>/.output/
+```
+
+### `clientJavascript`
+
+- **Type:** `boolean | { disabled: boolean; enableHMRInDev?: boolean }`
+- **Default:** `true`
+
+Control client-side JavaScript output. Set to `false` to disable all client JS. Use the object form to disable client JS in production while keeping HMR in development:
+
+```ts
+clientJavascript: { disabled: true, enableHMRInDev: true }
+```
+
+### `adapter`
+
+- **Type:** `TimberPlatformAdapter`
+- **Default:** none
+
+Deployment adapter. See [Deployment](/docs/deploying).
+
+```ts
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+import { nitro } from '@timber-js/app/adapters/nitro';
+
+adapter: cloudflare();
+adapter: nitro({ preset: 'node-server' });
+```
+
+### `serverTiming`
+
+- **Type:** `'detailed' | 'total' | false`
+- **Default:** `'detailed'` in dev, `'total'` in production
+
+Controls the `Server-Timing` response header. See [Instrumentation & Tracing](/docs/instrumentation).
+
+### `allowedOrigins`
+
+- **Type:** `string[]`
+- **Default:** none
+
+Origins allowed for CORS and CSRF validation.
+
+### `csrf`
+
+- **Type:** `boolean`
+- **Default:** `true` (in server mode)
+
+Enable CSRF protection for server actions and form submissions.
+
+### `limits`
+
+Control request body size limits:
+
+```ts
+limits: {
+  actionBodySize: '1mb',   // Server action body limit
+  uploadBodySize: '10mb',  // File upload body limit
+  maxFields: 1000,         // Maximum FormData fields
+}
+```
+
+### `forms.stripSensitiveFields`
+
+- **Type:** `boolean | string[]`
+- **Default:** `true`
+
+Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the `submittedValues` echoed back on validation failure. `true` uses the built-in deny-list; an array adds extra field names to the built-in list; `false` disables stripping (never do this in production). See [Forms & Server Actions](/docs/forms-and-actions) for the full pattern list.
+
+### `pageExtensions`
+
+- **Type:** `string[]`
+- **Default:** `['tsx', 'ts', 'jsx', 'js']`
+
+File extensions recognized for rendering conventions (`page.*`, `layout.*`, `error.*`, `default.*`, `denied.*`, status files). Add `'mdx'` for MDX pages.
+
+Code-only conventions (`middleware.*`, `access.*`, `route.*`, `params.*`) always use `.ts`/`.tsx`/`.js`/`.jsx` regardless of this setting. `.mts`/`.cts`/`.mjs`/`.cjs` are not recognized for any convention.
+
+Two files claiming the same convention in one directory (e.g. `page.tsx` + `page.jsx`) are a build error — filesystem order is platform-dependent, so timber refuses to pick one silently.
+
+### `debug`
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Enable timber debug logging in production builds. When `true`, timber's own diagnostics (dev warnings, verbose logging) are active even in production mode. React stays in production mode — only timber's logs are affected. Can also be enabled at runtime via the `TIMBER_DEBUG` environment variable.
+
+### `slowRequestMs`
+
+- **Type:** `number`
+- **Default:** `3000`
+
+Slow request threshold in milliseconds. Requests exceeding this emit a warning via the logger. Set to `0` to disable.
+
+### `renderTimeoutMs`
+
+- **Type:** `number`
+- **Default:** `30000`
+
+Render timeout in milliseconds. If an SSR render or RSC stream read does not complete within this duration, the render is aborted and the connection is closed. Protects against hung fetches and Suspense components that never resolve. Setting `0` uses a 120-second safety ceiling rather than disabling the timeout entirely.
+
+### `devBrowserLogs`
+
+- **Type:** `'error' | 'warn' | 'info' | 'none'`
+- **Default:** `'warn'`
+
+Forward browser console output to the server terminal in dev mode. Sets the minimum log level to forward. Does not intercept `console.log` or `console.debug` (too noisy). No effect in production builds.
+
+### `dev.slowPhaseMs`
+
+- **Type:** `number`
+- **Default:** `200`
+
+Threshold in milliseconds to highlight slow phases in dev logging output.
+
+### `budget`
+
+Build-time performance budgets. When exceeded, the build report emits a warning (does not fail the build).
+
+```ts
+budget: {
+  firstLoadJs: 100_000, // bytes (gzipped)
+}
+```
+
+#### `budget.firstLoadJs`
+
+- **Type:** `number`
+- **Default:** none
+
+Warn when any route's first-load JS (gzip) exceeds this many bytes.
+
+### `appDir`
+
+- **Type:** `string`
+- **Default:** auto-detected (`app/` or `src/app/`)
+
+Override the app directory location. Set to a relative path from the project root (e.g. `'src/app'`) to use a custom location.
+
+### `mdx`
+
+MDX compilation options — remark, rehype, and recma plugins:
+
+```ts
+mdx: {
+  remarkPlugins: [remarkGfm],
+  rehypePlugins: [rehypePrism],
+}
+```
+
+### `actionEncryption`
+
+Server action bound args encryption configuration. The RSC plugin encrypts closure variables captured by `'use server'` functions using AES-256-GCM so they are opaque and tamper-proof in the Flight payload. Encryption is always enabled in production.
+
+The encryption key is auto-generated at build time and embedded in the server bundle. For rolling/blue-green deployments where multiple builds coexist, set `TIMBER_ACTIONS_ENCRYPTION_KEY` env var to share a key across builds.
+
+#### `actionEncryption.disableInDev`
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Disable encryption in dev mode for easier debugging of bound args. Has no effect in production — encryption is always enabled.
+
+### `reactCompiler`
+
+- **Type:** `boolean | { compilationMode?: string; target?: string }`
+- **Default:** `false`
+
+Enable the React Compiler (`babel-plugin-react-compiler`) for automatic memoization of components and hooks at build time.
+
+```ts
+reactCompiler: true                                     // enable with defaults
+reactCompiler: { compilationMode: 'annotation' }        // only compile 'use memo' files
+reactCompiler: { target: '18' }                         // target React 18
+```
+
+Requires `babel-plugin-react-compiler` as a peer dependency.
+
+### `sitemap`
+
+Auto-generate `sitemap.xml` from the route tree. When enabled, timber walks the file-system route tree and produces a sitemap for all discoverable pages. Dynamic routes with `generateStaticSegmentParams()` are enumerated. Routes protected by `access.ts` are excluded by default. Supports automatic pagination (sitemap index) for sites with > 50,000 URLs.
+
+If a user-authored `sitemap.ts` or `sitemap.xml` exists at the app root, auto-generation is disabled.
+
+```ts
+sitemap: {
+  enabled: true,
+  baseUrl: 'https://example.com',
+  defaultChangeFrequency: 'weekly',
+  defaultPriority: 0.5,
+}
+```
+
+| Sub-option                | Type      | Default | Description                                      |
+| ------------------------- | --------- | ------- | ------------------------------------------------ |
+| `enabled`                 | `boolean` | `false` | Must be `true` to enable auto-generation         |
+| `baseUrl`                 | `string`  | —       | Base URL for absolute URLs. Required when enabled |
+| `defaultChangeFrequency`  | `string`  | —       | Default `<changefreq>` for all entries            |
+| `defaultPriority`         | `number`  | —       | Default `<priority>` (0.0–1.0)                   |
+| `includeProtected`        | `boolean` | `false` | Include routes protected by `access.ts`          |
+
+### `topLoader`
+
+Navigation progress bar shown at the top of the page during client-side navigations.
+
+```ts
+topLoader: {
+  enabled: true,
+  color: '#2299DD',
+  height: 3,
+  shadow: true,
+  delay: 0,
+  zIndex: 1600,
+}
+```
+
+| Sub-option | Type      | Default     | Description                                        |
+| ---------- | --------- | ----------- | -------------------------------------------------- |
+| `enabled`  | `boolean` | `true`      | Whether the top-loader is enabled                  |
+| `color`    | `string`  | `'#2299DD'` | Bar color                                          |
+| `height`   | `number`  | `3`         | Bar height in pixels                               |
+| `shadow`   | `boolean` | `true`      | Show subtle glow/shadow effect                     |
+| `delay`    | `number`  | `0`         | Delay in ms before showing (avoids flash on fast navs) |
+| `zIndex`   | `number`  | `1600`      | CSS z-index                                        |
+
+## `TimberPlatformAdapter`
+
+The adapter interface for community adapters:
+
+```ts
+interface TimberPlatformAdapter {
+  name: string;
+  buildOutput(config: TimberConfig, buildDir: string): Promise<void>;
+  preview?(config: TimberConfig, buildDir: string): Promise<void>;
+  waitUntil?(promise: Promise<unknown>): void;
+  sendEarlyHints?(links: string[]): void;
+}
+```

package/docs/api/35-api-typescript.mdx

@@ -0,0 +1,170 @@
+---
+title: 'API: TypeScript'
+description: 'Generated route types, $segment modules, typed Link, typed params, and the Routes interface.'
+slug: 'api-typescript'
+---
+
+# TypeScript
+
+timber.js generates route types at build time. Links, params, and search params are type-checked against the actual route tree.
+
+## Generated Route Map
+
+The build system scans your `app/` directory and generates `.timber/routes.d.ts`:
+
+```ts
+// .timber/routes.d.ts (generated, gitignored)
+import type schema from '../app/schema';
+import type { InferCodecType } from '@timber-js/app/params';
+
+export type TimberRoute = keyof TimberSegmentParams;
+
+export interface TimberSegmentParams {
+  '/': {};
+  '/products/[id]': {
+    id: InferCodecType<typeof schema.segmentParams['[id]']>;
+  };
+  '/blog/[...slug]': { slug: string[] };
+}
+
+export type AllSegmentParams = { /* union of all route params */ };
+```
+
+Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
+
+## `$segment` — Per-Route Type Narrowing
+
+Each route directory gets a generated `$segment` module (via TypeScript's `rootDirs`). Import `SEGMENT_PATH` for type-safe param access:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  // id is typed from your schema codec (e.g., number for codec.integer)
+}
+```
+
+### Exports
+
+| Export         | Type                | Description                                                   |
+| -------------- | ------------------- | ------------------------------------------------------------- |
+| `ROUTE`        | String literal      | URL route pattern, groups stripped (e.g., `'/products/[id]'`) |
+| `SEGMENT_PATH` | String literal      | Full tree path including groups and slots                     |
+
+### tsconfig.json
+
+Add `rootDirs` so TypeScript can resolve `$segment` imports:
+
+```jsonc
+{
+  "compilerOptions": {
+    "rootDirs": [".", ".timber/types"]
+  }
+}
+```
+
+## Typed `<Link>`
+
+`<Link>` validates `href` against the route map:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>           // ✓
+<Link href="/nonexistent">Bad</Link>        // ✗ TypeScript error
+```
+
+For dynamic routes, pass `segmentParams`:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/products/[id]" segmentParams={{ id: 42 }}>
+  Product
+</Link>
+// → <a href="/products/42">Product</a>
+```
+
+## Typed Segment Params
+
+With `SEGMENT_PATH` from `$segment`, param types are narrowed from your `app/schema.ts` codecs:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  // id: number (from z.coerce.number().int().positive() in schema.ts)
+}
+```
+
+Without `SEGMENT_PATH`, params are `Partial<AllSegmentParams>` — all optional.
+
+## Typed Search Params
+
+Search params are typed by the definition you create and import — there is no convention file:
+
+```ts
+// app/products/search-params.ts — any module you like
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: z.coerce.number().default(1),
+  sort: z.enum(['price', 'name']).default('price'),
+});
+
+// In page.tsx — searchParams.get() returns { page: number; sort: 'price' | 'name' }
+```
+
+## Context Types
+
+### `RouteContext`
+
+Passed to API route handlers (`route.ts`):
+
+```ts
+export async function GET(ctx: RouteContext) {
+  ctx.req; // Request
+  ctx.headers; // Headers (response, writable)
+}
+```
+
+Query params are read via `searchParams.get()` on an imported definition — the same accessor pages use. Segment params come from `getSegmentParams(SEGMENT_PATH)`. For the raw query string, use `new URL(ctx.req.url).searchParams`.
+
+### `MiddlewareContext`
+
+Passed to `middleware.ts`:
+
+```ts
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.req; // Request
+  ctx.segmentParams; // Record<string, string | string[]>
+  ctx.headers; // Headers (response, writable)
+  ctx.requestHeaders; // Headers (request, injectable)
+}
+```
+
+### `AccessContext`
+
+Empty interface — `access.ts` takes no arguments. Use ALS-backed imports:
+
+```ts
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function access() {
+  const params = getSegmentParams(SEGMENT_PATH);
+}
+```
+
+## Augmenting Routes
+
+The `Routes` interface is generated by the build system and written to `.timber/routes.d.ts`. It's module-augmented onto `@timber-js/app` — you don't need to import it manually.
+
+Run `timber build` or `timber dev` to regenerate types after adding or renaming routes.

package/docs/api/36-cli.mdx

@@ -0,0 +1,170 @@
+---
+title: 'CLI'
+description: 'timber dev, build, preview, check, and init commands.'
+slug: 'cli'
+---
+
+# CLI
+
+timber.js provides four commands. All are thin wrappers around Vite with timber-specific behavior.
+
+```tsx
+timber < command > [--config<path>][--project<path>];
+```
+
+## Commands
+
+### `timber dev`
+
+Start the development server with HMR and React Fast Refresh.
+
+```bash
+timber dev
+timber dev --config ./custom-vite.config.ts
+```
+
+Starts a Vite dev server with timber's routing, RSC pipeline, and dev tooling active. File changes trigger instant HMR. Route changes are detected automatically.
+
+The server binds the port immediately on startup and shows a loading page while Vite initializes. This eliminates connection refused errors during cold start.
+
+#### Port selection
+
+The default port is **`3000`** for both `timber dev` and `timber preview` (matching Next.js and most Node web frameworks). If `3000` is already in use, timber automatically bumps to `3001`, then `3002`, and so on until it finds a free port:
+
+```
+[timber] Port 3000 in use, using 3001
+```
+
+To override the default, use any of the following (highest precedence first):
+
+1. `server.port` in `vite.config.ts`
+2. `PORT=4000 timber dev` — the `PORT` environment variable
+
+> **Note:** `timber dev --port 4000` is an error, not a silent no-op. `timber dev` accepts only `--config` — use `PORT` or `server.port` to change the port.
+
+When you set the port explicitly, timber **does not** auto-bump — a conflict produces an `EADDRINUSE` error so you find out immediately rather than connecting to the wrong port. This same behavior applies to `timber preview` and the production Node preview server.
+
+### `timber build`
+
+Run the production build.
+
+```bash
+timber build
+timber build --config ./custom-vite.config.ts
+```
+
+Uses Vite's `createBuilder` + `buildApp()` to run a multi-environment build (RSC, SSR, client). The output goes to `.timber/dist/` by default (configurable via `buildDir` in `timber.config.ts`) and is shaped by your adapter (Cloudflare, Nitro, static).
+
+After the build completes, a route table is printed showing each route's type and bundle size:
+
+```tsx
+Route                          Type   Size
+─────────────────────────────────────────────
+/                              ○      2.1 kB
+/about                         ○      1.8 kB
+/blog/[slug]                   λ      3.4 kB
+/api/contact                   ƒ      0.5 kB
+
+○ Static   λ Dynamic   ƒ Function
+```
+
+### `timber preview`
+
+Serve the production build locally for testing.
+
+```bash
+timber preview
+```
+
+If your adapter provides a `preview()` method (e.g. Cloudflare's Miniflare-based preview), that takes priority. Otherwise falls back to Vite's built-in preview server.
+
+A `timber.config.ts` that exists but fails to load is a hard error naming the file — preview never silently falls back to the plain Vite preview server with your adapter ignored.
+
+Always run `timber build` before `timber preview`.
+
+### `timber check`
+
+Validate routes and types without producing build output.
+
+```bash
+timber check
+timber check --config ./custom-vite.config.ts --project ./tsconfig.build.json
+```
+
+Two passes, in order:
+
+1. **Routes.** Resolves your project through Vite exactly as `timber build` does — same root, app directory and `pageExtensions`, same `production` mode and `NODE_ENV`, and including config passed inline to `timber()` in `vite.config.ts`. A config that branches on `mode` or reads `.env.production` therefore resolves the same way under both commands. It then scans, runs the route convention linter, and regenerates the route types (`.timber/timber-routes.d.ts`, `.timber/segment-types.d.ts`, `timber-env.d.ts`). Convention *errors* — the proven-fatal misconfigurations that also fail `timber build`, such as an `error.tsx` that is a server component — fail the command. Warnings print and do not.
+2. **Types.** `tsgo --noEmit`, run from the root the route pass resolved — so it type-checks the same project whose routes were just validated, and finds the declarations that pass just wrote. A relative `--project` is interpreted from the directory you ran the command in.
+
+Codegen runs first on purpose: the generated declarations are what type `<Link href>`, `useSegmentParams()`, and `MiddlewareContext`. On a fresh clone that has never run `timber dev` or `timber build` they do not exist yet, so a bare type check would report errors about correct code.
+
+Your `tsconfig.json` must pull in `timber-env.d.ts` — that file is what references the generated route map. If your `include` lists only source directories, add it:
+
+```json
+{
+  "include": ["app", "*.config.ts", "timber-env.d.ts"]
+}
+```
+
+`timber check` warns when the generated types are not part of the resolved program, because the type check would otherwise pass while measuring `<Link href>` against an empty placeholder. Projects created with `create-timber-app` are configured correctly.
+
+`timber check` requires **`@typescript/native-preview`** (which provides `tsgo`). It is an optional peer dependency — install it as a dev dependency:
+
+```bash
+pnpm add -D @typescript/native-preview
+```
+
+If it is missing, `timber check` fails with that instruction. It never passes by skipping the type check.
+
+Useful in CI pipelines and pre-commit hooks to catch type and routing errors without a full build.
+
+### `timber init`
+
+Write `AGENTS.md` and `CLAUDE.md` to the project root for AI coding agent discovery.
+
+```bash
+timber init
+```
+
+The content comes from the installed `@timber-js/app` package, so it's always in sync with your installed version. If either file already exists, it's skipped — delete it first to regenerate.
+
+The generated `AGENTS.md` includes project structure, key imports, common patterns, and pointers to the full documentation in `node_modules/@timber-js/app/docs/`. `CLAUDE.md` is a one-line pointer to `AGENTS.md`.
+
+## Options
+
+| Flag              | Short | Description                                                                                               |
+| ----------------- | ----- | --------------------------------------------------------------------------------------------------------- |
+| `--config <path>`  | `-c`  | Path to a custom Vite config file. Means the same thing for every command, `check` included. |
+| `--project <path>` |       | `timber check` only — the `tsconfig.json` to type-check.                                     |
+
+> **Note:** `timber check` resolves your app through Vite, so `--config` names the Vite config there too, exactly as it does for `dev` and `build`. The tsconfig has its own flag, `--project`, spelled the way `tsc` and `tsgo` spell it. `check` needs a Vite config that lists the timber plugin and fails with an actionable message if it cannot find one.
+
+Those are the only flags. Any other produces an error rather than being silently ignored, with a hint at the supported alternative (e.g. `--port` points you to the `PORT` env var or `server.port` in `vite.config.ts`). Passing `--project` to a command with no type pass is an error too, pointing you at `--config`.
+
+## Package Manager Scripts
+
+Most projects run timber through package.json scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "timber dev",
+    "build": "timber build",
+    "preview": "timber preview",
+    "check": "timber check"
+  }
+}
+```
+
+```bash
+pnpm dev
+pnpm build
+pnpm preview
+pnpm run check
+```
+
+## What's Next
+
+- [Getting Started](/docs/quick-start) — create a project and run `timber dev`
+- [Configuration](/docs/api-config) — `timber.config.ts` reference
+- [Deployment](/docs/deploying) — build and deploy to production