@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/docs/more/06-instrumentation.mdx

@@ -1,214 +0,0 @@
----
-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

@@ -1,129 +0,0 @@
----
-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

package/docs/more/08-developer-experience.mdx

@@ -1,134 +0,0 @@
----
-title: 'Developer Experience'
-description: 'Dev logging, hydration diffs, Server-Timing headers, build reports, and more.'
-slug: 'developer-experience'
----
-
-# Developer Experience
-
-timber.js includes a suite of development tools that surface what your app is doing — where time is spent, what's cached, where errors come from — without reaching for external profiling tools.
-
-## Dev Logging
-
-Every request in development emits a structured tree to `stderr` showing the full execution pipeline with timing:
-
-```
-POST /dashboard/projects/123  trace_id: 4bf92f3577b34da6a3ce929d0e0e4736
-├─ [proxy]   proxy.ts                               0ms →  2ms
-├─ [rsc]     middleware.ts                           2ms →  4ms
-│  ├── fired: requireUser()                    (timber.cache prefetch)
-│  ├── fired: getProject("123")               (timber.cache prefetch)
-│  └── fired: getTaskCounts("123")            (timber.cache prefetch)
-├─ [rsc]     render                                 4ms
-│  ├─ [rsc]  AccessGate (authenticated)             4ms →  5ms
-│  │  └── requireUser()                        timber.cache HIT  <1ms
-│  ├─ [rsc]  ProjectPage                            8ms → 12ms
-│  │  └── getTaskCounts("123")                 timber.cache HIT  <1ms
-│  └── onShellReady                                12ms
-├─ [ssr]     hydration render                      13ms → 18ms
-└─ ✓ 200 OK                              total    18ms
-```
-
-The tree mirrors the execution structure. `[rsc]`/`[ssr]`/`[client]` labels show which Vite environment each phase runs in. Cache hits and misses are annotated inline.
-
-### Fetch Instrumentation
-
-`fetch()` calls from server components appear as children of the component that made them:
-
-```
-├─ [rsc]  page /                              6ms → 101ms
-│     ├─ fetch GET https://api.example.com/products  12ms → 89ms (77ms)
-│     └─ fetch GET https://api.example.com/user      12ms → 45ms (33ms) [cdn: HIT]
-```
-
-Start times reveal whether fetches ran concurrently or sequentially. Cache status from `X-Cache` or `CF-Cache-Status` headers is surfaced automatically. Fetch instrumentation is dev-only — `globalThis.fetch` is not patched in production.
-
-### Log Modes
-
-Control the verbosity with `TIMBER_DEV_LOG`:
-
-| Mode      | Output                                                     |
-| --------- | ---------------------------------------------------------- |
-| `tree`    | Full indented tree per request (default)                   |
-| `verbose` | Detailed tree showing every component render               |
-| `summary` | One line per request: `POST /path → 200 OK  18ms`         |
-| `json`    | Chronological NDJSON of all spans with full attributes     |
-
-Suppress all dev logging with `TIMBER_DEV_QUIET=1`.
-
-### Slow Phase Warnings
-
-Phases that exceed a configurable threshold are highlighted in the tree output. The default is 200ms:
-
-```ts title="timber.config.ts"
-export default {
-  dev: {
-    slowPhaseMs: 200,
-  },
-};
-```
-
-This surfaces performance bottlenecks during development without requiring explicit profiling.
-
-## Server-Timing Header
-
-timber.js emits a `Server-Timing` HTTP header for every response. The level of detail is configurable:
-
-| Value        | Output                                                   | Default in  |
-| ------------ | -------------------------------------------------------- | ----------- |
-| `'detailed'` | Per-phase breakdown: proxy, middleware, render, SSR       | Development |
-| `'total'`    | Single `total;dur=N` entry                               | Production  |
-| `false`      | No header                                                | —           |
-
-```ts title="timber.config.ts"
-export default {
-  serverTiming: 'detailed',
-};
-```
-
-In production, you can opt into `'detailed'` for APM integration — browser DevTools and monitoring tools parse `Server-Timing` automatically.
-
-## Hydration Mismatch Diff
-
-When React 19 detects a hydration mismatch, timber parses the diff and renders it with color-coded lines:
-
-- Green (`+`) lines show the client-side markup
-- Red (`-`) lines show the server-side markup
-
-This replaces Vite's plain-text rendering of hydration errors, making mismatches easy to spot and fix. Multiple hydration errors accumulate in the same overlay.
-
-## Error Overlay
-
-Errors during development are shown in a browser overlay with:
-
-- **Component stacks** — the React component hierarchy leading to the error
-- **Phase labels** — whether the error occurred in middleware, access check, RSC render, SSR, or a client component
-- **Source-mapped stack traces** — pointing to your original source files
-
-Client-side errors are forwarded to the overlay via Vite's HMR channel, so they get the same treatment as server errors.
-
-## Compiling Indicator
-
-A small "Compiling…" indicator appears in the bottom-left corner during HMR updates. It has a 200ms debounce — fast updates never show it. It fades out when the update completes.
-
-## Build Report
-
-After `timber build`, a route table shows every route with its bundle size, route type, and first-load JS:
-
-| Symbol | Meaning        |
-| ------ | -------------- |
-| ○      | Static page    |
-| λ      | Dynamic (SSR)  |
-| ƒ      | API route      |
-
-This helps identify large bundles and verify route classification.
-
-## HTTPS / HTTP-2 Dev Server
-
-timber supports `server.https` in your Vite config for local HTTPS development. The request scheme is derived from the TLS socket (not hardcoded), so CSRF protection works correctly under HTTPS. HTTP/2 pseudo-headers are handled automatically.
-
-## What's Next
-
-- [Instrumentation](/docs/instrumentation) — production tracing with OpenTelemetry
-- [Configuration](/docs/configuration) — all config options
-- [Streaming](/docs/streaming) — Suspense placement and `deferSuspenseFor`

