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

package/docs/more/04b-mdx.mdx

@@ -0,0 +1,209 @@
+---
+title: 'MDX'
+description: 'Use MDX to write pages in Markdown with embedded React components — server-rendered by default, zero client JS.'
+---
+
+# MDX
+
+MDX lets you write pages in Markdown with embedded React components. In timber.js, MDX pages are **server components by default** — they render on the server with zero client JavaScript unless a component explicitly opts in with `'use client'`.
+
+## Setup
+
+Add `'mdx'` to `pageExtensions` in your config:
+
+```ts title="timber.config.ts"
+export default {
+  pageExtensions: ['tsx', 'ts', 'jsx', 'js', 'mdx'],
+};
+```
+
+Install the MDX compiler and frontmatter plugins:
+
+```bash title="Terminal"
+pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter
+```
+
+That's it. Any `page.mdx` file in your `app/` directory is now a route.
+
+## Page-Level MDX
+
+A `page.mdx` works exactly like `page.tsx` — it becomes a route based on its directory:
+
+```
+app/
+  docs/
+    getting-started/
+      page.mdx          # /docs/getting-started
+    api-reference/
+      page.mdx          # /docs/api-reference
+    layout.tsx           # shared docs layout
+```
+
+MDX pages support `export const metadata` for page titles and descriptions:
+
+````mdx title="app/docs/getting-started/page.mdx"
+export const metadata = { title: 'Getting Started' }
+
+# Getting Started
+
+Install timber.js:
+
+```bash
+pnpm add @timber-js/app
+```
+
+This page is a **server component** — no JavaScript shipped to the browser.
+````
+
+## Frontmatter
+
+timber.js automatically registers `remark-frontmatter` and `remark-mdx-frontmatter` when installed. Frontmatter is exported as a single `frontmatter` object:
+
+````mdx title="app/blog/hello/page.mdx"
+---
+title: Hello World
+description: My first post
+---
+
+# {frontmatter.title}
+
+{frontmatter.description}
+````
+
+You can import the frontmatter object from another MDX file:
+
+```tsx title="app/blog/layout.tsx"
+import { frontmatter } from './page.mdx';
+
+// frontmatter.title, frontmatter.description, etc.
+```
+
+For page metadata, use an explicit `export const metadata` — frontmatter alone does not set metadata automatically:
+
+````mdx title="app/docs/getting-started/page.mdx"
+---
+title: Getting Started
+---
+
+export const metadata = { title: 'Getting Started' }
+
+# {frontmatter.title}
+````
+
+## Custom Components
+
+Create `mdx-components.tsx` at the project root to customize how Markdown elements render:
+
+```tsx title="mdx-components.tsx"
+import type { MDXComponents } from 'mdx/types';
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    ...components,
+    h1: (props) => <h1 className="text-3xl font-bold mt-8 mb-4" {...props} />,
+    pre: (props) => <pre className="bg-gray-900 text-gray-100 p-4 rounded-lg" {...props} />,
+    code: (props) => <code className="bg-gray-100 px-1.5 py-0.5 rounded text-sm" {...props} />,
+  };
+}
+```
+
+timber.js detects this file at startup and applies it to all MDX files automatically. The file can also live in `src/`.
+
+## Using Client Components in MDX
+
+MDX files stay on the server. To add interactivity, import a `'use client'` component:
+
+````mdx title="app/docs/getting-started/page.mdx"
+import { CopyButton } from '../../components/copy-button'
+
+# Getting Started
+
+```bash
+pnpm add @timber-js/app
+```
+
+<CopyButton text="pnpm add @timber-js/app" />
+````
+
+Only the `CopyButton` ships JavaScript. The rest of the page renders as static HTML.
+
+## Remark and Rehype Plugins
+
+Configure remark and rehype plugins through the `mdx` key in your config:
+
+```ts title="timber.config.ts"
+import remarkGfm from 'remark-gfm';
+import rehypeShiki from '@shikijs/rehype';
+
+export default {
+  pageExtensions: ['tsx', 'ts', 'jsx', 'js', 'mdx'],
+  mdx: {
+    remarkPlugins: [remarkGfm],
+    rehypePlugins: [[rehypeShiki, { theme: 'monokai' }]],
+  },
+};
+```
+
+The `mdx` config maps directly to `@mdx-js/rollup` options. Available fields:
+
+| Option                | Type            | Description                                |
+| --------------------- | --------------- | ------------------------------------------ |
+| `remarkPlugins`       | `PluggableList` | remark plugins for Markdown AST transforms |
+| `rehypePlugins`       | `PluggableList` | rehype plugins for HTML AST transforms     |
+| `recmaPlugins`        | `PluggableList` | recma plugins for ESTree transforms        |
+| `remarkRehypeOptions` | `object`        | Options passed to `remark-rehype`          |
+
+Plugins like `remark-gfm` and `rehype-shiki` are your choice to install — timber.js doesn't bundle them.
+
+## Dynamic MDX Loading
+
+For content-driven pages like a blog, use `import.meta.glob()` to build a map of MDX modules, then load the right one based on the URL:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { allBlogs } from 'content-collections';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+import { SEGMENT_PATH } from './$segment';
+
+const mdxModules = import.meta.glob<{ default: React.ComponentType }>(
+  '../../../content/blog/*.mdx'
+);
+
+export default async function BlogPost() {
+  const { slug } = getSegmentParams(SEGMENT_PATH);
+  const post = allBlogs.find((p) => p.slug === slug);
+  if (!post) deny(404);
+
+  const key = `../../../content/blog/${post._meta.fileName}`;
+  const loader = mdxModules[key];
+  if (!loader) deny(404);
+
+  const { default: MdxComponent } = await loader();
+
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <MdxComponent />
+    </article>
+  );
+}
+```
+
+`import.meta.glob()` is resolved at build time by Vite — each `.mdx` file becomes a real ES module in the bundle with no `eval` or `new Function()` at runtime. The glob path is relative to the file that calls it.
+
+This pattern pairs with [content collections](/docs/content-collections) — the collection provides typed metadata (title, date, tags), while `import.meta.glob()` loads the MDX body as a React component.
+
+An alternative is `compileMDX()` from `@content-collections/mdx`, which compiles MDX to a serialized string during the content collection transform step. You then render it at runtime with `useMDXComponent(code)`. This avoids glob paths but trades them for a runtime eval of the compiled output. `import.meta.glob()` keeps everything as real ES modules resolved at build time.
+
+## Content Collections
+
+For structured content outside the route tree (blog posts, docs, changelogs), use [content collections](/docs/content-collections). Collections give you typed schemas, slug generation, and build-time validation — while MDX page routes are for pages that live directly in `app/`.
+
+## Coming from Next.js
+
+| Next.js                                   | timber.js                                     |
+| ----------------------------------------- | --------------------------------------------- |
+| `@next/mdx` wrapper package               | Built-in — just add `'mdx'` to pageExtensions |
+| `next.config.mjs` `withMDX()` wrapper     | `timber.config.ts` `mdx` key                  |
+| MDX pages are client components by default | MDX pages are server components by default     |
+| Custom loader for `.md` files              | `@mdx-js/rollup` handles both `.mdx` and `.md` |
+| `mdx-components.tsx` at project root       | Same convention                               |

package/docs/more/05-content-collections.mdx

@@ -0,0 +1,90 @@
+---
+title: 'Content Collections'
+description: 'Typed file-based content with Zod schemas, MDX rendering, and virtual module access.'
+---
+
+# Content Collections
+
+Content collections let you define typed, file-based content in a `content/` directory. Each collection has a Zod schema for frontmatter validation and a transform for processing (like MDX compilation).
+
+## Defining a Collection
+
+```ts
+// content-collections.ts
+import { defineCollection, defineConfig } from '@content-collections/core';
+import { compileMDX } from '@content-collections/mdx';
+import { z } from 'zod/v4';
+
+const docs = defineCollection({
+  name: 'docs',
+  directory: 'content/docs',
+  include: '**/*.{mdx,md}',
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    order: z.number(),
+    section: z.string().optional(),
+  }),
+  transform: async (document, context) => {
+    const mdx = await compileMDX(context, document);
+    return { ...document, mdx };
+  },
+});
+
+export default defineConfig({ collections: [docs] });
+```
+
+## Using Collections
+
+Import the generated collection and query it:
+
+```tsx
+import { allDocs } from 'content-collections';
+import { getSegmentParams, deny } from '@timber-js/app/server';
+
+declare const allDocs: { title: string; _meta: { fileName: string }; mdx: { default: React.ComponentType } }[];
+
+export default async function DocsPage() {
+  const { slug } = getSegmentParams();
+  const doc = allDocs.find((d) => d._meta.fileName === slug);
+  if (!doc) deny(404);
+
+  return (
+    <article className="prose">
+      <h1>{doc.title}</h1>
+      <doc.mdx.default />
+    </article>
+  );
+}
+```
+
+## Content Directory Structure
+
+```tsx
+content / docs / v1 / getting - started.mdx;
+routing.mdx;
+blog / hello - world.mdx;
+```
+
+Each file's `_meta` includes `path`, `fileName`, and `directory` — useful for filtering by version, building sidebar navigation, or generating static params.
+
+## MDX Components
+
+Customize MDX rendering with `mdx-components.tsx`:
+
+```tsx
+// mdx-components.tsx
+import type { MDXComponents } from 'mdx/types';
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    ...components,
+    h1: ({ children }) => <h1 className="text-3xl font-bold">{children}</h1>,
+    code: ({ children }) => <code className="bg-gray-100 rounded px-1">{children}</code>,
+  };
+}
+```
+
+## Type Generation
+
+Content collections generate TypeScript types at build time. Every document is fully typed — frontmatter fields, computed properties from transforms, and `_meta` information.

package/docs/more/06-instrumentation.mdx

@@ -0,0 +1,214 @@
+---
+title: 'Instrumentation & Tracing'
+description: 'Server instrumentation, OTEL tracing, custom logging, and Server-Timing headers.'
+slug: 'instrumentation'
+---
+
+# Instrumentation & Tracing
+
+timber.js provides structured observability out of the box: per-request trace IDs, OTEL span integration, pluggable logging, and Server-Timing headers.
+
+## `instrumentation.ts`
+
+Create an `instrumentation.ts` file at your project root. It runs once at server startup, before the first request is handled.
+
+```ts
+// instrumentation.ts
+
+// Called once at startup. Initialize your OTEL SDK, database pools, etc.
+export async function register() {
+  // e.g. initialize OpenTelemetry
+  const { NodeSDK } = await import('@opentelemetry/sdk-node');
+  const sdk = new NodeSDK({
+    /* ... */
+  });
+  sdk.start();
+}
+
+// Called on every unhandled server error.
+export function onRequestError(error, request, context) {
+  // Send to Sentry, Datadog, etc.
+  console.error(`[${context.phase}] ${request.method} ${request.path}`, error);
+}
+
+// Optional: replace the default logger.
+export { logger } from './lib/logger';
+```
+
+### `register()`
+
+Called once before the server starts accepting requests. Use it to:
+
+- Initialize an OpenTelemetry SDK
+- Set up database connection pools
+- Configure external services
+
+The server blocks until `register()` resolves.
+
+### `onRequestError(error, request, context)`
+
+Called for every unhandled error in the server pipeline. The handler receives:
+
+| Parameter           | Type                     | Description                                           |
+| ------------------- | ------------------------ | ----------------------------------------------------- |
+| `error`             | `unknown`                | The thrown error                                      |
+| `request.method`    | `string`                 | HTTP method (`'GET'`, `'POST'`, etc.)                 |
+| `request.path`      | `string`                 | Request path (`'/dashboard/projects/123'`)            |
+| `request.headers`   | `Record<string, string>` | Request headers                                       |
+| `context.phase`     | `string`                 | Pipeline phase: `'proxy'`, `'handler'`, or `'render'` |
+| `context.routePath` | `string`                 | Request pathname (`'/dashboard/projects/123'`)        |
+| `context.routeType` | `string`                 | Currently always `'page'`                             |
+| `context.traceId`   | `string`                 | 32-char hex trace ID for correlation                  |
+
+The handler must not affect the response. Errors thrown by the handler are caught and logged.
+
+### `logger`
+
+Export a logger object to replace the default logger:
+
+```ts
+// instrumentation.ts
+import pino from 'pino';
+
+export const logger = pino({ level: 'info' });
+```
+
+Any object with `info`, `warn`, `error`, and `debug` methods works:
+
+```ts
+interface TimberLogger {
+  info(msg: string, data?: Record<string, unknown>): void;
+  warn(msg: string, data?: Record<string, unknown>): void;
+  error(msg: string, data?: Record<string, unknown>): void;
+  debug(msg: string, data?: Record<string, unknown>): void;
+}
+```
+
+The default logger writes human-readable lines to stderr with automatic trace ID injection.
+
+## Tracing
+
+### `getTraceId()`
+
+Returns the current request's trace ID — always a 32-char lowercase hex string. Available in middleware, access checks, server components, and server actions.
+
+```ts
+import { getTraceId } from '@timber-js/app/server';
+
+const id = getTraceId(); // "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
+```
+
+- **With OTEL**: returns the real OTEL trace ID (matches Jaeger, Honeycomb, Datadog)
+- **Without OTEL**: returns a `crypto.randomUUID()`-derived fallback in the same format
+
+Use `getTraceId()` to correlate logs, errors, and external service calls for a single request.
+
+### `getSpanId()`
+
+Returns the current OTEL span ID if available, `undefined` otherwise.
+
+```ts
+import { getSpanId } from '@timber-js/app/server';
+
+const sid = getSpanId(); // "1234567890abcdef" or undefined
+```
+
+### `withSpan(name, attributes, fn)`
+
+Run a function within a span. Emits an OTEL span when an SDK is active, and a native platform span on Cloudflare (see [Cloudflare Native Traces](#cloudflare-native-traces)). With neither, the function runs directly with zero overhead.
+
+```ts
+import { withSpan } from '@timber-js/app/server';
+
+declare const userId: string;
+declare const db: { users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> } };
+
+const user = await withSpan('db.getUser', { userId }, async () => {
+  return db.users.findUnique({ where: { id: userId } });
+});
+```
+
+The span automatically:
+
+- Creates as a child of the current active span
+- Records exceptions on error
+- Ends when the function completes
+
+### `addSpanEvent(name, attributes?)`
+
+Add an event to the current active span. Used for recording cache hits/misses, checkpoints, etc.
+
+```ts
+import { addSpanEvent } from '@timber-js/app/server';
+
+await addSpanEvent('cache.hit', { key: 'user:123' });
+```
+
+## Cloudflare Native Traces
+
+When you deploy with the Cloudflare adapter, timber's pipeline spans (`timber.proxy`, `timber.middleware`, `timber.access`, `timber.render`, `timber.action`, …) appear **natively in the Cloudflare Observability dashboard** — no OTEL SDK required. They nest alongside Cloudflare's auto-instrumented D1, KV, and `fetch` spans with the same attributes timber emits over OTEL (`http.request.method`, `url.path`, `http.route`, `http.response.status_code`, `timber.result`, …).
+
+This works out of the box:
+
+- The generated `_worker.js` registers timber's spans with the Workers custom spans API (`tracing.enterSpan()` from `cloudflare:workers`).
+- The generated `wrangler.jsonc` enables the trace destination (`observability.traces.enabled`).
+
+To turn native traces off, use the `wrangler` escape hatch:
+
+```ts
+// timber.config.ts
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  adapter: cloudflare({
+    wrangler: { observability: { traces: { enabled: false } } },
+  }),
+};
+```
+
+Native emission is additive — if you also initialize an OTEL SDK in `register()`, spans are emitted on both channels, so external collectors (Honeycomb, Jaeger, Datadog) keep working. `timber.cache` HIT/MISS **span events** are OTEL-only; the Workers span API has no event equivalent.
+
+On runtimes without the custom spans API (older compatibility dates or an outdated local `wrangler`), the worker silently falls back to OTEL-only emission.
+
+## Server-Timing
+
+timber.js can emit `Server-Timing` headers for browser DevTools performance inspection.
+
+```ts
+// timber.config.ts
+export default {
+  serverTiming: 'detailed', // 'detailed' | 'total' | false
+};
+```
+
+| Value        | Description                                                                |
+| ------------ | -------------------------------------------------------------------------- |
+| `'detailed'` | Per-phase timing (proxy, middleware, access, render). Default in dev mode. |
+| `'total'`    | Total request duration only. Default in production.                        |
+| `false`      | No Server-Timing header.                                                   |
+
+View the timings in Chrome DevTools under Network > Timing.
+
+## Log–Trace Correlation
+
+All framework log messages automatically include `trace_id` and `span_id` (when OTEL is active). Custom loggers receive these in the `data` parameter:
+
+```json
+{
+  "msg": "request completed",
+  "method": "GET",
+  "path": "/dashboard",
+  "status": 200,
+  "durationMs": 42,
+  "trace_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
+  "span_id": "1234567890abcdef"
+}
+```
+
+This enables filtering logs by trace ID in your logging backend to see all events for a single request.
+
+## Dev Mode
+
+In development, timber automatically initializes a minimal OTEL SDK with a `DevSpanProcessor` that outputs span information to the dev log. No configuration needed — just run `pnpm dev`.
+
+In production, OTEL spans are only emitted when you initialize an SDK in `register()`.

package/docs/more/07-security.mdx

@@ -0,0 +1,129 @@
+---
+title: 'Security'
+description: 'Built-in CSRF protection, action encryption, redirect safety, and header immutability.'
+slug: 'security'
+---
+
+# Security
+
+timber.js ships with several security protections enabled by default. You don't need to configure most of them — they're structural, built into how the framework handles requests.
+
+## CSRF Protection
+
+All server actions validate the `Origin` header automatically. The `Origin` is compared against the request's full origin (scheme + host + port) — not just the hostname. Behind a reverse proxy, the scheme is derived from `X-Forwarded-Proto`. If the origin doesn't match, the action is rejected with 403. No configuration required.
+
+This protects against cross-site request forgery attacks where a malicious page submits a form to your server. The protection works for both JavaScript-enhanced actions and plain HTML form submissions.
+
+## Server Action Encryption
+
+When a server action captures variables from its closure (bound args), those values are serialized into the RSC payload sent to the client. timber encrypts them with AES-256-GCM before they leave the server.
+
+```tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+declare const db: {
+  products: { find(id: string): Promise<{ id: string; name: string }> };
+  cart: { add(productId: string): Promise<void> };
+};
+declare function AddToCartButton(props: { action: () => Promise<void> }): React.ReactElement;
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await db.products.find(id);
+
+  async function addToCart() {
+    'use server';
+    // `product.id` is a bound arg — encrypted in the client payload
+    await db.cart.add(product.id);
+  }
+
+  return <AddToCartButton action={addToCart} />;
+}
+```
+
+The client receives an opaque, encrypted blob. It can't read or tamper with the bound args — the GCM authentication tag ensures integrity.
+
+### Encryption Key for Multi-Deploy
+
+By default, timber generates a random encryption key per build. This means server actions created by one build can't be decrypted by another. For rolling or blue-green deployments where two builds serve traffic simultaneously, set a shared key:
+
+```bash
+TIMBER_ACTIONS_ENCRYPTION_KEY=<base64-encoded-32-byte-key>
+```
+
+Generate a key:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+```
+
+## Redirect Safety
+
+Open redirect vulnerabilities let an attacker craft a URL on your domain that redirects users to a malicious site (e.g., `/login?next=https://evil.com`). timber prevents this structurally — `redirect()` cannot produce an external redirect.
+
+### `redirect()` is relative-only
+
+The `redirect()` function only accepts relative paths. Absolute URLs and protocol-relative URLs are rejected:
+
+```ts
+import { redirect } from '@timber-js/app/server';
+
+redirect('/dashboard'); // ✅ relative path
+redirect('https://evil.com'); // ❌ throws — absolute URL
+redirect('//evil.com'); // ❌ throws — protocol-relative
+```
+
+This applies everywhere — middleware, access checks, server actions, and server components. There is no code path where `redirect()` can send users off-site.
+
+### `redirectExternal()` with allow-list
+
+When you legitimately need to redirect to an external URL (e.g., an OAuth provider), use `redirectExternal()` with an explicit origin allow-list. Only `http:` and `https:` schemes are permitted:
+
+```ts
+import { redirectExternal } from '@timber-js/app/server';
+
+redirectExternal('https://auth.example.com/login', ['https://auth.example.com']);
+
+// With a custom status code
+redirectExternal('https://docs.example.com/guide', ['https://docs.example.com'], 301);
+```
+
+If the target origin isn't in the allow-list, the scheme isn't http(s), or the URL is invalid, the call throws. This gives you external redirects without the open redirect risk.
+
+<Callout variant="tip" title="vs. Next.js">
+  Next.js `redirect()` accepts absolute URLs by default. In timber, external redirects require an explicit allow-list — open redirect bugs are structurally impossible.
+</Callout>
+
+## Header Immutability
+
+Request headers are immutable after the request enters the pipeline:
+
+- `getHeaders()` returns a frozen, read-only `Headers` object — calling `.set()` or `.delete()` throws
+- Middleware can add headers via `ctx.requestHeaders` (an additive overlay), but cannot delete or modify the original request headers
+- The original `Request` object is never mutated
+
+This prevents a class of middleware bypass attacks where a malicious or buggy middleware could delete authentication headers before they reach access checks.
+
+## Link Safety
+
+The `<Link>` component rejects dangerous URL schemes. Links with `javascript:`, `data:`, or `vbscript:` protocols are blocked at render time, preventing XSS via URL injection.
+
+## Error Information
+
+Unexpected server errors return `{ code: 'INTERNAL_ERROR' }` to the client with no stack trace or internal details. To send structured error data across the boundary, use `deny()` with explicit opt-in:
+
+```ts
+import { deny } from '@timber-js/app/server';
+
+// Only the data you explicitly pass crosses the boundary
+deny({ status: 404, data: { productId: id } });
+```
+
+In development, error details are shown in the browser error overlay. In production, they're suppressed.
+
+## What's Next
+
+- [Authorization](/docs/access-control) — per-segment access control with `access.ts`
+- [Forms & Server Actions](/docs/forms-and-actions) — action clients, validation, and progressive enhancement
+- [Error Handling](/docs/error-handling) — status codes, deny(), and error boundaries