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

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

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

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

package/llms.txt

@@ -0,0 +1,55 @@
+# @timber-js/app
+
+> Vite-native React Server Components framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript.
+
+timber.js is a React framework built on Vite and React Server Components. It uses file-system routing (app/ directory), server components by default, and produces real HTTP status codes. It deploys to Cloudflare Workers, Node.js, Vercel, Netlify, and more via adapters.
+
+It is inspired by, but _not_ next.js. Do not assume next.js features work in timber, though the routing is similar, much of the rest diverges.
+
+## Docs
+
+Documentation ships with this package in the `docs/` directory. All files are MDX.
+
+### Learn (core concepts, read in order)
+
+- [Introduction](docs/learn/00-introduction.mdx)
+- [Quick Start](docs/learn/01-quick-start.mdx)
+- [Pages and Layouts](docs/learn/02-pages-and-layouts.mdx)
+- [Fetching Data](docs/learn/03-fetching-data.mdx)
+- [Access Control](docs/learn/03b-access-control.mdx)
+- [Loading States](docs/learn/04-loading-states.mdx)
+- [The Flush Point](docs/learn/04b-the-flush-point.mdx)
+- [Typed Params](docs/learn/05-typed-params.mdx)
+- [Forms and Actions](docs/learn/06-forms-and-actions.mdx)
+- [Streaming](docs/learn/08-streaming.mdx)
+- [Caching](docs/learn/09-caching.mdx)
+- [Middleware](docs/learn/10-middleware.mdx)
+- [Error Handling](docs/learn/11-error-handling.mdx)
+- [Client Navigation](docs/learn/12-client-navigation.mdx)
+- [Configuration](docs/learn/13-configuration.mdx)
+- [Deploying](docs/learn/14-deploying.mdx)
+
+### More (advanced topics)
+
+- [Advanced Routing](docs/more/01-advanced-routing.mdx)
+- [Advanced Forms](docs/more/02-advanced-forms.mdx)
+- [Coming from Next.js](docs/more/03-coming-from-nextjs.mdx)
+- [Metadata and Fonts](docs/more/04-metadata-and-fonts.mdx)
+- [MDX](docs/more/04b-mdx.mdx)
+- [Content Collections](docs/more/05-content-collections.mdx)
+- [Instrumentation & Tracing](docs/more/06-instrumentation.mdx)
+- [Security](docs/more/07-security.mdx)
+
+### API Reference
+
+- [@timber-js/app/server](docs/api/30-api-server.mdx)
+- [@timber-js/app/client](docs/api/31-api-client.mdx)
+- [@timber-js/app/cache](docs/api/32-api-cache.mdx)
+- [Search & Segment Params](docs/api/33-api-search-params.mdx)
+- [timber.config.ts](docs/api/34-api-config.mdx)
+- [TypeScript](docs/api/35-api-typescript.mdx)
+- [CLI](docs/api/36-cli.mdx)
+
+## AI Agent Skill
+
+A Claude Code skill is included at `agent-skill.md`. Load it for guidance on building timber.js applications.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.153",
+  "version": "0.2.0-alpha.155",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -26,6 +26,9 @@
     "dist",
     "src",
     "bin",
+    "docs",
+    "agent-skill.md",
+    "llms.txt",
     "README.md",
     "LICENSE"
   ],
@@ -159,7 +162,8 @@
     "node": ">=22.18.0"
   },
   "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "copy-docs": "node scripts/copy-docs.js",
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
     "typecheck": "tsgo --noEmit"
   }
 }

package/src/cli.ts

@@ -11,7 +11,7 @@
 //   timber preview  — Serve the production build
 //   timber check    — Validate types + routes without building
 