package/docs/more/40-why-timber.mdx

@@ -1,50 +0,0 @@
----
-title: 'Why timber.js?'
-description: 'The design decisions behind timber.js and why they matter.'
-slug: 'why-timber'
----
-
-# Why timber.js?
-
-timber.js exists because we think the current generation of React frameworks made a wrong turn on streaming.
-
-## The Premise
-
-Most React frameworks stream HTML as fast as possible. The moment the server starts rendering, bytes go to the browser. This sounds great in theory — faster Time to First Byte, progressive rendering, the user sees _something_ sooner.
-
-The cost is real:
-
-- **Every page returns HTTP 200.** A 404? That's a 200 with an error boundary. A redirect? That's a 200 with client-side navigation. A 500? Also 200. Once you start streaming, you've committed the status code.
-- **Pages don't work without JavaScript.** The client needs JS to resolve suspense boundaries, handle error states, and execute redirects that the server couldn't express through HTTP.
-- **Loading states everywhere.** `loading.tsx` exists because the framework sends the shell before data is ready. Now you're designing skeleton states for every route, managing layout shift, and adding perceived complexity.
-
-## What timber.js Does Differently
-
-timber.js holds the response until the shell is ready. That's the content outside `<Suspense>` boundaries — the stuff that actually determines the page's HTTP status, headers, and primary content.
-
-The trade-off is roughly 20ms of server-side buffering before the first byte. In exchange:
-
-- **Real status codes.** `deny(404)` sends a genuine HTTP 404. CDNs cache it correctly. Search engines deindex it. `curl` sees it. APM tools report it.
-- **Pages work without JavaScript.** The initial render arrives complete. No JS needed to show the primary content.
-- **No implicit loading states.** There's no `loading.tsx`. If you want a loading state, you place a `<Suspense>` boundary explicitly around the slow content — and you choose where.
-
-Secondary content (reviews on a product page, comments on a post) can still stream via `<Suspense>`. You decide where the flush boundary sits. The framework doesn't decide for you.
-
-## What timber.js is Not
-
-This is not a framework for every use case. It's opinionated about a few things:
-
-- **Server-first rendering.** If you're building a single-page app with no server, this isn't the right tool.
-- **Explicit over implicit.** There's no magic caching, no implicit data fetching, no hidden loading states. You opt into each behavior.
-- **Smaller API surface.** We'd rather have fewer features that work correctly than many features with edge cases.
-
-Next.js is more mature, more battle-tested, and supports more use cases. If you're happy with it, there's no reason to switch. timber.js is for people who've run into the limitations of streaming-first and want HTTP semantics that work.
-
-## Built on Vite
-
-timber.js is a Vite plugin, not a standalone build system. You get Vite's ecosystem: sub-second HMR, the plugin ecosystem, native ESM, and Rolldown for production builds. Your `vite.config.ts` stays normal — timber.js adds to it, it doesn't replace it.
-
-## What's Next
-
-- [Getting Started](/docs/quick-start) — create a project in under five minutes
-- [timber.js vs Next.js](/docs/timber-vs-nextjs) — an honest comparison

