@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/docs/learn/10-caching.mdx

@@ -16,7 +16,7 @@ This is the number one confusion point. They are different things:
 | ------------------- | --------------------------- | -------------------- |
 | Scope               | Cross-request (persistent)  | Single request       |
 | TTL/tags            | Yes                         | No                   |
-| Works in middleware  | Yes                         | No                   |
+| Works in middleware | Yes                         | Yes (same request)   |
 | Use case            | Database queries, API calls | Request-scoped dedup |
 
 `React.cache` deduplicates within a single request — if three components call `getUser(id)`, only one database query runs. `timber.cache` persists across requests with TTL — the same query serves cached results for 60 seconds.
@@ -58,10 +58,10 @@ const getUser = cache.data(
     return db.users.findUnique({ where: { id: userId } });
   },
   {
-    ttl: 60,                                   // Cache for 60 seconds
-    key: (userId) => `user:${userId}`,         // Explicit cache key (optional)
-    staleWhileRevalidate: true,                // Serve stale while refetching
-    tags: (userId) => [`user:${userId}`],      // For tag-based invalidation
+    ttl: 60, // Cache for 60 seconds
+    key: (userId) => `user:${userId}`, // Explicit cache key (optional)
+    staleWhileRevalidate: true, // Serve stale while refetching
+    tags: (userId) => [`user:${userId}`], // For tag-based invalidation
   }
 );
 ```
@@ -101,7 +101,18 @@ revalidateTag('products');
 revalidateTag(`user:${userId}`);
 ```
 
-Invalidation wins races against in-flight cached functions: if a cached function is mid-execution when you invalidate one of its tags (the usual mutation flow — update the database, then `revalidateTag`), its result is not written back to the cache, and callers arriving after the invalidation re-execute instead of joining the superseded execution. This guard is per-process; with a shared handler (Redis/KV), an invalidation from a *different* instance can still race a concurrent write on this one.
+`revalidateTag` works outside actions too. From a `route.ts` handler, say a CMS webhook, it invalidates immediately, and you await it before responding:
+
+```ts title="app/api/cms-webhook/route.ts"
+export async function POST(ctx: RouteContext) {
+  await revalidateTag('products');
+  return new Response(null, { status: 204 });
+}
+```
+
+`revalidatePath` is different: it re-renders a page into a server action's response, so it only works inside an action.
+
+Invalidation wins races against in-flight cached functions: if a cached function is mid-execution when you invalidate one of its tags (the usual mutation flow — update the database, then `revalidateTag`), its result is not written back to the cache, and callers arriving after the invalidation re-execute instead of joining the superseded execution. This guard is per-process; with a shared handler (Redis/KV), an invalidation from a _different_ instance can still race a concurrent write on this one.
 
 ## `staleWhileRevalidate`
 
@@ -129,7 +140,12 @@ const PostBody = cache.component(
   async function PostBody() {
     const { slug } = getSegmentParams();
     const post = await getPost(slug);
-    return <article><h1>{post.title}</h1><PostContent content={post.content} /></article>;
+    return (
+      <article>
+        <h1>{post.title}</h1>
+        <PostContent content={post.content} />
+      </article>
+    );
   },
   { prerender: true }
 );
