@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

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

@@ -0,0 +1,329 @@
+---
+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?: false | {
+    mdastPlugins?: any[];
+    hastPlugins?: any[];
+    features?: Record<string, 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 content conventions (`page.*`, `layout.*`, `default.*`, `denied.*`). Add `'mdx'` for MDX pages.
+
+Status/error conventions (`error.*`, `global-error.*`, status files like `404.*`) always use `.tsx`/`.jsx`/`.ts`/`.js` (or `.json` for status files) — they do not follow `pageExtensions`. Code-only conventions (`middleware.*`, `access.*`, `route.*`, `params.*`) also always use `.ts`/`.tsx`/`.js`/`.jsx`. `.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 — Satteri visitor plugins and parser feature toggles (GFM and frontmatter are on by default). Set `mdx: false` to disable timber's MDX support and bring your own compiler:
+
+```ts
+mdx: {
+  hastPlugins: [myCodeHighlighter],
+  features: { math: true },
+}
+```
+
+See [MDX](/docs/mdx) for the plugin model and how it differs from remark/rehype.
+
+### `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:** `true`
+
+Enable the React Compiler for automatic memoization of components and hooks at build time. Uses `@vitejs/plugin-react`'s native OXC-based compiler path — JSX and compilation run in a single Rust pass with no Babel overhead.
+
+Enabled by default. Set to `false` to disable. Enabling the compiler disables React Fast Refresh — HMR still works but component state is not preserved across edits.
+
+```ts
+reactCompiler: true                                     // enable with defaults (the default)
+reactCompiler: { compilationMode: 'annotation' }        // only compile 'use memo' files
+reactCompiler: { target: '18' }                         // target React 18
+reactCompiler: false                                    // disable
+```
+
+`oxc-transform-react` is included automatically as a dependency of `@timber-js/app`.
+
+### `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,91 @@
+---
+title: 'API: TypeScript'
+description: 'Generated route types, $segment module exports, context types, 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` Module
+
+Each route directory gets a generated `$segment` module, resolved via TypeScript's `rootDirs` (setup and usage in [Typed Routes](/docs/typed-routes)).
+
+| 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                     |
+
+`<Link>` `href` validation and `segmentParams`/`searchParams` typing are described in [Typed Routes](/docs/typed-routes); the param and search-param definitions they draw from are in [Typed Params](/docs/typed-params).
+
+## 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,192 @@
+---
+title: 'CLI'
+description: 'timber dev, build, preview, check, graph, and init commands.'
+slug: 'cli'
+---
+
+# CLI
+
+timber.js provides a small set of 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.
+
+When the requested port is available, the server shows a loading page while Vite initializes. If that port is occupied, startup continues without the loading page.
+
+#### 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:
+
+```
+Port 3000 is in use, trying another one...
+```
+
+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.
+
+For `timber dev`, an occupied port produces a notice and the server tries the next free port. Set `server.strictPort: true` in `vite.config.ts` to fail on a conflict instead. Preview and the production Node preview server report a conflict for an explicit port.
+
+Editing `timber.config.ts` triggers a full process restart so the updated config takes effect. The dev server briefly shuts down and restarts on the same port. Changing the configured port takes effect on restart.
+
+### `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 graph`
+
+Classify a file's module environment(s) — server, client boundary, client-internal, shared, server action, or unreferenced.
+
+```bash
+timber graph app/dashboard/nav.tsx          # human-readable answer
+timber graph app/dashboard/nav.tsx --json   # machine contract for tools and agents
+timber graph --all --json                   # classify the whole project
+```
+
+A file is not intrinsically "client" or "server" — its environment is a property of the import graph. `timber graph` answers from timber's **development module graphs** — the same Vite resolution pipeline `timber dev` runs (aliases, tsconfig paths, `react-server` export conditions), evaluated under serve/development mode. For most apps that is also what production builds; a config that branches on `command` or `mode` is classified as its dev variant. The output includes the environments the file is instantiated in, the import chain(s) that put it there (with the `'use client'` boundary marked), and report-only warnings when a file imports something exclusive to the other side (`node:*` from client-reachable code, `client-only` from server code).
+
+The first query after a clone or a file change runs a full-project crawl — typically ~2.5&nbsp;s, up to ~10&nbsp;s on plugin-heavy apps. Every subsequent query is a cache hit (milliseconds) until the project changes; the cache lives at `.timber/graph-cache.json` and invalidates automatically on any source, config, or lockfile change.
+
+`--json` is the stable machine contract: `{ version, source, cached, target, kind, pending, subtreeUnknown, envs, boundary, chains, poisonings }`. `--all` requires `--json`.
+
+> **Note:** unlike every other command, `timber graph` discovers the Vite config by walking **up from the target file**, not from the directory you run it in — so in a monorepo, the file's own app answers. `--config` overrides as usual.
+
+### `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.                                     |
+| `--json`           |       | `timber graph` only — emit the machine-readable JSON contract.                               |
+| `--all`            |       | `timber graph` only — classify the whole project (requires `--json`).                        |
+
+> **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 — or `--json`/`--all` to anything but `graph` — is an error too, pointing you at the right command.
+
+## 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