package/docs/more/41-timber-vs-nextjs.mdx

@@ -1,81 +0,0 @@
----
-title: 'timber.js vs Next.js'
-description: 'An honest comparison of timber.js and Next.js — where they differ and why.'
-slug: 'timber-vs-nextjs'
----
-
-# timber.js vs Next.js
-
-Next.js is the most widely used React framework. It's mature, well-documented, and backed by Vercel. timber.js would not exist without it — the app directory routing model, server components, and many API patterns are directly inspired by Next.js.
-
-That said, we made different design decisions in a few areas. Here's an honest comparison.
-
-## HTTP Semantics
-
-| Behavior           | Next.js                                          | timber.js                                        |
-| ------------------ | ------------------------------------------------ | ------------------------------------------------ |
-| Status codes       | Always 200 (streaming commits early)             | Real status codes (flush held until shell ready) |
-| 404 pages          | 200 + `not-found.tsx` error boundary             | HTTP 404 + `404.tsx`                             |
-| Redirects in pages | Client-side via `redirect()` after 200           | HTTP 302/301 before any bytes sent               |
-| Works without JS   | Partially (primary content yes, interactions no) | Fully (forms, navigation, status codes all work) |
-
-This is the core philosophical difference. Next.js optimizes for earliest possible TTFB. timber.js optimizes for correct HTTP responses, at the cost of ~20ms additional server buffering.
-
-## Streaming
-
-Both frameworks support React Suspense streaming. The difference is when it starts:
-
-- **Next.js:** Streams immediately. `loading.tsx` renders while data loads. Status code is already committed.
-- **timber.js:** Holds until the shell is ready (everything outside `<Suspense>`). Then streams Suspense content. No `loading.tsx` — `<Suspense>` is opt-in only.
-
-## Routing
-
-Both use file-system routing in an `app/` directory. The models are similar:
-
-- Layouts, pages, dynamic segments, catch-all routes — same patterns
-- Parallel routes (slots) — both support `@sidebar`, `@modal` patterns
-- Route groups — both support `(group)` directories
-
-**Differences:**
-
-- **Middleware:** Next.js has a single global `middleware.ts`. timber.js has per-segment `middleware.ts` files.
-- **Authorization:** timber.js has `access.ts` files for per-segment access control with `deny()`. Next.js uses middleware or in-component checks.
-- **Typed routes:** timber.js generates route types at build time — `<Link>` type-checks `href` and params.
-
-## Caching
-
-| Behavior          | Next.js                                              | timber.js                                             |
-| ----------------- | ---------------------------------------------------- | ----------------------------------------------------- |
-| `fetch()` caching | Cached by default (opt out with `cache: 'no-store'`) | Never cached (explicit is better)                     |
-| Cache API         | `unstable_cache` / `'use cache'`                     | `timber.cache()` with TTL, tags, staleWhileRevalidate |
-| Revalidation      | `revalidateTag()`, `revalidatePath()`                | `revalidateTag()`                                     |
-
-timber.js takes the position that implicit caching causes more bugs than it prevents. Nothing is cached unless you wrap it in `timber.cache()`.
-
-## Build System
-
-|                  | Next.js             | timber.js                             |
-| ---------------- | ------------------- | ------------------------------------- |
-| Bundler          | Turbopack / Webpack | Vite 7 (Rolldown)                     |
-| Config           | `next.config.js`    | `vite.config.ts` + `timber.config.ts` |
-| Plugin ecosystem | Next.js-specific    | Full Vite plugin ecosystem            |
-
-## Platform Support
-
-Next.js is optimized for Vercel and works on other platforms through community adapters. timber.js ships a first-party Cloudflare Workers adapter and a Nitro adapter that covers Node.js, Vercel, Bun, Netlify, AWS Lambda, and more.
-
-## When to Use Next.js
-
-- You need the largest ecosystem and community support
-- You're deploying to Vercel
-- You need features timber.js hasn't built yet (image optimization, ISR, etc.)
-- Your team is already productive with Next.js
-
-## When to Use timber.js
-
-- You care about correct HTTP status codes and headers
-- You want pages that work fully without JavaScript
-- You're deploying to Cloudflare Workers
-- You prefer explicit caching over implicit
-- You want per-segment middleware and authorization
-- You want Vite's build speed and plugin ecosystem

