@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/src/plugins/dev-server.ts

@@ -15,10 +15,22 @@
 import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
-import { setViteServer } from '#/server/dev-warnings.js';
-import { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
-import { compressResponse } from '#/server/compress.js';
+import type { PluginContext } from '../plugin-context.js';
+import { setViteServer } from '../server/dev-warnings.js';
+import {
+  sendErrorToOverlay,
+  classifyErrorPhase,
+  fixErrorStacktrace,
+  parseFirstAppFrame,
+  type ErrorPhase,
+} from './dev-error-overlay.js';
+import {
+  generateDevErrorPage,
+  extractHmrOptions,
+  type DevErrorHmrOptions,
+} from './dev-error-page.js';
+import { addVirtualModuleContext } from '../config-validation.js';
+import { compressResponse } from '../server/compress.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -96,6 +108,21 @@ export function timberDevServer(ctx: PluginContext): Plugin {
       // Pre-hook — registers middleware before Vite's internals
       server.middlewares.use(createTimberMiddleware(server, ctx.root));
 
+      // Wrap server.listen() to close the holding server immediately
+      // before Vite binds the port — no gap where nothing is listening.
+      // The holding server was started in rootSync's config() hook to
+      // serve a loading page during initialization.
+      // See design/21-dev-server.md §"Startup Holding Server", TIM-665.
+      if (ctx.holdingServer) {
+        const originalListen = server.listen.bind(server);
+        const holdingRef = ctx.holdingServer;
+        ctx.holdingServer = null;
+        server.listen = async (port?: number, isRestart?: boolean) => {
+          await holdingRef.close().catch(() => {});
+          return originalListen(port, isRestart);
+        };
+      }
+
       // Log startup timing summary. configureServer runs on all plugins
       // before the server listens, so this captures the full cold start.
       ctx.timer.end('dev-server-setup');
@@ -122,6 +149,10 @@ export function timberDevServer(ctx: PluginContext): Plugin {
  * calls next() to let Vite handle them.
  */
 function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
+  // Extract HMR connection options once so the error page can construct
+  // a correct WebSocket URL (TIM-789).
+  const hmrOptions = extractHmrOptions(server.config);
+
   return async (req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void> => {
     const url = req.url;
     if (!url) {
@@ -161,12 +192,38 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
 
       // Wire pipeline errors into the browser error overlay.
       // setDevPipelineErrorHandler is only defined in dev (rsc-entry.ts exports it).
+      // The handler receives optional RSC debug component data (component names,
+      // environments, stack frames) from the Flight debug channel for render errors.
       const setHandler = rscModule.setDevPipelineErrorHandler as
-        | ((fn: (error: Error, phase: string) => void) => void)
+        | ((
+            fn: (
+              error: Error,
+              phase: string,
+              debugComponents?: Array<{ name: string; env: string | null; stack: unknown[] | null }>
+            ) => void
+          ) => void)
         | undefined;
       if (typeof setHandler === 'function') {
-        setHandler((error) => {
-          sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
+        setHandler((error, _phase, debugComponents) => {
+          sendErrorToOverlay(
+            server,
+            error,
+            classifyErrorPhase(error, projectRoot),
+            projectRoot,
+            debugComponents
+          );
+        });
+      }
+
+      // Wire source-map handler so error pages show original positions.
+      // fixErrorStacktrace rewrites the error's stack trace in-place using
+      // the Vite dev server's module graph. See TIM-811.
+      const setSourceMap = rscModule.setDevSourceMapHandler as
+        | ((fn: (error: Error) => void) => void)
+        | undefined;
+      if (typeof setSourceMap === 'function') {
+        setSourceMap((error: Error) => {
+          fixErrorStacktrace(server, error);
         });
       }
     } catch (error) {
@@ -174,9 +231,11 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Vite may already show its own overlay for these, but we still
       // log to stderr with frame dimming for the terminal.
       if (error instanceof Error) {
+        // Add context for virtual:timber-* module errors
+        addTimberContext(error);
         sendErrorToOverlay(server, error, 'module-transform', projectRoot);
       }
-      respond500(res, error);
+      respond500(res, error, 'module-transform', projectRoot, hmrOptions);
       return;
     }
 
@@ -191,8 +250,20 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Convert Node IncomingMessage → Web Request
       const webRequest = toWebRequest(req);
 
-      // Run the full pipeline
-      const webResponse = await handler(webRequest);
+      // Check for a platform-specific request wrapper (e.g., Cloudflare
+      // dev bindings). The cloudflareDevBindings() plugin stores a wrapper
+      // function on the server instance using a well-known Symbol. The
+      // wrapper runs the handler inside an ALS context so platform APIs
+      // like getCloudflareBindings() work during dev.
+      // See design/35-cloudflare-primitives.md §"Dev Experience".
+      const wrapper = (server as any)[Symbol.for('timber:dev-request-wrapper')] as
+        | (<T>(fn: () => T) => T)
+        | undefined;
+
+      // Run the full pipeline (wrapped if a platform dev plugin is active)
+      const webResponse = wrapper
+        ? await wrapper(() => handler(webRequest))
+        : await handler(webRequest);
 
       // Compress the response if the client supports it.
       // In dev mode, compression is always enabled for parity with production.
@@ -207,24 +278,60 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       if (error instanceof Error) {
         const phase = classifyErrorPhase(error, projectRoot);
         sendErrorToOverlay(server, error, phase, projectRoot);
+        respond500(res, error, phase, projectRoot, hmrOptions);
       } else {
         process.stderr.write(`\x1b[31m[timber] Dev server error:\x1b[0m ${String(error)}\n`);
+        respond500(res, error, 'render', projectRoot, hmrOptions);
       }
-      respond500(res, error);
     }
   };
 }
 
 /**
  * Send a 500 response without crashing the dev server.
+ *
+ * In dev mode, renders a styled HTML error page with source context,
+ * classified stack trace, and auto-reload on HMR. Falls back to
+ * text/plain if the HTML generator fails (must never crash).
  */
-function respond500(res: ServerResponse, error: unknown): void {
-  if (!res.headersSent) {
-    res.statusCode = 500;
-    res.setHeader('content-type', 'text/plain');
-    res.end(
-      `[timber] Internal server error\n\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}`
-    );
+function respond500(
+  res: ServerResponse,
+  error: unknown,
+  phase: ErrorPhase,
+  projectRoot: string,
+  hmrOptions?: DevErrorHmrOptions
+): void {
+  if (res.headersSent) return;
+
+  // Try to render the rich HTML error page
+  if (error instanceof Error) {
+    try {
+      const html = generateDevErrorPage(error, phase, projectRoot, hmrOptions);
+      res.statusCode = 500;
+      res.setHeader('content-type', 'text/html; charset=utf-8');
+      res.end(html);
+      return;
+    } catch {
+      // Fall through to text/plain if the HTML generator fails
+    }
+  }
+
+  // Fallback: plain text (same as before)
+  res.statusCode = 500;
+  res.setHeader('content-type', 'text/plain');
+  res.end(
+    `[timber] Internal server error\n\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}`
+  );
+}
+
+/**
+ * Add timber-specific context to an error's message if it references
+ * internal virtual modules (virtual:timber-*). Mutates the error in place.
+ */
+function addTimberContext(error: Error): void {
+  const enriched = addVirtualModuleContext(error.message);
+  if (enriched !== error.message) {
+    error.message = enriched;
   }
 }
 
@@ -317,6 +424,17 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
   nodeRes.flushHeaders();
 
   const reader = webResponse.body.getReader();
+
+  // Cancel the reader when the client disconnects. This causes any pending
+  // reader.read() to reject, breaking the pump loop. Critical for SSE and
+  // other infinite streams — without this, disconnected clients leak readers.
+  let clientDisconnected = false;
+  const onClose = () => {
+    clientDisconnected = true;
+    reader.cancel('Client disconnected').catch(() => {});
+  };
+  nodeRes.on('close', onClose);
+
   try {
     while (true) {
       const { done, value } = await reader.read();
@@ -325,9 +443,18 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
       // don't need back-pressure here — just keep pushing chunks.
       nodeRes.write(value);
     }
+  } catch (err) {
+    // reader.cancel() from the close handler causes read() to reject.
+    // This is expected on client disconnect — not an error.
+    if (!clientDisconnected) {
+      throw err;
+    }
   } finally {
+    nodeRes.off('close', onClose);
     reader.releaseLock();
-    nodeRes.end();
+    if (!nodeRes.writableEnded) {
+      nodeRes.end();
+    }
   }
 }
 

package/src/plugins/dev-terminal-error.ts

@@ -0,0 +1,217 @@
+/**
+ * Terminal error formatting — boxed, color-coded error output for dev mode.
+ *
+ * Produces a visually scannable error block with:
+ * - Unicode box-drawing border around the error
+ * - Phase badge and error message
+ * - First app frame highlighted as the primary action item
+ * - OSC 8 clickable file:line links (VSCode terminal, iTerm2, etc.)
+ * - Internal/framework frames collapsed with a count
+ * - Component stack (for React render errors)
+ *
+ * Dev-only: this module is only imported by dev-error-overlay.ts.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import { pathToFileURL } from 'node:url';
+import {
+  classifyFrame,
+  extractComponentStack,
+  parseFirstAppFrame,
+  PHASE_LABELS,
+  type ErrorPhase,
+  type FrameType,
+} from './dev-error-overlay.js';
+
+// ─── ANSI Codes ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const UNDERLINE = '\x1b[4m';
+
+// ─── OSC 8 Hyperlinks ──────────────────────────────────────────────────────
+
+/**
+ * Wrap text in an OSC 8 hyperlink escape sequence.
+ *
+ * Terminals that support OSC 8 (VSCode, iTerm2, Windows Terminal, etc.)
+ * render this as a clickable link. Others ignore the escape sequences
+ * and show the text normally.
+ *
+ * Format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+ */
+function hyperlink(text: string, url: string): string {
+  return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+
+/**
+ * Format a file:line:col reference as a clickable terminal link.
+ *
+ * Uses file:// URLs so terminals open the file in the configured editor.
+ * The link text is styled with cyan + underline for visibility.
+ */
+function fileLink(filePath: string, line?: number, col?: number): string {
+  const display = line ? `${filePath}:${line}${col ? `:${col}` : ''}` : filePath;
+  // Use pathToFileURL for proper encoding of spaces, #, ?, and Windows
+  // drive letters (TIM-792). Append :line:col after the URL.
+  const base = pathToFileURL(filePath).href;
+  const url = line ? `${base}:${line}${col ? `:${col}` : ''}` : base;
+  return `${CYAN}${UNDERLINE}${hyperlink(display, url)}${RESET}`;
+}
+
+// ─── Box Drawing ────────────────────────────────────────────────────────────
+
+const BOX = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+};
+
+/**
+ * Wrap lines of text in a Unicode box with a colored left border.
+ *
+ * @param lines - Content lines (no ANSI length calculation — keeps it simple)
+ * @param width - Box width (characters). Lines longer than this are not truncated.
+ */
+function box(lines: string[], borderColor: string, width = 80): string {
+  const bar = BOX.horizontal.repeat(width - 2);
+  const output: string[] = [];
+
+  output.push(`${borderColor}${BOX.topLeft}${bar}${BOX.topRight}${RESET}`);
+  for (const line of lines) {
+    output.push(`${borderColor}${BOX.vertical}${RESET} ${line}`);
+  }
+  output.push(`${borderColor}${BOX.bottomLeft}${bar}${BOX.bottomRight}${RESET}`);
+
+  return output.join('\n');
+}
+
+// ─── Frame Extraction ───────────────────────────────────────────────────────
+
+interface ClassifiedFrame {
+  raw: string;
+  type: FrameType;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+/** Parse file/line/col from a stack frame line. */
+function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
+  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
+  if (parenMatch) {
+    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
+  }
+  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
+  if (bareMatch) {
+    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
+  }
+  return {};
+}
+
+function classifyFrames(stack: string, projectRoot: string): ClassifiedFrame[] {
+  return stack
+    .split('\n')
+    .slice(1)
+    .filter((l) => l.trim().startsWith('at '))
+    .map((raw) => {
+      const type = classifyFrame(raw, projectRoot);
+      const { file, line, col } = parseFrame(raw);
+      return { raw, type, file, line, col };
+    });
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Format an error for terminal output with a boxed layout.
+ *
+ * The output is designed to be scannable at a glance:
+ * 1. Red box with phase badge and error message
+ * 2. First app frame as a clickable link (the primary action item)
+ * 3. App frames listed normally
+ * 4. Internal/framework frames collapsed with count
+ * 5. Component stack (if present)
+ */
+export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
+  const sections: string[] = [];
+  const componentStack = extractComponentStack(error);
+  const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
+  const frames = error.stack ? classifyFrames(error.stack, projectRoot) : [];
+  const appFrames = frames.filter((f) => f.type === 'app');
+  const internalCount = frames.filter((f) => f.type !== 'app').length;
+
+  // ── Box: Phase + Message ──────────────────────────────────────────
+  const boxLines: string[] = [];
+  boxLines.push(`${RED}${BOLD}${PHASE_LABELS[phase]} Error${RESET}`);
+  boxLines.push('');
+
+  // Error message — may be multi-line
+  for (const msgLine of error.message.split('\n')) {
+    boxLines.push(`${RED}${msgLine}${RESET}`);
+  }
+
+  // Primary file location (clickable)
+  if (loc) {
+    boxLines.push('');
+    const relPath = loc.file.startsWith(projectRoot)
+      ? loc.file.slice(projectRoot.length + 1)
+      : loc.file;
+    boxLines.push(
+      `${BOLD}→${RESET} ${fileLink(loc.file, loc.line, loc.column)} ${DIM}(${relPath})${RESET}`
+    );
+  }
+
+  sections.push(box(boxLines, RED));
+
+  // ── Component Stack ───────────────────────────────────────────────
+  if (componentStack) {
+    sections.push('');
+    sections.push(`  ${BOLD}Component Stack:${RESET}`);
+    for (const csLine of componentStack.trim().split('\n')) {
+      sections.push(`  ${DIM}${csLine.trim()}${RESET}`);
+    }
+  }
+
+  // ── App Frames ────────────────────────────────────────────────────
+  if (appFrames.length > 0) {
+    sections.push('');
+    sections.push(`  ${BOLD}Application Frames:${RESET}`);
+    for (let i = 0; i < appFrames.length; i++) {
+      const f = appFrames[i]!;
+      if (f.file && f.line) {
+        const prefix = i === 0 ? `${BOLD}▸${RESET}` : ' ';
+        sections.push(
+          `  ${prefix} ${fileLink(f.file, f.line, f.col)} ${DIM}${extractFnName(f.raw)}${RESET}`
+        );
+      } else {
+        sections.push(`  ${f.raw}`);
+      }
+    }
+  }
+
+  // ── Internal Frames (collapsed) ───────────────────────────────────
+  if (internalCount > 0) {
+    sections.push(
+      `  ${DIM}… ${internalCount} internal frame${internalCount !== 1 ? 's' : ''} hidden${RESET}`
+    );
+  }
+
+  sections.push('');
+  return sections.join('\n');
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Extract the function name from a stack frame line like "    at fnName (/path:1:2)". */
+function extractFnName(frameLine: string): string {
+  const match = /at\s+(\S+)\s+\(/.exec(frameLine.trim());
+  return match ? match[1]! : '';
+}

package/src/plugins/entries.ts

@@ -15,7 +15,7 @@ import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -34,6 +34,7 @@ const VIRTUAL_IDS = {
   browserEntry: 'virtual:timber-browser-entry',
   config: 'virtual:timber-config',
   instrumentation: 'virtual:timber-instrumentation',
+  cacheHandler: 'virtual:timber-cache-handler',
 } as const;
 
 /**
@@ -48,7 +49,7 @@ const VIRTUAL_IDS = {
 const ENTRY_FILE_MAP: Record<string, string> = {
   [VIRTUAL_IDS.rscEntry]: resolve(SRC_DIR, 'server', 'rsc-entry', 'index.ts'),
   [VIRTUAL_IDS.ssrEntry]: resolve(SRC_DIR, 'server', 'ssr-entry.ts'),
-  [VIRTUAL_IDS.browserEntry]: resolve(SRC_DIR, 'client', 'browser-entry.ts'),
+  [VIRTUAL_IDS.browserEntry]: resolve(SRC_DIR, 'client', 'browser-entry', 'index.ts'),
 };
 
 /** The \0-prefixed resolved ID for virtual:timber-config */
@@ -57,6 +58,9 @@ const RESOLVED_CONFIG_ID = `\0${VIRTUAL_IDS.config}`;
 /** The \0-prefixed resolved ID for virtual:timber-instrumentation */
 const RESOLVED_INSTRUMENTATION_ID = `\0${VIRTUAL_IDS.instrumentation}`;
 
+/** The \0-prefixed resolved ID for virtual:timber-cache-handler */
+const RESOLVED_CACHE_HANDLER_ID = `\0${VIRTUAL_IDS.cacheHandler}`;
+
 /**
  * Strip the \0 prefix from a module ID.
  *
@@ -94,12 +98,39 @@ function stripRootPrefix(id: string, root: string): string {
  *
  * Serializes output mode and feature flags for runtime consumption.
  */
-function generateConfigModule(ctx: PluginContext): string {
-  // Resolve cookie secrets: `secret` shorthand expands to `secrets: [secret]`
-  const cookieSecrets =
-    ctx.config.cookies?.secrets ??
-    (ctx.config.cookies?.secret ? [ctx.config.cookies.secret] : undefined);
+/**
+ * Extract the JSON-serializable subset of `forms` config.
+ *
+ * Drops function-valued `stripSensitiveFields` with a build-time warning —
+ * functions cannot cross the JSON boundary to the runtime, so users must
+ * configure function predicates per-action via `createActionClient` instead.
+ */
+function serializeFormsConfig(
+  forms: { stripSensitiveFields?: unknown } | undefined
+): { stripSensitiveFields?: boolean | readonly string[] } | undefined {
+  if (!forms) return undefined;
+  const opt = forms.stripSensitiveFields;
+  if (opt === undefined) return {};
+  if (typeof opt === 'boolean') return { stripSensitiveFields: opt };
+  if (Array.isArray(opt)) {
+    // Coerce to a string array and drop any non-string entries.
+    const names = opt.filter((v): v is string => typeof v === 'string');
+    return { stripSensitiveFields: names };
+  }
+  if (typeof opt === 'function') {
+    console.warn(
+      '[timber] forms.stripSensitiveFields was set to a function in timber.config.ts — ' +
+        'this is not supported at the global level (functions cannot be serialized ' +
+        'into the runtime config). Use a per-action override via ' +
+        '`createActionClient({ stripSensitiveFields: (name) => ... })` instead. ' +
+        'The built-in deny-list will be used globally.'
+    );
+    return {};
+  }
+  return {};
+}
 
+function generateConfigModule(ctx: PluginContext): string {
   const runtimeConfig = {
     output: ctx.config.output ?? 'server',
     csrf: ctx.config.csrf ?? true,
@@ -108,11 +139,24 @@ function generateConfigModule(ctx: PluginContext): string {
     dev: ctx.dev ?? false,
     slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
     slowRequestMs: ctx.config.slowRequestMs ?? 3000,
-    cookieSecrets,
     topLoader: ctx.config.topLoader,
-    responseCache: ctx.config.responseCache,
     debug: ctx.config.debug ?? false,
-
+    serverTiming: ctx.config.serverTiming,
+    renderTimeoutMs: ctx.config.renderTimeoutMs ?? 30_000,
+    // Auto-generated sitemap config — opt-in via timber.config.ts.
+    // See design/16-metadata.md §"Auto-generated Sitemap"
+    sitemap: ctx.config.sitemap,
+    // Forms config — only the serializable subset. `stripSensitiveFields`
+    // accepts boolean | string[] at the global level. Functions must be
+    // configured per-action via `createActionClient({ stripSensitiveFields })`
+    // because JSON.stringify would silently drop them here. See TIM-816.
+    forms: serializeFormsConfig(ctx.config.forms),
+    // Per-build deployment ID for version skew detection (TIM-446).
+    // Null in dev mode — HMR handles code updates without full reloads.
+    deploymentId: ctx.deploymentId ?? null,
+    // Note: project root is NOT included here — it was leaking server
+    // filesystem paths to client bundles (TIM-787). Dev error pages get
+    // the root through the dev server, not the runtime config.
   };
 
   return [
@@ -178,6 +222,53 @@ export function generateInstrumentationModule(instrumentationPath: string | null
   ].join('\n');
 }
 
+/**
+ * Detect the user's timber.config file at the project root.
+ * Returns the absolute path or null if not found.
+ */
+function detectConfigFile(root: string): string | null {
+  const names = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  for (const name of names) {
+    const candidate = resolve(root, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Generate the virtual:timber-cache-handler module source.
+ *
+ * When the user's config has a cacheHandler, generates a module that
+ * dynamically imports the config file and extracts the cacheHandler.
+ * The cacheHandler is a class instance (e.g. RedisCacheHandler) that
+ * cannot be JSON-serialized into virtual:timber-config, so it must
+ * be loaded at runtime via dynamic import. See TIM-599.
+ */
+function generateCacheHandlerModule(configPath: string | null, hasCacheHandler: boolean): string {
+  if (configPath && hasCacheHandler) {
+    return [
+      '// Auto-generated cache handler loader — do not edit.',
+      '// Generated by timber-entries plugin.',
+      '',
+      `export default async function loadCacheHandler() {`,
+      `  const mod = await import(${JSON.stringify(configPath)});`,
+      `  const config = mod.default ?? mod;`,
+      `  return config.cacheHandler ?? null;`,
+      `}`,
+    ].join('\n');
+  }
+
+  return [
+    '// Auto-generated cache handler loader — do not edit.',
+    '// Generated by timber-entries plugin.',
+    '// No cacheHandler configured in timber.config.',
+    '',
+    `export default async function loadCacheHandler() {`,
+    `  return null;`,
+    `}`,
+  ].join('\n');
+}
+
 /**
  * Create the timber-entries Vite plugin.
  *
@@ -220,6 +311,11 @@ export function timberEntries(ctx: PluginContext): Plugin {
         return RESOLVED_INSTRUMENTATION_ID;
       }
 
+      // Check cache handler virtual module
+      if (cleanId === VIRTUAL_IDS.cacheHandler) {
+        return RESOLVED_CACHE_HANDLER_ID;
+      }
+
       return null;
     },
 
@@ -237,6 +333,11 @@ export function timberEntries(ctx: PluginContext): Plugin {
         const instrumentationPath = detectInstrumentationFile(ctx.root);
         return generateInstrumentationModule(instrumentationPath);
       }
+      if (id === RESOLVED_CACHE_HANDLER_ID) {
+        const configPath = detectConfigFile(ctx.root);
+        const hasCacheHandler = ctx.config.cacheHandler != null;
+        return generateCacheHandlerModule(configPath, hasCacheHandler);
+      }
       return null;
     },