-const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema'] as const;
+const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
@@ -37,7 +37,7 @@ export interface CommandOptions {
 export function parseArgs(args: string[]): ParsedArgs {
   if (args.length === 0) {
     throw new Error(
-      'No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]'
+      'No command provided. Usage: timber <dev|build|preview|check|schema|init> [--config <path>]'
     );
   }
 
@@ -64,7 +64,7 @@ export function parseArgs(args: string[]): ParsedArgs {
       throw new Error(
         `Unknown option: ${arg}. The timber CLI only accepts --config <path>.${portHint}`
       );
-    } else if (command === 'schema') {
+    } else if (command === 'schema' || command === 'init') {
       rest.push(arg);
     } else {
       throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
@@ -235,6 +235,62 @@ export async function runSchema(args: string[]): Promise<void> {
   }
 }
 
+// ─── Init Subcommand ─────────────────────────────────────────────────────────
+
+/**
+ * `timber init` — write AGENTS.md (and CLAUDE.md pointer) to the project root
+ * so AI coding agents can discover timber.js documentation and conventions.
+ *
+ * The content is read from the installed @timber-js/app package itself, so it
+ * stays in sync with the installed version.
+ */
+export async function runInit(): Promise<void> {
+  const { readFileSync, writeFileSync, existsSync } = await import('node:fs');
+  const { resolve, dirname } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+
+  const root = process.cwd();
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+  const agentSkillPath = resolve(packageRoot, 'agent-skill.md');
+  if (!existsSync(agentSkillPath)) {
+    throw new Error(
+      'agent-skill.md not found in @timber-js/app package. ' +
+        'This may be a development install — try reinstalling.'
+    );
+  }
+
+  const agentSkill = readFileSync(agentSkillPath, 'utf-8');
+
+  const agentsPath = resolve(root, 'AGENTS.md');
+  const claudePath = resolve(root, 'CLAUDE.md');
+
+  const wrote: string[] = [];
+
+  if (existsSync(agentsPath)) {
+    console.log('[timber] AGENTS.md already exists — skipping (delete it first to regenerate)');
+  } else {
+    writeFileSync(agentsPath, agentSkill);
+    wrote.push('AGENTS.md');
+  }
+
+  if (existsSync(claudePath)) {
+    console.log('[timber] CLAUDE.md already exists — skipping (delete it first to regenerate)');
+  } else {
+    writeFileSync(claudePath, 'Read AGENTS.md for project context and conventions.\n');
+    wrote.push('CLAUDE.md');
+  }
+
+  if (wrote.length > 0) {
+    console.log(
+      `[timber] Created ${wrote.join(' and ')} — AI agents can now discover timber.js docs.`
+    );
+    console.log('[timber] Full documentation: node_modules/@timber-js/app/docs/');
+  } else {
+    console.log('[timber] Nothing to do — both files already exist.');
+  }
+}
+
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
@@ -257,6 +313,9 @@ async function main(): Promise<void> {
     case 'schema':
       await runSchema(parsed.rest);
       break;
+    case 'init':
+      await runInit();
+      break;
   }
 }
 

package/src/client/browser-entry/action-dispatch.ts

@@ -66,6 +66,20 @@ export function setupServerActions(): void {
     // instead of returning HTTP 302. Perform a client-side SPA navigation.
     if (hasRedirect) {
       const wrapper = decoded as { _redirect: string; _status: number };
+
+      // External redirects (e.g., OAuth flows via redirectExternal()) must
+      // use a full page navigation — the RSC router can only fetch same-origin
+      // payloads. On browsers with the Navigation API, navigation.navigate()
+      // happens to perform a real cross-origin navigation, but browsers
+      // without it (iPad Safari) would attempt an RSC fetch that fails on CORS.
+      const isExternal =
+        wrapper._redirect.startsWith('https://') || wrapper._redirect.startsWith('http://');
+      if (isExternal) {
+        setHardNavigating(true);
+        window.location.href = wrapper._redirect;
+        return undefined;
+      }
+
       try {
         const router = getRouter();
         void router.navigate(wrapper._redirect);

package/src/server/pipeline-metadata.ts

@@ -41,6 +41,7 @@ export async function serveStaticMetadataFile(
   const headers: Record<string, string> = {
     'Content-Type': isText ? `${contentType}; charset=utf-8` : contentType,
     'Content-Length': String(body.byteLength),
+    'Cache-Control': 'public, max-age=14400, must-revalidate',
   };
 
   return new Response(body, { status: 200, headers });

package/src/server/pipeline-phases.ts

@@ -316,7 +316,10 @@ export async function handleRequest(
         }
         return new Response(body, {
           status: 200,
-          headers: { 'Content-Type': `${contentType}; charset=utf-8` },
+          headers: {
+            'Content-Type': `${contentType}; charset=utf-8`,
+            'Cache-Control': 'public, max-age=14400, must-revalidate',
+          },
         });
       } catch (error) {
         // Control-flow signals from the metadata handler (e.g. a sitemap that

package/src/server/sitemap-handler.ts

@@ -111,7 +111,10 @@ export function createAutoSitemapHandler(
       const xml = result.type === 'single' ? result.xml : result.indexXml;
       return new Response(xml, {
         status: 200,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'Cache-Control': 'public, max-age=14400, must-revalidate',
+        },
       });
     }
 
@@ -125,7 +128,10 @@ export function createAutoSitemapHandler(
         if (pageIndex === 0) {
           return new Response(result.xml, {
             status: 200,
-            headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+            headers: {
+              'Content-Type': 'application/xml; charset=utf-8',
+              'Cache-Control': 'public, max-age=14400, must-revalidate',
+            },
           });
         }
         return new Response(null, { status: 404 });
@@ -138,7 +144,10 @@ export function createAutoSitemapHandler(
       }
       return new Response(pageXml, {
         status: 200,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'Cache-Control': 'public, max-age=14400, must-revalidate',
+        },
       });
     }