package/docs/more/42-timber-vs-others.mdx

@@ -1,68 +0,0 @@
----
-title: 'timber.js vs Other Frameworks'
-description: 'How timber.js compares to Vinext, Remix, and other React server frameworks.'
-slug: 'timber-vs-others'
----
-
-# timber.js vs Other Frameworks
-
-Beyond Next.js, there are several React frameworks worth comparing against. Each makes different trade-offs.
-
-## Vinext (Cloudflare)
-
-Vinext is Cloudflare's implementation of Next.js on Vite. It aims for Next.js API compatibility running natively on Cloudflare Workers.
-
-**Shared ground:** Both timber.js and Vinext target Cloudflare Workers, use Vite, and support React Server Components.
-
-**Key differences:**
-
-|              | Vinext                                 | timber.js                                |
-| ------------ | -------------------------------------- | ---------------------------------------- |
-| Goal         | Next.js compatibility on Vite          | Independent design, different trade-offs |
-| Streaming    | Streams immediately (Next.js behavior) | Holds until shell ready                  |
-| Status codes | 200 for everything (Next.js behavior)  | Real HTTP status codes                   |
-| API surface  | Next.js-compatible                     | Similar but divergent where we disagree  |
-| Caching      | Next.js caching model                  | Explicit-only caching                    |
-
-If you want Next.js on Cloudflare with minimal code changes, Vinext is the right choice. If you want a different rendering model with correct HTTP semantics, that's timber.js.
-
-## Remix / React Router
-
-Remix (now React Router v7) pioneered many of the ideas timber.js agrees with: progressive enhancement, forms that work without JavaScript, and server-first rendering.
-
-**Shared philosophy:**
-
-- Forms should work without JS
-- Server rendering is the default
-- Progressive enhancement over client-side-first
-
-**Key differences:**
-
-|               | Remix / React Router                 | timber.js                                |
-| ------------- | ------------------------------------ | ---------------------------------------- |
-| Routing model | Flat route config or file convention | Nested `app/` directory (Next.js-style)  |
-| Data loading  | `loader` / `action` functions        | Async server components + server actions |
-| RSC support   | Not yet (planned)                    | Built on RSC from day one                |
-| Streaming     | Supports `defer()` for streaming     | `<Suspense>` with explicit flush point   |
-| Build system  | Vite (React Router v7)               | Vite                                     |
-
-Remix's `loader`/`action` model is elegant and well-understood. timber.js bets on RSC as the data loading primitive — your components are your data layer.
-
-## TanStack Start
-
-TanStack Start is a full-stack React framework from the TanStack Router team.
-
-**Shared ground:** Both use Vite, both aim for good TypeScript support, both support server-side rendering.
-
-**Key differences:**
-
-|                | TanStack Start                          | timber.js                                  |
-| -------------- | --------------------------------------- | ------------------------------------------ |
-| Routing        | TanStack Router (code-based, type-safe) | File-system routing with generated types   |
-| Data loading   | TanStack Query integration              | Async server components + `timber.cache()` |
-| RSC support    | Experimental                            | Core architecture                          |
-| Platform focus | General-purpose                         | Cloudflare-first, works everywhere         |
-
-## Summary
-
-Every framework makes trade-offs. timber.js trades streaming speed for HTTP correctness and trades API surface size for explicitness. If those trade-offs align with how you think about web development, it's worth trying. If they don't, the frameworks above are all excellent choices.