@timber-js/app 0.1.0 → 0.1.2

package/src/plugins/dynamic-transform.ts

@@ -0,0 +1,161 @@
+/**
+ * timber-dynamic-transform — Vite sub-plugin for 'use dynamic' directive.
+ *
+ * Detects `'use dynamic'` directives in server component function bodies
+ * and transforms them into `markDynamic()` runtime calls. The directive
+ * declares a dynamic boundary — the component and its subtree opt out of
+ * the pre-rendered shell and render per-request.
+ *
+ * - In `output: 'static'` mode, `'use dynamic'` is a build error.
+ * - In standard SSR routes (no prerender.ts), the directive is a no-op
+ *   (everything is already per-request), but the transform still runs
+ *   so the runtime can skip unnecessary work.
+ *
+ * Design doc: design/15-future-prerendering.md §"'use dynamic'"
+ */
+
+import type { Plugin } from 'vite';
+import type { PluginContext } from '#/index.js';
+import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Quick check: does this source file contain 'use dynamic' anywhere?
+ * Used as a fast bail-out before doing expensive AST parsing.
+ */
+export function containsUseDynamic(code: string): boolean {
+  return containsDirective(code, 'use dynamic');
+}
+
+// ---------------------------------------------------------------------------
+// Transform
+// ---------------------------------------------------------------------------
+
+interface TransformResult {
+  code: string;
+  map?: null;
+}
+
+/**
+ * Find function declarations/expressions containing 'use dynamic' and
+ * transform them into markDynamic() calls.
+ *
+ * Input:
+ * ```tsx
+ * export default async function AddToCartButton({ productId }) {
+ *   'use dynamic'
+ *   const user = await getUser()
+ *   return <button>Add to cart</button>
+ * }
+ * ```
+ *
+ * Output:
+ * ```tsx
+ * import { markDynamic as __markDynamic } from '@timber/app/runtime';
+ * export default async function AddToCartButton({ productId }) {
+ *   __markDynamic();
+ *   const user = await getUser()
+ *   return <button>Add to cart</button>
+ * }
+ * ```
+ *
+ * The markDynamic() call registers the component boundary as dynamic
+ * at render time. The pre-render pass uses this to know which subtrees
+ * to skip and leave as holes for per-request rendering.
+ */
+export function transformUseDynamic(code: string): TransformResult | null {
+  if (!containsUseDynamic(code)) return null;
+
+  const functions = findFunctionsWithDirective(code, 'use dynamic');
+  if (functions.length === 0) return null;
+
+  // Replace directive strings with __markDynamic() calls, processing
+  // from end to start to preserve source offsets
+  let result = code;
+  for (const fn of functions) {
+    // Replace the directive in the body content
+    const cleanBody = fn.bodyContent.replace(/['"]use dynamic['"];?/, '__markDynamic();');
+    // Reconstruct: replace the body content between braces
+    result = result.slice(0, fn.bodyStart) + cleanBody + result.slice(fn.bodyEnd);
+  }
+
+  // Add the import at the top
+  result = `import { markDynamic as __markDynamic } from '@timber/app/runtime';\n` + result;
+
+  return { code: result, map: null };
+}
+
+// ---------------------------------------------------------------------------
+// Static mode validation
+// ---------------------------------------------------------------------------
+
+/**
+ * In `output: 'static'` mode, `'use dynamic'` is a build error.
+ * Static mode renders everything at build time — there is no per-request
+ * rendering to opt into.
+ */
+export function validateNoDynamicInStaticMode(
+  code: string
+): { message: string; line?: number } | null {
+  if (!containsUseDynamic(code)) return null;
+
+  const functions = findFunctionsWithDirective(code, 'use dynamic');
+  if (functions.length === 0) return null;
+
+  return {
+    message:
+      `'use dynamic' cannot be used in static mode (output: 'static'). ` +
+      `Static mode renders all content at build time — there is no per-request rendering. ` +
+      `Remove the directive or switch to output: 'server'.`,
+    line: functions[functions.length - 1].directiveLine, // First occurrence (sorted descending)
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Vite Plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the timber-dynamic-transform Vite plugin.
+ *
+ * In server mode: transforms 'use dynamic' into markDynamic() calls.
+ * In static mode: rejects 'use dynamic' as a build error.
+ */
+export function timberDynamicTransform(ctx: PluginContext): Plugin {
+  const isStatic = ctx.config.output === 'static';
+
+  return {
+    name: 'timber-dynamic-transform',
+
+    transform(code: string, id: string) {
+      // Skip node_modules
+      if (id.includes('node_modules')) return null;
+
+      // Only check files in the app directory
+      if (!id.includes('/app/') && !id.startsWith('app/')) return null;
+
+      // Only check JS/TS files
+      if (!/\.[jt]sx?$/.test(id)) return null;
+
+      // Quick bail-out
+      if (!containsUseDynamic(code)) return null;
+
+      // In static mode, 'use dynamic' is a build error
+      if (isStatic) {
+        const error = validateNoDynamicInStaticMode(code);
+        if (error) {
+          this.error(
+            `[timber] Static mode error in ${id}${error.line ? `:${error.line}` : ''}: ${error.message}`
+          );
+        }
+        return null;
+      }
+
+      // In server mode, transform the directive
+      return transformUseDynamic(code);
+    },
+  };
+}

package/src/plugins/entries.ts

@@ -0,0 +1,207 @@
+/**
+ * timber-entries — Vite sub-plugin for entry virtual module resolution.
+ *
+ * Resolves virtual:timber-rsc-entry, virtual:timber-ssr-entry,
+ * virtual:timber-browser-entry to real TypeScript files, and generates
+ * virtual:timber-config as serialized runtime config.
+ *
+ * Entry modules are real .ts files — NOT codegen strings. The only
+ * generated code is virtual:timber-config (serialized runtime config).
+ *
+ * Design docs: 18-build-system.md §"Entry Generation", §"Virtual Modules"
+ */
+
+import type { Plugin } from 'vite';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { PluginContext } from '#/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC_DIR = resolve(__dirname, '..');
+
+// ─── Virtual Module IDs ──────────────────────────────────────────────────
+
+const VIRTUAL_IDS = {
+  rscEntry: 'virtual:timber-rsc-entry',
+  ssrEntry: 'virtual:timber-ssr-entry',
+  browserEntry: 'virtual:timber-browser-entry',
+  config: 'virtual:timber-config',
+} as const;
+
+/**
+ * Map from virtual module IDs to their resolved file paths.
+ *
+ * These point to .ts source files that Vite transpiles at runtime.
+ * They import virtual modules (virtual:timber-config, etc.) so they
+ * cannot be pre-compiled — they must be processed by Vite's pipeline
+ * with timber's plugin active. The .ts files are included in the
+ * published package via the `files` field.
+ */
+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'),
+};
+
+/** The \0-prefixed resolved ID for virtual:timber-config */
+const RESOLVED_CONFIG_ID = `\0${VIRTUAL_IDS.config}`;
+
+/**
+ * Strip the \0 prefix from a module ID.
+ *
+ * The RSC plugin generates browser entry imports using already-resolved
+ * \0-prefixed IDs. Vite's import-analysis cannot resolve these.
+ * See 18-build-system.md §"Resolution Quirks".
+ */
+function stripNullPrefix(id: string): string {
+  return id.startsWith('\0') ? id.slice(1) : id;
+}
+
+/**
+ * Strip a root directory prefix from a module ID.
+ *
+ * Vite prefixes virtual module IDs with the project root when resolving
+ * SSR build entries. We need to handle both `virtual:timber-rsc-entry`
+ * and `<root>/virtual:timber-rsc-entry`.
+ * See 18-build-system.md §"Resolution Quirks".
+ */
+function stripRootPrefix(id: string, root: string): string {
+  if (id.startsWith(root)) {
+    // Remove root + path separator
+    const stripped = id.slice(root.length);
+    // Handle both /virtual:... and \virtual:... (Windows)
+    if (stripped.startsWith('/') || stripped.startsWith('\\')) {
+      return stripped.slice(1);
+    }
+    return stripped;
+  }
+  return id;
+}
+
+/**
+ * Generate the virtual:timber-config module source.
+ *
+ * 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);
+
+  const runtimeConfig = {
+    output: ctx.config.output ?? 'server',
+    csrf: ctx.config.csrf ?? true,
+    allowedOrigins: ctx.config.allowedOrigins,
+    clientJavascript: ctx.clientJavascript,
+    dev: ctx.dev ?? false,
+    slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
+    cookieSecrets,
+  };
+
+  return [
+    '// Auto-generated runtime config — do not edit.',
+    '// Generated by timber-entries plugin.',
+    '',
+    `const config = ${JSON.stringify(runtimeConfig, null, 2)};`,
+    '',
+    'export default config;',
+  ].join('\n');
+}
+
+/**
+ * Create the timber-entries Vite plugin.
+ *
+ * Hooks: resolveId, load
+ */
+export function timberEntries(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-entries',
+
+    /**
+     * Resolve virtual entry and config module IDs.
+     *
+     * Handles:
+     * - virtual:timber-rsc-entry → real file path
+     * - virtual:timber-ssr-entry → real file path
+     * - virtual:timber-browser-entry → real file path
+     * - virtual:timber-config → \0-prefixed virtual ID
+     * - \0 prefix stripping (RSC plugin re-imports)
+     * - Root prefix stripping (SSR build entries)
+     */
+    resolveId(id: string) {
+      // Step 1: Strip \0 prefix if present
+      let cleanId = stripNullPrefix(id);
+
+      // Step 2: Strip root prefix if present
+      cleanId = stripRootPrefix(cleanId, ctx.root);
+
+      // Check entry file map (real files)
+      if (cleanId in ENTRY_FILE_MAP) {
+        return ENTRY_FILE_MAP[cleanId];
+      }
+
+      // Check config virtual module
+      if (cleanId === VIRTUAL_IDS.config) {
+        return RESOLVED_CONFIG_ID;
+      }
+
+      return null;
+    },
+
+    /**
+     * Load the virtual:timber-config module.
+     *
+     * Entry files (rsc/ssr/browser) are real TypeScript files that Vite
+     * processes normally. Only virtual:timber-config needs generated code.
+     */
+    load(id: string) {
+      if (id === RESOLVED_CONFIG_ID) {
+        return generateConfigModule(ctx);
+      }
+      return null;
+    },
+
+    /**
+     * Rename "rsc-entry" chunks in the client build to "rsc-client-entry".
+     *
+     * The RSC plugin creates client reference facades named after the RSC
+     * entry (virtual:timber-rsc-entry), producing chunks like "rsc-entry-XYZ.js"
+     * in the client output. This is confusing since those chunks contain client
+     * components, not server code. Renaming clarifies their purpose.
+     */
+    generateBundle(_options, bundle) {
+      if ((this as any).environment?.name !== 'client') return;
+
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== 'chunk') continue;
+        if (!chunk.name?.startsWith('rsc-entry')) continue;
+
+        const newFileName = fileName.replace('rsc-entry', 'rsc-client-entry');
+        // Extract just the basename for matching code references like "./rsc-entry-XYZ.js"
+        const oldBase = fileName.split('/').pop()!;
+        const newBase = newFileName.split('/').pop()!;
+
+        chunk.fileName = newFileName;
+        chunk.name = chunk.name.replace('rsc-entry', 'rsc-client-entry');
+        bundle[newFileName] = chunk;
+        delete bundle[fileName];
+
+        // Update import references in other chunks
+        for (const other of Object.values(bundle)) {
+          if (other.type !== 'chunk') continue;
+          if (other.code.includes(oldBase)) {
+            other.code = other.code.replaceAll(oldBase, newBase);
+          }
+          if (other.imports) {
+            other.imports = other.imports.map((i) => (i === fileName ? newFileName : i));
+          }
+          if (other.dynamicImports) {
+            other.dynamicImports = other.dynamicImports.map((i) =>
+              i === fileName ? newFileName : i
+            );
+          }
+        }
+      }
+    },
+  };
+}