@timber-js/app 0.2.0-alpha.166 → 0.2.0-alpha.168

package/docs/learn/09-caching.mdx

@@ -36,7 +36,7 @@ export const getUser = cache(async (id: string) => {
 });
 
 // Caches across requests for 60 seconds
-export const getPopularProducts = timberCache(
+export const getPopularProducts = timberCache.data(
   async () => {
     return db.products.findPopular();
   },
@@ -44,7 +44,7 @@ export const getPopularProducts = timberCache(
 );
 ```
 
-## `timber.cache()` Options
+## `cache.data()` Options
 
 ```ts
 import { cache } from '@timber-js/app/cache';
@@ -53,7 +53,7 @@ declare const db: {
   users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> };
 };
 
-const getUser = cache(
+const getUser = cache.data(
   async (userId: string) => {
     return db.users.findUnique({ where: { id: userId } });
   },
@@ -74,7 +74,7 @@ Without an explicit `key`, the cache key is derived from the call site plus a de
 
 ### Content-Derived Cache Identities
 
-The call-site identity is content-based — derived from the source code of the `cache()` call, not its position in the file. This means:
+The call-site identity is content-based — derived from the source code of the `cache.data()` call, not its position in the file. This means:
 
 - **Unchanged code = cache survives deploys.** If you redeploy without changing a cached function, its entries remain valid on persistent handlers like Redis or KV.
 - **Changed code = automatic invalidation.** Editing the wrapped function or its options changes the cache identity, which invalidates old entries without manual cache busting.
@@ -86,7 +86,7 @@ Object key order doesn't matter — `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produc
 Arguments that can't be serialized faithfully — functions, symbols, or class instances whose data lives behind getters with no `toJSON()` — throw a `TypeError` instead of silently colliding. If you hit this, pass an explicit `key`:
 
 ```ts
-cache(fn, { ttl: 60, key: (session) => `events:${session.userId}` });
+cache.data(fn, { ttl: 60, key: (session) => `events:${session.userId}` });
 ```
 
 ## Invalidation
@@ -117,16 +117,132 @@ On serverless platforms (Cloudflare Workers, Lambda), the background refetch is
 
 When multiple concurrent requests miss the cache for the same key, only one executes the underlying function. The rest wait for the result. The result is written to the cache exactly once, by the execution that ran the function. This is built in — no opt-in needed.
 
+## Caching Components
+
+`cache.data` caches a function's return value. `cache.component` caches a component's **rendered output** — the RSC flight payload — so re-renders skip the entire component tree:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { cache } from '@timber-js/app/cache';
+import { getSegmentParams } from '@timber-js/app/server';
+
+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>;
+  },
+  { prerender: true }
+);
+
+export async function generateStaticSegmentParams() {
+  return allPosts.map((p) => ({ slug: p.slug }));
+}
+
+export default async function BlogPost() {
+  return <PostBody />;
+}
+```
+
+The same API gives you three tiers of freshness, controlled by two options:
+
+### Static (build-time only)
+
+Rendered at build for each set of params from `generateStaticSegmentParams`. Changes only on redeploy. Request context (`getCookieJar()`, `getHeaders()`) is a build error.
+
+```tsx
+const BlogBody = cache.component(Body, { prerender: true });
+```
+
+### Cached (runtime only)
+
+Rendered on first request, stored with a TTL. Invalidatable by tag. May read request context (with a warning — be careful not to leak per-user data into a shared cache).
+
+```tsx
+const Pricing = cache.component(PricingTable, {
+  ttl: 300,
+  tags: ['pricing'],
+  staleWhileRevalidate: true,
+});
+```
+
+### ISR (build-seeded, runtime-refreshable)
+
+Rendered at build, but refreshable via `revalidateTag` without a redeploy. Unenumerated params fill in on first request.
+
+```tsx
+const DocsPage = cache.component(DocsBody, {
+  prerender: true,
+  ttl: 3600,
+  tags: ['docs'],
+});
+```
+
+### Mixing Tiers on One Page
+
+A page can combine all three — a dynamic shell with cached islands:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { getCookieJar } from '@timber-js/app/server';
+
+export default async function BlogPost() {
+  const user = await getUser(getCookieJar());
+  return (
+    <>
+      <Nav user={user} />           {/* dynamic — personalized */}
+      <PostBody />                   {/* prerendered — from build artifact */}
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments />                 {/* dynamic — streams per-request */}
+      </Suspense>
+    </>
+  );
+}
+```
+
+### Route-Level Shorthand
+
+For fully static routes, export `prerender` instead of wrapping the component manually:
+
+```ts title="app/about/page.tsx"
+export const prerender = true;
+```
+
+This desugars to `cache.component(...)` around the page's default export. For dynamic routes (`[slug]`), pair it with `generateStaticSegmentParams` so the build knows which params to prerender:
+
+```ts title="app/docs/[slug]/page.tsx"
+export const prerender = { ttl: 3600, tags: ['docs'] };
+
+export async function generateStaticSegmentParams() {
+  return allDocs.map((d) => ({ slug: d.slug }));
+}
+```
+
+Layout `prerender` cascades to descendant pages unless a closer layout or page overrides it.
+
+### Slots: Dynamic Children Through a Cached Shell
+
+When the expensive part is a wrapper (nav, sidebar, layout chrome) but its children are dynamic, use `slots` to cache the shell with holes for live content:
+
+```tsx
+const Shell = cache.component(ExpensiveWrapper, {
+  ttl: 3600,
+  tags: ['marketing'],
+  slots: ['children'],
+});
+
+// The shell serves from cache; children render live per request.
+<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.
+
 ## Cache Handlers
 
-The default handler is in-memory. Configure a different backend in `timber.config.ts`:
+The default handler is in-memory. Configure a different backend in `timber.cache.ts`:
 
-```ts title="timber.config.ts"
+```ts title="timber.cache.ts"
 import { MemoryCacheHandler } from '@timber-js/app/cache';
 
-export default {
-  cacheHandler: new MemoryCacheHandler(),
-};
+export default new MemoryCacheHandler();
 ```
 
 Implement the `CacheHandler` interface for Redis, Cloudflare KV, or any other backend. See the [Cache API Reference](/docs/api-cache).

package/docs/learn/12-client-navigation.mdx

@@ -108,7 +108,13 @@ export function NavItem({ href, children }: { href: string; children: React.Reac
 
 ## Segment Cache
 
-The client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
+Opt-in via `clientSegmentCache: true` in `timber.config.ts`. When enabled, the client maintains a mirror of the server's segment tree. On navigation, only changed segments are re-fetched:
+
+```ts title="timber.config.ts"
+export default {
+  clientSegmentCache: true,
+};
+```
 
 ```
 /dashboard/settings → /dashboard/team
@@ -121,6 +127,8 @@ The client maintains a mirror of the server's segment tree. On navigation, only
 
 Sync layouts stay cached while mounted. Async layouts always re-render. Pages always re-render. Client component state in shared layouts is preserved — counters, form inputs, scroll positions survive navigation.
 
+When disabled (the default), every client navigation gets a full RSC payload from the server. This is simpler and avoids edge cases with stale cached layouts, at the cost of slightly larger payloads on navigation.
+
 Back/forward navigation replays cached RSC payloads instantly — no server roundtrip.
 
 ## Scroll Restoration

package/docs/learn/13-configuration.mdx

@@ -81,16 +81,15 @@ export default {
 
 ## Cache Handler
 
-```ts title="timber.config.ts"
+Cache handler configuration lives in a separate `timber.cache.ts` file (not `timber.config.ts`). This keeps runtime cache instances separate from build-time config, preventing build dependencies from leaking into the server bundle.
+
+```ts title="timber.cache.ts"
 import { MemoryCacheHandler } from '@timber-js/app/cache';
 
-export default {
-  output: 'server',
-  cacheHandler: new MemoryCacheHandler(),
-};
+export default new MemoryCacheHandler();
 ```
 
-The default is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
+The default export is the `CacheHandler` instance. Export `cdnPurge` as a named export for CDN purge handlers. The default handler is in-memory. See [Caching](/docs/caching) for Redis, KV, and custom handlers.
 
 ## `clientJavascript`
 
@@ -129,8 +128,6 @@ Server actions still work — HTML forms submit natively via POST without JavaSc
 | `buildDir`          | `string`                    | `'.timber/dist'`             | Build output directory                   |
 | `clientJavascript`  | `boolean \| object`         | `true`                       | Control client-side JS                   |
 | `adapter`           | `TimberPlatformAdapter`     | —                            | Deployment adapter                       |
-| `cacheHandler`      | `CacheHandler`              | `MemoryCacheHandler`         | Cache backend                            |
-| `cdnPurge`          | `CdnPurgeHandler`           | —                            | CDN purge on revalidation                |
 | `serverTiming`      | `'detailed' \| 'total' \| false` | `'detailed'` / `'total'` | Server-Timing header                     |
 | `allowedOrigins`    | `string[]`                  | —                            | CORS / CSRF allowed origins              |
 | `csrf`              | `boolean`                   | `true`                       | CSRF protection                          |
@@ -148,6 +145,7 @@ Server actions still work — HTML forms submit natively via POST without JavaSc
 | `actionEncryption`  | `object`                    | —                            | Server action bound args encryption      |
 | `reactCompiler`     | `boolean \| object`         | `false`                      | React Compiler auto-memoization          |
 | `sitemap`           | `object`                    | —                            | Auto-generated sitemap.xml               |
+| `clientSegmentCache`| `boolean`                   | `false`                      | Opt-in client segment cache for partial nav |
 | `topLoader`         | `object`                    | enabled                      | Navigation progress bar                  |
 
 For the full type definition, see the [Config API Reference](/docs/api-config).

package/docs/learn/14-deploying.mdx

@@ -65,15 +65,19 @@ For caching, use `CloudflareKVCacheHandler`:
 
 ```ts title="timber.config.ts"
 import { cloudflare } from '@timber-js/app/adapters/cloudflare';
-import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
 
 export default {
   output: 'server',
   adapter: cloudflare(),
-  cacheHandler: new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' }),
 };
 ```
 
+```ts title="timber.cache.ts"
+import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+
+export default new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' });
+```
+
 **Constraints:** no file system, 10ms/30s CPU time limits, 10MB/25MB bundle size.
 
 ## Node.js & Docker
@@ -226,30 +230,26 @@ When using the Cloudflare adapter, CDN purge is **automatic** — no configurati
 
 For non-Workers Cloudflare zones (Enterprise), or other CDNs, configure a purge handler manually:
 
-```ts title="timber.config.ts"
+```ts title="timber.cache.ts"
 import { CloudflarePurge } from '@timber-js/app/cdn/cloudflare';
 
-export default {
-  // Only needed for non-Workers Cloudflare zones (Enterprise)
-  cdnPurge: new CloudflarePurge({
-    zoneId: process.env.CF_ZONE_ID!,
-    apiToken: process.env.CF_API_TOKEN!,
-  }),
-};
+// Only needed for non-Workers Cloudflare zones (Enterprise)
+export const cdnPurge = new CloudflarePurge({
+  zoneId: process.env.CF_ZONE_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+});
 ```
 
 Fastly:
 
-```ts title="timber.config.ts"
+```ts title="timber.cache.ts"
 import { FastlyPurge } from '@timber-js/app/cdn/fastly';
 
-export default {
-  cdnPurge: new FastlyPurge({
-    serviceId: process.env.FASTLY_SERVICE_ID!,
-    apiToken: process.env.FASTLY_API_TOKEN!,
-    softPurge: true,
-  }),
-};
+export const cdnPurge = new FastlyPurge({
+  serviceId: process.env.FASTLY_SERVICE_ID!,
+  apiToken: process.env.FASTLY_API_TOKEN!,
+  softPurge: true,
+});
 ```
 
 When `revalidateTag('products')` fires, it clears the application cache **and** calls the CDN purge handler. CDN purge is best-effort — failures are logged but don't break cache invalidation.

package/docs/more/03-coming-from-nextjs.mdx

@@ -80,14 +80,14 @@ export const searchParams = defineSearchParams({
 
 **Next.js:** Implicit fetch caching, `unstable_cache`, ISR with `revalidate`.
 
-**timber:** No implicit caching. No ISR. Explicit `timber.cache()` with TTL and tags:
+**timber:** No implicit caching. No ISR. Explicit `cache.data()` with TTL and tags:
 
 ```ts
 import { cache } from '@timber-js/app/cache';
 
 declare const db: { products: { findPopular(): Promise<{ id: string; name: string }[]> } };
 
-const getProducts = cache(
+const getProducts = cache.data(
   async () => db.products.findPopular(),
   { ttl: 300, tags: ['products'] }
 );

package/docs/more/04-metadata-and-fonts.mdx

@@ -87,7 +87,7 @@ Special files in your route tree generate metadata endpoints:
 
 When `opengraph-image.tsx` exists in a segment, timber automatically emits both `<meta property="og:image">` and `<meta name="twitter:image">` in `<head>` — no need to declare them in your `metadata` export. The auto-linked URL includes a cache-busting hash so social platforms pick up changes on redeploy.
 
-If you declare `openGraph.images` in your metadata, the auto-linked tags are suppressed (user-declared metadata wins).
+If you declare `openGraph.images` in your metadata, both auto-linked tags are suppressed. If you declare only `twitter.images`, the auto-linked `twitter:image` is suppressed but `og:image` is still emitted. User-declared metadata always wins.
 
 `favicon.tsx` lets you generate favicons dynamically (e.g. tenant branding). The URL stays `/favicon.ico` for browser compatibility.
 

package/docs/more/50-ai-agent-instructions.mdx

@@ -53,8 +53,8 @@ These are the things you will get wrong if you assume Next.js behavior.
 | Concept | Next.js | timber.js |
 | --- | --- | --- |
 | Default component type | Client components need `'use client'` | **All components are server components** by default. Only add `'use client'` when you need browser APIs or hooks. |
-| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache()` from `@timber-js/app/cache` explicitly. |
-| ISR | `revalidate` option | **Does not exist.** Use `cache()` with TTL and tags. |
+| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache.data()` from `@timber-js/app/cache` explicitly. |
+| ISR | `revalidate` option | **Does not exist.** Use `cache.data()` with TTL and tags. |
 | `loading.tsx` | Convention for auto-Suspense | **Does not exist.** Use `<Suspense>` explicitly. |
 | Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
 | `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
@@ -104,11 +104,11 @@ content-collections.ts  # Collection definitions (optional)
 
 2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
 
-3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache()` from `@timber-js/app/cache` when you want caching.
+3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache.data()` from `@timber-js/app/cache` when you want caching.
 
 4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
 
-5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache()` with `{ ttl: seconds, tags: ['tag'] }`.
+5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache.data()` with `{ ttl: seconds, tags: ['tag'] }`.
 
 6. **Calling `notFound()`** — use `deny(404)` from `@timber-js/app/server` instead. It sends a real HTTP 404 status code.
 
@@ -123,7 +123,7 @@ content-collections.ts  # Collection definitions (optional)
 ```tsx
 import { cache } from '@timber-js/app/cache';
 
-const getProducts = cache(
+const getProducts = cache.data(
   async () => db.products.findMany(),
   { ttl: 300, tags: ['products'] }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.166",
+  "version": "0.2.0-alpha.168",
   "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",
@@ -158,12 +158,13 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/context-async-hooks": "^2.8.0",
-    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
     "cookie": "^1.1.1",
+    "jsonc-parser": "^3.3.1",
     "magic-string": "^0.30.21",
     "nitro": "3.0.260610-beta",
-    "srvx": "^0.11.17"
+    "srvx": "^0.11.22"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0 || ^0.15.0",
@@ -175,7 +176,7 @@
     "nuqs": "^2.0.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
-    "vite": "^8.1.0",
+    "vite": "8.1.0",
     "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },

package/src/adapters/cloudflare-kv-cache.ts

@@ -1,5 +1,6 @@
 import type { CacheHandler } from '../cache/index';
 import { getCloudflareBindings } from './cloudflare';
+import { warnLossyJsonValue } from '../cache/json-lossy-check.js';
 
 /**
  * Cloudflare Workers KV interface — the subset of KVNamespace we depend on.
@@ -117,6 +118,7 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     value: unknown,
     opts: { ttl: number; tags: string[]; generation?: number }
   ): Promise<void> {
+    warnLossyJsonValue(value, key);
     const kv = this.getKV();
     const entry: KVCacheEntry = {
       value,
@@ -127,12 +129,16 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     // KV expirationTtl minimum is 60s. Use 2× TTL (min 60s) so stale entries
     // survive for staleWhileRevalidate background refetches.
     const kvTtl = Math.max(opts.ttl * 2, 60);
-    await kv.put(this.dataKey(key), JSON.stringify(entry), { expirationTtl: kvTtl });
 
-    // Update tag indexes — prune physically expired members on each write so
-    // indexes don't grow unboundedly. Uses the physical KV expiry (2× TTL) as
-    // the deadline, not the logical expiresAt, so stale entries in the SWR
-    // window remain in the index for invalidate({tag}) to find.
+    // Serialize upfront so BigInt/non-serializable errors throw before any
+    // writes — prevents tag indexes pointing at stale data from a prior set().
+    const payload = JSON.stringify(entry);
+
+    // Tag indexes are written BEFORE the data key so that a partial network
+    // failure on the data write never leaves an entry invisible to
+    // invalidate({tag}). A dangling tag-index reference to a non-existent
+    // data key is harmless — invalidate() re-checks stored tags and cleans
+    // up on the next pass.
     const now = Date.now();
     const kvExpiresAt = now + kvTtl * 1000;
     await Promise.all(
@@ -145,6 +151,8 @@ export class CloudflareKVCacheHandler implements CacheHandler {
         });
       })
     );
+
+    await kv.put(this.dataKey(key), payload, { expirationTtl: kvTtl });
   }
 
   async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
@@ -175,7 +183,20 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     if (opts.tag) {
       const entries = parseTagIndex(await kv.get(this.tagKey(opts.tag), { type: 'json' }));
       if (entries.length > 0) {
-        await Promise.all(entries.map((e) => kv.delete(this.dataKey(e.key))));
+        // Re-check each member's stored tags before deleting — the tag index
+        // can contain stale references from partial writes or entries whose
+        // tags changed since they were indexed. Mirrors Redis handler behavior.
+        await Promise.all(
+          entries.map(async (e) => {
+            const raw = (await kv.get(this.dataKey(e.key), {
+              type: 'json',
+            })) as KVCacheEntry | null;
+            if (!raw) return;
+            if (raw.tags?.includes(opts.tag!)) {
+              await kv.delete(this.dataKey(e.key));
+            }
+          })
+        );
       }
       await kv.delete(this.tagKey(opts.tag));
     }

package/src/adapters/cloudflare.ts

@@ -3,9 +3,10 @@
 // Primary deployment target. Generates a Workers-compatible entry point
 // and wrangler.jsonc configuration. See design/11-platform.md §"Cloudflare Workers".
 
-import { writeFile, readFile, cp, rm, readdir } from 'node:fs/promises';
+import { writeFile, readFile, cp, rm, readdir, access } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
+import { parse as parseJsonc } from 'jsonc-parser';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { runSharedBuildSteps } from './build-output-helper.js';
@@ -158,6 +159,12 @@ export interface CloudflareBindings {
 
 /** Options for the Cloudflare Workers adapter. */
 export interface CloudflareAdapterOptions {
+  /**
+   * Worker name used in the generated wrangler.jsonc.
+   * @default 'timber-app'
+   */
+  name?: string;
+
   /**
    * Cloudflare compatibility date.
    * @default Current date in YYYY-MM-DD format at build time.
@@ -291,8 +298,10 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
       const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit, hasWorkerHandlers);
       await writeFile(join(outDir, '_worker.js'), workerEntry);
 
-      // Generate wrangler.jsonc
-      const wranglerConfig = generateWranglerConfig(config, options);
+      // Generate wrangler.jsonc — merges user's wrangler config from disk if present
+      const root = config.root ?? process.cwd();
+      const userConfig = await readUserWranglerConfig(root);
+      const wranglerConfig = generateWranglerConfig(config, options, userConfig);
       await writeFile(join(outDir, 'wrangler.jsonc'), JSON.stringify(wranglerConfig, null, 2));
     },
 
@@ -682,22 +691,40 @@ function isPlainObject(val: unknown): val is Record<string, unknown> {
   return val !== null && typeof val === 'object' && !Array.isArray(val);
 }
 
+const WRANGLER_CONFIG_FILES = ['wrangler.jsonc', 'wrangler.json'] as const;
+
+/**
+ * Read the user's wrangler config from the project root, if one exists.
+ * Checks wrangler.jsonc first, then wrangler.json.
+ * @internal Exported for testing.
+ */
+export async function readUserWranglerConfig(
+  root: string
+): Promise<Record<string, unknown> | null> {
+  for (const filename of WRANGLER_CONFIG_FILES) {
+    const filepath = join(root, filename);
+    try {
+      await access(filepath);
+    } catch {
+      continue;
+    }
+    const content = await readFile(filepath, 'utf-8');
+    return parseJsonc(content) as Record<string, unknown>;
+  }
+  return null;
+}
+
 /** @internal Exported for testing. */
 export function generateWranglerConfig(
   config: TimberConfig,
-  options: CloudflareAdapterOptions
+  options: CloudflareAdapterOptions,
+  userConfig?: Record<string, unknown> | null
 ): Record<string, unknown> {
-  const compatDate = options.compatibilityDate ?? new Date().toISOString().slice(0, 10);
-
-  const flags = options.compatibilityFlags ?? ['nodejs_compat'];
-
   const base: Record<string, unknown> = {
     name: 'timber-app',
     main: '_worker.js',
-    compatibility_date: compatDate,
-    compatibility_flags: flags,
-    // The build output is already fully bundled by Vite — skip wrangler's
-    // esbuild pass to avoid issues with top-level await and module format.
+    compatibility_date: new Date().toISOString().slice(0, 10),
+    compatibility_flags: ['nodejs_compat'],
     no_bundle: true,
     find_additional_modules: true,
     rules: [{ type: 'ESModule', globs: ['**/*.js'] }],
@@ -705,29 +732,40 @@ export function generateWranglerConfig(
       directory: './static',
       binding: 'ASSETS',
     },
-    // Native trace destination — required for timber's pipeline spans
-    // (emitted via tracing.enterSpan in the generated _worker.js) to appear
-    // in the Cloudflare Observability dashboard. Gates traces only; does
-    // not enable Workers Logs. Override via the `wrangler` escape hatch:
-    // wrangler: { observability: { traces: { enabled: false } } }.
     observability: {
       traces: { enabled: true },
     },
   };
 
-  // Layer 1: merge bindings-generated sections into base
+  // Layer 1: user's wrangler.jsonc / wrangler.json from disk
+  let merged: Record<string, unknown> = userConfig ? shallowDeepMerge(base, userConfig) : base;
+
+  // Layer 2: explicit adapter options override disk config
+  const explicit: Record<string, unknown> = {};
+  if (options.name != null) explicit.name = options.name;
+  if (options.compatibilityDate != null) explicit.compatibility_date = options.compatibilityDate;
+  if (options.compatibilityFlags != null) explicit.compatibility_flags = options.compatibilityFlags;
+  if (Object.keys(explicit).length > 0) {
+    merged = { ...merged, ...explicit };
+  }
+
+  // Layer 3: declarative bindings
   const bindingsConfig = generateBindingsConfig(options.bindings);
-  const merged = { ...base, ...bindingsConfig };
+  merged = shallowDeepMerge(merged, bindingsConfig as Record<string, unknown>);
 
-  // Layer 2: wrangler escape hatch with deep merge for nested plain objects.
-  // A shallow spread would replace entire sections like durable_objects and
-  // queues — e.g. adding migrations via wrangler would drop the generated
-  // durable_objects.bindings. Deep merge preserves generated keys while
-  // letting wrangler override on actual key-level conflicts.
+  // Layer 4: wrangler escape hatch — highest priority, deep merge.
   if (options.wrangler) {
-    return shallowDeepMerge(merged, options.wrangler);
+    merged = shallowDeepMerge(merged, options.wrangler);
   }
 
+  // Generated config targets a single environment — env blocks can override
+  // main/assets per-environment and break the build output.
+  delete merged.env;
+
+  // These fields are required for the build output to work correctly.
+  merged.main = '_worker.js';
+  merged.find_additional_modules = true;
+
   return merged;
 }
 

package/src/adapters/types.ts

@@ -9,6 +9,8 @@
  * A subset of the resolved timber.config.ts relevant to adapters.
  */
 export interface TimberConfig {
+  /** Absolute path to the project root (Vite root). */
+  root?: string;
   output: 'server' | 'static';
   clientJavascriptDisabled?: boolean;
   /**