@@ -188,10 +204,10 @@ export default async function BlogPost() {
   const user = await getUser(getCookieJar());
   return (
     <>
-      <Nav user={user} />           {/* dynamic — personalized */}
-      <PostBody />                   {/* prerendered — from build artifact */}
+      <Nav user={user} /> {/* dynamic — personalized */}
+      <PostBody /> {/* prerendered — from build artifact */}
       <Suspense fallback={<CommentsSkeleton />}>
-        <Comments />                 {/* dynamic — streams per-request */}
+        <Comments /> {/* dynamic — streams per-request */}
       </Suspense>
     </>
   );
@@ -230,7 +246,9 @@ const Shell = cache.component(ExpensiveWrapper, {
 });
 
 // The shell serves from cache; children render live per request.
-<Shell theme="dark"><LiveUserFeed /></Shell>
+<Shell theme="dark">
+  <LiveUserFeed />
+</Shell>;
 ```
 
 Slot props are excluded from the cache key. Slots are runtime tier only — `prerender` is ignored when `slots` is active.

package/docs/learn/11-middleware.mdx

@@ -27,10 +27,16 @@ Before diving in, the first question: should this be middleware or `access.ts`?
 | ------------- | -------------------------------------- | --------------------------------- |
 | Runs          | Before rendering                       | Inside React tree                 |
 | Purpose       | Headers, redirects, cache warming      | Auth, data gating                 |
-| `React.cache` | Not available                          | Active — shares scope with layout |
+| `React.cache` | Active — shares scope with the render  | Active — shares scope with layout |
 | Slots         | N/A                                    | Graceful degradation              |
 
-Use `middleware.ts` for request-level decisions: should this request proceed? What headers does it need? Use `access.ts` for auth — it has `React.cache` and supports slot degradation.
+Use `middleware.ts` for request-level decisions: should this request proceed? What headers does it need? Use `access.ts` for auth — it gates each segment, renders status pages with `deny()`, and supports slot degradation.
+
+Both share one `React.cache` scope per request with your layouts and pages. A `React.cache`-wrapped `getUser()` called in middleware, `access.ts`, and a layout runs once. Middleware is a good place to start that fetch early.
+
+If middleware changes a cookie, cached functions that already read it keep their old result. Have them take the cookie value as an argument (see [Fetching Data](/docs/fetching-data)); in development timber warns when this happens.
+
+Middleware runs once, root to leaf, before any `access.ts`. A child `middleware.ts` that returns a `Response` responds before a parent's `access.ts` runs. Put authorization that must cover a whole subtree in `access.ts` or in a parent `middleware.ts`.
 
 ## `proxy.ts` — Global Middleware
 

package/docs/learn/12-error-handling.mdx

@@ -111,21 +111,26 @@ The general error boundary. It's a client component:
 
 export default function DashboardError({
   error,
+  digest,
   reset,
 }: {
   error: Error;
+  digest: string | null;
   reset: () => void;
 }) {
   return (
     <div>
       <h2>Something went wrong</h2>
       <p>{error.message}</p>
+      {digest && <p>Reference: {digest}</p>}
       <button onClick={reset}>Try again</button>
     </div>
   );
 }
 ```
 
+`digest` is the ID the server logged the error with: the `errorId` field on its log line. In production `error.message` is a generic string, so the digest is what a reader can quote to you and what you search your logs for. It is `null` when the boundary is serving a `deny()`, and for an error the server logged without an ID: one thrown in the browser, one a client component throws while the page renders on the server, or one raised before the page renders (a module that fails to load, say).
+
 Error boundaries wrap page content inside layouts — the layout shell (nav, sidebar) stays visible when an error fires.
 
 A status page renders inside the layouts **above and including the segment it lives in**, and none below it. A root `404.tsx` serving a `deny(404)` from `app/docs/[slug]/page.tsx` renders inside the root layout only — `docs/layout.tsx` and `[slug]/layout.tsx` do not appear, because the file that matched lives above them. Co-locate the status file with the segment whose chrome you want kept: move that `404.tsx` to `app/docs/` and the docs layout comes with it.
@@ -184,4 +189,4 @@ if (!product) {
 }
 ```
 
-The status-code file receives the structured data as the `data` prop, surviving the RSC → client boundary where plain error properties are stripped.
+The status-code file receives the structured data as the `data` prop, surviving the RSC → client boundary where plain error properties are stripped. This works for any 4xx or 5xx status: `deny(503, { dangerouslyPassData })` renders `503.tsx` (or `5xx.tsx`, or `error.tsx`) with its `data`. A plain `throw` is for failures you did not plan for: outside `<Suspense>` it renders the error page with a 500, and in production the page gets a generic message and a `digest` to find the log line by.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.207",
+  "version": "0.2.0-alpha.209",
   "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",
@@ -133,6 +133,10 @@
       "types": "./dist/adapters/nitro.d.ts",
       "import": "./dist/adapters/nitro.js"
     },
+    "./adapters/types": {
+      "types": "./dist/adapters/types.d.ts",
+      "import": "./dist/adapters/types.js"
+    },
     "./fonts/google": {
       "types": "./dist/shims/font-google.d.ts",
       "import": "./dist/shims/font-google.js"
@@ -165,8 +169,8 @@
     "@vitejs/plugin-react": "^6.1.0",
     "@vitejs/plugin-rsc": ">=0.5.35",
     "nuqs": "^2.0.0",
-    "react": "19.3.0",
-    "react-dom": "19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "satteri": "^0.9.5",
     "vite": "8.3.0",
     "vite-plugin-satteri": "^0.2.15",

package/src/adapters/build-output-helper.ts

@@ -23,15 +23,20 @@ import {
   USER_PLATFORM_DIR,
 } from '../shared/static-platform-files.ts';
 import { detectFsIdentity, fsKey } from './fs-identity.ts';
-import type { TimberConfig } from './types.ts';
+import type {
+  BuildArtifacts,
+  ServerBuildArtifacts,
+  StaticBuildArtifacts,
+  TimberConfig,
+} from './types.ts';
 
 /** Options for the shared build output steps. */
 export interface BuildOutputBaseOptions {
   /** Resolved timber config. */
   config: TimberConfig;
-  /** Root build directory (e.g. `.timber/build`). */
-  buildDir: string;
-  /** Adapter-specific output directory (e.g. `.timber/build/nitro`). */
+  /** What the build produced. */
+  artifacts: ServerBuildArtifacts;
+  /** Adapter-specific output directory (e.g. `.timber/dist/nitro`). */
   outDir: string;
   /**
    * Name of the public/static directory within outDir.
@@ -52,7 +57,7 @@ export interface BuildOutputBaseOptions {
  * Returns the resolved public directory path for further adapter-specific use.
  */
 export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {
-  const { config, buildDir, outDir, publicDirName } = opts;
+  const { config, artifacts, outDir, publicDirName } = opts;
 
   // 1. Create the output directory.
   await mkdir(outDir, { recursive: true });
@@ -60,9 +65,9 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
   // 2. Copy client assets to public/static directory.
   // When client JavaScript is disabled, skip .js files — only CSS,
   // fonts, images, and other static assets are needed.
-  const clientDir = join(buildDir, 'client');
   const publicDir = join(outDir, publicDirName);
   await mkdir(publicDir, { recursive: true });
+  const clientDir = artifacts.client.path;
   // Find WASM files that are referenced by client JS (legitimate client WASM)
   // vs orphaned server-only WASM (e.g. @takumi-rs for OG image generation).
   // Only strip orphaned WASM to avoid breaking client-side WASM usage.
@@ -77,39 +82,31 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
       if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;
       return true;
     },
-  }).catch((e: NodeJS.ErrnoException) => {
-    // Client dir may not exist when client JavaScript is disabled
-    if (e.code !== 'ENOENT') throw e;
   });
 
   // 3. Write _headers file for static asset cache control.
   // Scan for unhashed files so they get per-file Cache-Control rules in the
   // _headers file. On platforms like Cloudflare Workers Static Assets, the
   // worker never sees static file requests — _headers is the only mechanism.
-  await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
+  await writeHeadersFile(publicDir, config, artifacts);
 
-  // 4. Copy RSC + SSR server bundles into the output directory.
-  await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
-  await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(
-    (e: NodeJS.ErrnoException) => {
-      // SSR dir may not exist for static-only builds
-      if (e.code !== 'ENOENT') throw e;
-    }
-  );
+  // 4. Copy RSC + SSR server bundles into the output directory. The RSC
+  // bundle imports the SSR one by a path the RSC plugin computed between the
+  // two *build* directories, which the build names `rsc/` and `ssr/` as
+  // siblings (index.ts); deploying them under the same names keeps it valid.
+  await cp(artifacts.rsc.path, join(outDir, 'rsc'), { recursive: true });
+  await cp(artifacts.ssr.path, join(outDir, 'ssr'), { recursive: true });
 
-  // 4b. Copy prebuilt/ flight payloads if present (cache.component artifacts).
-  // These are produced by the post-build capture pass (design/44) and read
-  // at request time via the adapter's PrebuiltPayloadSource.
-  await cp(join(buildDir, 'prebuilt'), join(outDir, 'prebuilt'), { recursive: true }).catch(
-    (e: NodeJS.ErrnoException) => {
-      // No prebuilt dir when the app has no cache.component calls
-      if (e.code !== 'ENOENT') throw e;
-    }
-  );
+  // 4b. Copy prebuilt/ flight payloads (cache.component artifacts). These
+  // are produced by the post-build capture pass (design/44) and read at
+  // request time via the adapter's PrebuiltPayloadSource.
+  if (artifacts.prebuilt) {
+    await cp(artifacts.prebuilt.path, join(outDir, 'prebuilt'), { recursive: true });
+  }
 
   // 5. Write manifest-init module if present.
-  if (config.manifestInit) {
-    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
+  if (artifacts.manifestInit) {
+    await writeFile(join(outDir, '_timber-manifest-init.js'), artifacts.manifestInit);
   }
 
   return publicDir;
@@ -120,9 +117,16 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
  * Cache-Control rules in the `_headers` file.
  *
  * Excludes:
- * - Files under `assets/` and `_timber/` (covered by wildcard rules)
+ * - Files under the build's `immutableDirs` (covered by wildcard rules)
+ * - Files under `rsc/` and `ssr/` (server bundles, never served)
  * - Underscore-prefixed files (`_headers`, `_worker.js`, etc.)
  *
+ * Ordered for the rule cap: well-known metadata files, then everything
+ * else, then files under an underscore-prefixed directory — the
+ * framework's own output (unhashed RSC payloads in a static build with
+ * client JavaScript disabled, which nothing fetches). Those can number one
+ * per route, and must not take the budget from the app's real files.
+ *
  * @internal Exported for testing.
  */
 // Well-known metadata files that should be prioritized when capping
@@ -136,7 +140,10 @@ const PRIORITY_FILES = new Set([
   '/apple-touch-icon.png',
 ]);
 
-export async function findUnhashedStaticFiles(publicDir: string): Promise<string[]> {
+export async function findUnhashedStaticFiles(
+  publicDir: string,
+  immutableDirs: readonly string[]
+): Promise<string[]> {
   let files: string[];
   try {
     files = await collectFiles(publicDir);
@@ -146,20 +153,23 @@ export async function findUnhashedStaticFiles(publicDir: string): Promise<string
 
   const priority: string[] = [];
   const rest: string[] = [];
+  const framework: string[] = [];
   for (const file of files) {
     const rel = relative(publicDir, file).replace(/\\/g, '/');
-    if (rel.startsWith('assets/') || rel.startsWith('_timber/')) continue;
-    if (rel.startsWith('rsc/') || rel.startsWith('ssr/') || rel.startsWith('_rsc/')) continue;
+    if (immutableDirs.some((dir) => rel.startsWith(`${dir}/`))) continue;
+    if (rel.startsWith('rsc/') || rel.startsWith('ssr/')) continue;
     if (basename(rel).startsWith('_')) continue;
     const urlPath = '/' + rel;
     if (PRIORITY_FILES.has(urlPath)) {
       priority.push(urlPath);
+    } else if (rel.startsWith('_')) {
+      framework.push(urlPath);
     } else {
       rest.push(urlPath);
     }
   }
 
-  return [...priority.sort(), ...rest.sort()];
+  return [...priority.sort(), ...rest.sort(), ...framework.sort()];
 }
 
 /**
@@ -169,13 +179,7 @@ export async function findUnhashedStaticFiles(publicDir: string): Promise<string
  */
 async function findReferencedWasm(clientDir: string): Promise<Set<string>> {
   const referenced = new Set<string>();
-
-  let files: string[];
-  try {
-    files = await collectFiles(clientDir);
-  } catch {
-    return referenced;
-  }
+  const files = await collectFiles(clientDir);
 
   const jsFiles = files.filter((f) => f.endsWith('.js'));
   const wasmFiles = files.filter((f) => f.endsWith('.wasm')).map((f) => basename(f));
@@ -200,7 +204,7 @@ async function findReferencedWasm(clientDir: string): Promise<Set<string>> {
  */
 export async function buildStaticDirectoryOutput(
   config: TimberConfig,
-  buildDir: string,
+  artifacts: StaticBuildArtifacts,
   outDir: string,
   publicDirName: string
 ): Promise<void> {
@@ -214,15 +218,12 @@ export async function buildStaticDirectoryOutput(
   await mkdir(publicDir, { recursive: true });
 
   // Copy client assets (JS, CSS, fonts, images).
-  const clientDir = join(buildDir, 'client');
-  await cp(clientDir, publicDir, {
+  await cp(artifacts.client.path, publicDir, {
     recursive: true,
     filter: (src: string) => {
       if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;
       return true;
     },
-  }).catch((e: NodeJS.ErrnoException) => {
-    if (e.code !== 'ENOENT') throw e;
   });
 
   // Copy pre-rendered static pages (HTML + RSC flight + API routes).
@@ -231,10 +232,8 @@ export async function buildStaticDirectoryOutput(
   // into a single directory, and `cp` resolves an overlap by overwriting with
   // no diagnostic — the deployment then contains one of the two artifacts and
   // nothing recorded which. Refuse instead (TIM-1266).
-  if (config.staticPagesDir) {
-    await assertNoTreeCollision(config.staticPagesDir, publicDir);
-    await cp(config.staticPagesDir, publicDir, { recursive: true });
-  }
+  await assertNoTreeCollision(artifacts.pages.path, publicDir);
+  await cp(artifacts.pages.path, publicDir, { recursive: true });
 }
 
 /**
@@ -265,15 +264,18 @@ export async function buildStaticDirectoryOutput(
 export async function writeHeadersFile(
   dir: string,
   config: TimberConfig,
-  unhashedPaths: string[]
+  artifacts: BuildArtifacts
 ): Promise<void> {
   const userRules = await readUserPlatformFile(config.root, HEADERS_FILE);
   await writeFile(
     join(dir, HEADERS_FILE),
     generateHeadersFile({
       base: adapterBase(config),
-      unhashedPaths,
-      contentTypes: config.staticContentTypes,
+      immutableDirs: artifacts.immutableDirs,
+      // Scanned from the directory being deployed, which holds everything
+      // the platform will serve from it.
+      unhashedPaths: await findUnhashedStaticFiles(dir, artifacts.immutableDirs),
+      contentTypes: artifacts.output === 'static' ? artifacts.contentTypes : undefined,
       userRules: userRules ?? undefined,
     })
   );

package/src/adapters/canonicalize-module.ts

@@ -0,0 +1,29 @@
+// Compiles server/canonicalize.ts into a standalone ESM module
+// (_canonicalize.mjs) for the Nitro preview server, so preview answers a
+// request path exactly as the runtime's request boundary does — the same
+// rejections (encoded separators, null bytes, malformed encoding, escaping
+// the root) and the same single decode — instead of a hand-kept copy of
+// those rules drifting from them. Same mechanism as compress-module.ts:
+// type-stripped, not bundled, so the source must stay import-free.
+
+import { transformWithOxc } from 'vite';
+// Vite's ?raw import embeds the file as a string at build time (see
+// compress-module.ts).
+import canonicalizeSource from '../server/canonicalize.ts?raw';
+import { assertStandalone } from './compress-module.ts';
+
+/**
+ * Compile server/canonicalize.ts into a standalone ESM module exporting
+ * `canonicalize`.
+ *
+ * @internal Exported for testing.
+ */
+export async function generateCanonicalizeModule(): Promise<string> {
+  const result = await transformWithOxc(canonicalizeSource, 'canonicalize.ts', { lang: 'ts' });
+  assertStandalone(result.code, 'server/canonicalize.ts', '_canonicalize.mjs');
+  return (
+    '// Generated by @timber-js/app — compiled from server/canonicalize.ts.\n' +
+    '// Do not edit — this file is regenerated on each build.\n' +
+    result.code
+  );
+}