@timber-js/app 0.2.0-alpha.154 → 0.2.0-alpha.155

package/docs/api/33-api-search-params.mdx

@@ -0,0 +1,141 @@
+---
+title: 'API: @timber-js/app/search-params & Segment Params'
+description: 'Params exports — defineSchema, getSegmentParams, defineSearchParams, codecs, and utilities.'
+slug: 'api-params'
+---
+
+# @timber-js/app/search-params
+
+Typed search parameter definitions.
+
+## `defineSearchParams(codecs)`
+
+Create a typed search params definition for a route.
+
+```ts
+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', 'date']).default('date'),
+  q: z.string().optional(),
+});
+```
+
+### Returns: `SearchParamsDefinition<T>`
+
+| Method / Property         | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `.get()`                  | Read from ALS and parse (server-only)                  |
+| `.parse(searchParams)`    | Parse and validate from `URLSearchParams` or `Promise` |
+| `.useQueryStates(opts?)`  | Client hook — read and update typed search params      |
+| `.extend(codecs)`         | Add additional params                                  |
+| `.pick(...keys)`          | Create a subset                                        |
+| `.serialize(values)`      | Convert typed values to URL search string              |
+| `.href(base, values)`     | Build a full URL with params                           |
+| `.toSearchParams(values)` | Convert to `URLSearchParams`                           |
+| `.codecs`                 | Read-only codec map                                    |
+| `.urlKeys`                | Read-only URL key alias map                            |
+
+---
+
+# Segment Params
+
+Segment params are defined globally in `app/schema.ts` via `defineSchema`. Access them with `getSegmentParams()` from `@timber-js/app/server` or `useSegmentParams()` from `@timber-js/app/client`.
+
+## `defineSchema(config)`
+
+Define segment param codecs in a single file. Exported from `@timber-js/app`.
+
+```ts
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+import { z } from 'zod/v4';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': z.coerce.number().int().positive(),
+    '[artistSlug]': codec.string,
+    '[year]': codec.integer,
+  },
+});
+```
+
+Each key uses the bracket syntax from the filesystem. Parse failure → 404.
+
+## `getSegmentParams(segmentPath?)`
+
+Read segment params on the server. ALS-backed. Exported from `@timber-js/app/server`.
+
+```ts
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+const { id } = getSegmentParams(SEGMENT_PATH); // Exact types from schema
+const params = getSegmentParams();       // Partial<AllSegmentParams>
+```
+
+## `useSegmentParams(segmentPath?)`
+
+Read segment params on the client. Context-backed. Exported from `@timber-js/app/client`.
+
+```tsx
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+const { id } = useSegmentParams(SEGMENT_PATH); // Exact types from schema
+```
+
+See [Typed Params](/docs/typed-params) for the full guide.
+
+## `SearchParamCodec<T>`
+
+The codec protocol shared across search params, segment params, and cookies. See [Codecs](/docs/typed-params) for the full guide.
+
+```ts
+interface SearchParamCodec<T> {
+  parse(value: string | string[] | undefined): T;
+  serialize(value: T): string | null;
+}
+```
+
+Compatible codecs:
+
+- **Zod/Valibot/ArkType schemas** — auto-detected via Standard Schema
+- **nuqs parsers** — `parseAsInteger`, `parseAsString`, `parseAsBoolean`
+- **Custom** — any object implementing the interface
+
+## Built-in Codecs
+
+| Export                         | Description                 |
+| ------------------------------ | --------------------------- |
+| `parseAsString`                | `string \| null`            |
+| `parseAsInteger`               | `number \| null`            |
+| `parseAsFloat`                 | `number \| null`            |
+| `parseAsBoolean`               | `boolean \| null`           |
+| `parseAsStringEnum(values)`    | Enum `T \| null`            |
+| `parseAsStringLiteral(values)` | Literal `T[number] \| null` |
+
+## Codec Wrappers
+
+### `withDefault(codec, value)`
+
+Wrap a codec to replace `null` with a default value.
+
+```ts
+import { withDefault } from '@timber-js/app/search-params';
+import { parseAsInteger } from 'nuqs';
+const page = withDefault(parseAsInteger, 1); // number (never null)
+```
+
+### `withUrlKey(codec, key)`
+
+Attach a URL key alias to a codec.
+
+```ts
+import { withUrlKey } from '@timber-js/app/search-params';
+import { parseAsString } from 'nuqs';
+const query = withUrlKey(parseAsString, 'q');
+// ?q=shoes → { query: 'shoes' }
+```

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

@@ -0,0 +1,189 @@
+---
+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';
+  buildDir?: string;
+  clientJavascript?: boolean | ClientJavascriptConfig;
+  adapter?: TimberPlatformAdapter;
+  cacheHandler?: CacheHandler;
+  serverTiming?: 'detailed' | 'total' | false;
+  allowedOrigins?: string[];
+  csrf?: boolean;
+  limits?: {
+    actionBodySize?: string;
+    uploadBodySize?: string;
+    maxFields?: number;
+  };
+  actions?: {
+    runMiddleware?: boolean;
+  };
+  forms?: {
+    stripSensitiveFields?: boolean | string[];
+  };
+  pageExtensions?: string[];
+  dev?: {
+    slowPhaseMs?: number;
+  };
+  mdx?: {
+    remarkPlugins?: any[];
+    rehypePlugins?: any[];
+    recmaPlugins?: any[];
+    remarkRehypeOptions?: any;
+  };
+}
+```
+
+## 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' });
+```
+
+### `cacheHandler`
+
+- **Type:** `CacheHandler`
+- **Default:** `MemoryCacheHandler`
+
+Cache backend for `timber.cache()`. See [Cache API](/docs/api-cache).
+
+### `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
+}
+```
+
+### `actions.runMiddleware`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Run `middleware.ts` on server action requests before dispatching. Keeps authentication, rate limiting, and other cross-cutting checks applied uniformly to page renders, route handlers, and server actions. Set to `false` only if your middleware would corrupt action submissions (e.g. it rewrites POST bodies) — you then own placing those checks inside every action.
+
+### `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.
+
+### `dev.slowPhaseMs`
+
+- **Type:** `number`
+- **Default:** framework default
+
+Threshold in milliseconds for slow-phase warnings in dev mode.
+
+### `mdx`
+
+MDX compilation options — remark, rehype, and recma plugins:
+
+```ts
+mdx: {
+  remarkPlugins: [remarkGfm],
+  rehypePlugins: [rehypePrism],
+}
+```
+
+## `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
+
+When a `params.ts` file exports `searchParams`, search params are fully typed:
+
+```ts
+// app/products/params.ts
+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)
+}
+```
+
+Segment params and query params are read via `segmentParams.get()` / `searchParams.get()` from the colocated `params.ts` / `search-params.ts` — the same accessors pages use. 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,143 @@
+---
+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>];
+```
+
+## 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. The timber CLI only accepts `--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 types and routes without producing build output.
+
+```bash
+timber check
+```
+
+Runs TypeScript type checking via `tsgo --noEmit`. Useful in CI pipelines and pre-commit hooks to catch type 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 (for `dev`, `build`, `preview`) or a `tsconfig.json` path (for `check`) |
+
+> **Note:** For `timber check`, `--config` is passed to `tsgo --project` and should point to a TypeScript config file, not a Vite config.
+
+`--config` is the only flag. Any other flag 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`).
+
+## 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