@timber-js/app 0.1.1 → 0.1.3

package/src/plugins/server-action-exports.ts

@@ -0,0 +1,220 @@
+import type { Plugin } from 'vite';
+import { Parser } from 'acorn';
+import acornJsx from 'acorn-jsx';
+import { detectFileDirective } from '#/utils/directive-parser.js';
+
+const jsxParser = Parser.extend(acornJsx());
+
+/**
+ * Rewrite 'use server' module exports to bypass RSC plugin AST validation.
+ *
+ * The RSC plugin's client/SSR proxy transform (transformProxyExport) requires
+ * all `export const` initializers to be `async ArrowFunctionExpression`. But
+ * `createActionClient().action()` and `validated()` return async functions via
+ * CallExpressions — valid at runtime but rejected by the static AST check.
+ *
+ * This plugin rewrites non-function-expression exports from:
+ *
+ *   export const foo = someCall();
+ *
+ * to:
+ *
+ *   const foo = someCall();
+ *   export { foo };
+ *
+ * The `export { name }` form bypasses the RSC plugin's validation without
+ * changing runtime semantics. Function expression exports (async arrows,
+ * async function expressions) are left untouched.
+ *
+ * See design/08-forms-and-actions.md §"Middleware for Server Actions"
+ */
+export function timberServerActionExports(): Plugin {
+  return {
+    name: 'timber-server-action-exports',
+    transform(code, id) {
+      // Skip non-JS/TS files
+      if (!/\.[jt]sx?$/.test(id)) return;
+      // Quick bail-out
+      if (!code.includes('use server')) return;
+      // Check for file-level directive
+      const directive = detectFileDirective(code, ['use server']);
+      if (!directive) return;
+
+      return rewriteServerActionExports(code);
+    },
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AcornNode = any;
+
+/**
+ * Check if an AST node is an async function expression (arrow or regular).
+ * These are handled correctly by the RSC plugin and don't need rewriting.
+ */
+function isAsyncFunctionExpr(node: AcornNode): boolean {
+  if (!node) return false;
+  return (
+    (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression') && node.async
+  );
+}
+
+/**
+ * Extract identifier names from a declarator's id pattern.
+ * Handles simple identifiers and destructuring patterns.
+ */
+function extractDeclNames(id: AcornNode): string[] {
+  if (id.type === 'Identifier') return [id.name];
+
+  // ObjectPattern: const { a, b } = ...
+  if (id.type === 'ObjectPattern') {
+    return id.properties.flatMap((p: AcornNode) => extractDeclNames(p.value ?? p.argument));
+  }
+
+  // ArrayPattern: const [a, b] = ...
+  if (id.type === 'ArrayPattern') {
+    return id.elements.filter(Boolean).flatMap((e: AcornNode) => extractDeclNames(e));
+  }
+
+  // RestElement: const [...rest] = ...
+  if (id.type === 'RestElement') {
+    return extractDeclNames(id.argument);
+  }
+
+  // AssignmentPattern: const { a = 1 } = ...
+  if (id.type === 'AssignmentPattern') {
+    return extractDeclNames(id.left);
+  }
+
+  return [];
+}
+
+interface RewriteTarget {
+  /** Start offset of the `export` keyword */
+  exportStart: number;
+  /** Start offset of the `const/let/var` keyword (right after `export `) */
+  declStart: number;
+  /** Names to re-export */
+  names: string[];
+}
+
+function rewriteServerActionExports(code: string): { code: string; map: null } | undefined {
+  let ast: AcornNode;
+  try {
+    ast = jsxParser.parse(code, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    });
+  } catch {
+    // TypeScript that esbuild hasn't stripped yet — use regex fallback
+    return rewriteServerActionExportsFallback(code);
+  }
+
+  const targets: RewriteTarget[] = [];
+
+  for (const node of ast.body) {
+    // Case 1: export const/let/var name = <non-function-expression>
+    if (
+      node.type === 'ExportNamedDeclaration' &&
+      node.declaration?.type === 'VariableDeclaration'
+    ) {
+      const hasNonFunctionInit = node.declaration.declarations.some(
+        (d: AcornNode) => d.init && !isAsyncFunctionExpr(d.init)
+      );
+      if (!hasNonFunctionInit) continue;
+
+      const names = node.declaration.declarations.flatMap((d: AcornNode) => extractDeclNames(d.id));
+      if (names.length === 0) continue;
+
+      targets.push({
+        exportStart: node.start,
+        declStart: node.declaration.start,
+        names,
+      });
+    }
+
+    // Case 2: export default <non-function-expression>
+    if (node.type === 'ExportDefaultDeclaration') {
+      const decl = node.declaration;
+      if (
+        decl.type !== 'FunctionDeclaration' &&
+        decl.type !== 'Identifier' &&
+        !isAsyncFunctionExpr(decl)
+      ) {
+        // export default someCall() → const $$default = someCall(); export default $$default;
+        targets.push({
+          exportStart: node.start,
+          declStart: -1, // sentinel for default export
+          names: ['default'],
+        });
+      }
+    }
+  }
+
+  if (targets.length === 0) return undefined;
+
+  // Process from end to start to preserve character positions
+  let result = code;
+  const reExports: string[] = [];
+
+  for (let i = targets.length - 1; i >= 0; i--) {
+    const target = targets[i];
+
+    if (target.declStart === -1) {
+      // export default <expr> → const $$default = <expr>;\nexport default $$default;
+      const node = ast.body.find(
+        (n: AcornNode) => n.type === 'ExportDefaultDeclaration' && n.start === target.exportStart
+      );
+      if (node) {
+        const exprCode = code.slice(node.declaration.start, node.declaration.end);
+        const replacement = `const $$default = ${exprCode};\nexport default $$default;`;
+        result = result.slice(0, node.start) + replacement + result.slice(node.end);
+      }
+      continue;
+    }
+
+    // Remove 'export ' from the declaration
+    result = result.slice(0, target.exportStart) + result.slice(target.declStart);
+    reExports.push(...target.names);
+  }
+
+  if (reExports.length > 0) {
+    result += '\nexport { ' + reExports.join(', ') + ' };\n';
+  }
+
+  return { code: result, map: null };
+}
+
+/**
+ * Regex fallback for TypeScript files that acorn cannot parse.
+ *
+ * Matches `export const/let/var name = <expr>` where the initializer does
+ * NOT start with `async function` or `async (` (i.e., not an async
+ * function expression or async arrow function).
+ */
+function rewriteServerActionExportsFallback(code: string): { code: string; map: null } | undefined {
+  // Match: export const/let/var <name> = <non-async-function-expr>
+  const pattern =
+    /^(export\s+)((?:const|let|var)\s+(\w+)\s*=\s*)(?!async\s+(?:function[\s(]|\())/gm;
+
+  const names: string[] = [];
+  let result = code;
+  let offset = 0;
+  let match;
+
+  while ((match = pattern.exec(code)) !== null) {
+    const exportKeyword = match[1]; // 'export ' (with trailing space)
+    const name = match[3];
+
+    // Remove 'export ' at this position (adjusted for prior removals)
+    const pos = match.index + offset;
+    result = result.slice(0, pos) + result.slice(pos + exportKeyword.length);
+    offset -= exportKeyword.length;
+    names.push(name);
+  }
+
+  if (names.length === 0) return undefined;
+
+  result += '\nexport { ' + names.join(', ') + ' };\n';
+  return { code: result, map: null };
+}

package/src/plugins/server-bundle.ts

@@ -0,0 +1,113 @@
+/**
+ * timber-server-bundle — Bundle all dependencies for server environments.
+ *
+ * In production builds, sets `resolve.noExternal: true` for the rsc and ssr
+ * environments. This ensures all npm dependencies are bundled into the output,
+ * which is required for platforms like Cloudflare Workers that don't have
+ * access to node_modules at runtime.
+ *
+ * In dev mode, Vite's default externalization is preserved for fast HMR.
+ *
+ * Design docs: design/11-platform.md, design/25-production-deployments.md
+ */
+
+import type { Plugin } from 'vite';
+
+export function timberServerBundle(): Plugin[] {
+  const bundlePlugin: Plugin = {
+    name: 'timber-server-bundle',
+
+    config(_cfg, { command }) {
+      // In dev mode, Vite externalizes node_modules by default for fast HMR.
+      // But server-only/client-only must NOT be externalized — they need to
+      // go through the timber-shims plugin so it can replace them with no-op
+      // virtual modules. Without this, deps like `bright` that import
+      // `server-only` get the real CJS package loaded via Node's require(),
+      // which throws in the SSR environment.
+      if (command === 'serve') {
+        // In dev, Vite externalizes node_modules and loads them via Node's
+        // native require(). Deps that import `server-only` (like `bright`)
+        // hit the real CJS package which throws at runtime. We force these
+        // poison-pill packages to be non-external so they go through Vite's
+        // module pipeline, where the timber-shims plugin intercepts them
+        // and serves no-op virtual modules for server environments.
+        return {
+          environments: {
+            rsc: {
+              resolve: {
+                noExternal: ['server-only', 'client-only'],
+              },
+            },
+            ssr: {
+              resolve: {
+                noExternal: ['server-only', 'client-only'],
+              },
+            },
+          },
+        };
+      }
+
+      // Bundle all dependencies in server environments for production.
+      // Without this, bare imports like 'nuqs/adapters/custom' are left
+      // as external imports in the output, which fails on platforms
+      // without node_modules (Cloudflare Workers, edge runtimes).
+      // Define process.env.NODE_ENV in server environments so that
+      // dead-code branches (dev-only tracing, React dev checks) are
+      // eliminated by Rollup's tree-shaking. Without this, the runtime
+      // check falls through on platforms where process.env is empty
+      // (e.g. Cloudflare Workers), causing dev code to run in production.
+      const serverDefine = {
+        'process.env.NODE_ENV': JSON.stringify('production'),
+      };
+
+      return {
+        // Target webworker so Rolldown doesn't emit createRequire(import.meta.url)
+        // shims that fail in Cloudflare Workers where import.meta.url is undefined
+        // for non-entry modules. See design/11-platform.md.
+        ssr: { target: 'webworker' },
+        environments: {
+          rsc: {
+            resolve: { noExternal: true },
+            define: serverDefine,
+          },
+          ssr: {
+            resolve: { noExternal: true },
+            define: serverDefine,
+          },
+        },
+      };
+    },
+  };
+
+  // Fix Rolldown's broken `__esmMin` lazy initializers in server bundles.
+  //
+  // Rolldown wraps ESM module initialization in `__esmMin` lazy functions.
+  // For packages with `sideEffects: false` (e.g. nuqs), Rolldown drops
+  // the variable assignment of the init function — so the module's React
+  // imports, context creation, etc. never execute.
+  //
+  // The fix: patch the `__esmMin` runtime definition to eagerly execute
+  // the init callback while still returning the lazy wrapper. This makes
+  // all ESM module inits run at load time (standard ESM behavior) instead
+  // of lazily, which is functionally correct and avoids the dropped-init bug.
+  const esmInitFixPlugin: Plugin = {
+    name: 'timber-esm-init-fix',
+    applyToEnvironment(environment) {
+      return environment.name === 'rsc' || environment.name === 'ssr';
+    },
+    renderChunk(code) {
+      const lazy = 'var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);';
+      if (!code.includes(lazy)) return null;
+
+      // Replace with eager-then-lazy: execute init immediately, then
+      // return the lazy wrapper for any subsequent calls (which are
+      // idempotent since fn is set to 0 after first execution).
+      const eager =
+        'var __esmMin = (fn, res) => { var l = () => (fn && (res = fn(fn = 0)), res); l(); return l; };';
+
+      return { code: code.replace(lazy, eager), map: null };
+    },
+  };
+
+  return [bundlePlugin, esmInitFixPlugin];
+}

package/src/plugins/shims.ts

@@ -0,0 +1,168 @@
+/**
+ * timber-shims — Vite sub-plugin for next/* → timber shim resolution.
+ *
+ * Intercepts imports of next/* modules and redirects them to timber.js
+ * shim implementations. This enables Next.js-compatible libraries
+ * (nuqs, next-intl, etc.) to work unmodified.
+ *
+ * Design doc: 18-build-system.md §"Shim Map"
+ */
+
+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 SHIMS_DIR = resolve(__dirname, '..', 'shims');
+
+/**
+ * Virtual module IDs for server-only and client-only poison pills.
+ *
+ * These packages cause build errors when imported in the wrong environment:
+ * - `server-only` errors when imported in a client component
+ * - `client-only` errors when imported in a server component
+ */
+const SERVER_ONLY_VIRTUAL = '\0timber:server-only';
+const CLIENT_ONLY_VIRTUAL = '\0timber:client-only';
+
+/**
+ * Map from next/* import specifiers to shim file paths.
+ *
+ * The shim map is a separate data structure (not embedded in the plugin)
+ * per the task's approach constraints.
+ */
+const SHIM_MAP: Record<string, string> = {
+  'next/link': resolve(SHIMS_DIR, 'link.ts'),
+  'next/image': resolve(SHIMS_DIR, 'image.ts'),
+  'next/navigation': resolve(SHIMS_DIR, 'navigation.ts'),
+  'next/headers': resolve(SHIMS_DIR, 'headers.ts'),
+  // next/font/* redirects to the timber-fonts virtual modules.
+  // The fonts plugin's load hook serves the actual module code.
+  'next/font/google': '\0@timber/fonts/google',
+  'next/font/local': '\0@timber/fonts/local',
+};
+
+/**
+ * Client-only shim overrides for the browser environment.
+ *
+ * next/navigation in the client environment resolves to navigation-client.ts
+ * which only re-exports client hooks — not server functions like redirect()
+ * and deny(). This prevents server/primitives.ts from being pulled into the
+ * browser bundle via tree-shaking-resistant imports.
+ */
+const CLIENT_SHIM_OVERRIDES: Record<string, string> = {
+  'next/navigation': resolve(SHIMS_DIR, 'navigation-client.ts'),
+};
+
+/**
+ * Map from @timber/app/* subpath imports to real source files.
+ *
+ * These resolve subpath imports like `@timber/app/server` to the
+ * real entry files in the package source.
+ */
+const TIMBER_SUBPATH_MAP: Record<string, string> = {
+  '@timber/app/server': resolve(__dirname, '..', 'server', 'index.ts'),
+  '@timber/app/client': resolve(__dirname, '..', 'client', 'index.ts'),
+  '@timber/app/cache': resolve(__dirname, '..', 'cache', 'index.ts'),
+  '@timber/app/search-params': resolve(__dirname, '..', 'search-params', 'index.ts'),
+  '@timber/app/routing': resolve(__dirname, '..', 'routing', 'index.ts'),
+};
+
+/**
+ * Strip .js extension from an import specifier.
+ *
+ * Libraries like nuqs import `next/navigation.js` with an explicit
+ * extension. We strip it before matching against the shim map.
+ */
+function stripJsExtension(id: string): string {
+  return id.endsWith('.js') ? id.slice(0, -3) : id;
+}
+
+/**
+ * Create the timber-shims Vite plugin.
+ *
+ * Hooks: resolveId, load
+ */
+export function timberShims(_ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-shims',
+    // Must run before Vite's built-in resolution so that server-only/client-only
+    // poison pills are intercepted even when imported from node_modules deps
+    // (e.g. bright, next-intl). Without this, the dep optimizer resolves to the
+    // real CJS package which throws at runtime in the SSR environment.
+    enforce: 'pre',
+
+    /**
+     * Resolve next/* and @timber/app/* imports to shim/source files.
+     *
+     * Resolution order:
+     * 1. Check server-only / client-only poison pill packages
+     * 2. Strip .js extension from the import specifier
+     * 3. Check next/* shim map
+     * 4. Check @timber/app/* subpath map
+     * 5. Return null (pass through) for unrecognized imports
+     */
+    resolveId(id: string) {
+      // Poison pill packages — resolve to virtual modules handled by load()
+      if (id === 'server-only') return SERVER_ONLY_VIRTUAL;
+      if (id === 'client-only') return CLIENT_ONLY_VIRTUAL;
+
+      const cleanId = stripJsExtension(id);
+
+      // Check next/* shim map.
+      // In the client (browser) environment, use client-only shim overrides
+      // to avoid pulling server code (primitives.ts) into the browser bundle.
+      if (cleanId in SHIM_MAP) {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'client' && cleanId in CLIENT_SHIM_OVERRIDES) {
+          return CLIENT_SHIM_OVERRIDES[cleanId];
+        }
+        return SHIM_MAP[cleanId];
+      }
+
+      // Check @timber/app/* subpath map
+      if (cleanId in TIMBER_SUBPATH_MAP) {
+        return TIMBER_SUBPATH_MAP[cleanId];
+      }
+
+      return null;
+    },
+
+    /**
+     * Serve virtual modules for server-only / client-only poison pills.
+     *
+     * In the correct environment, the module is a no-op (empty export).
+     * In the wrong environment, it throws a build-time error message that
+     * clearly identifies the boundary violation.
+     */
+    load(id: string) {
+      const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+      const isClient = envName === 'client';
+
+      if (id === SERVER_ONLY_VIRTUAL) {
+        if (isClient) {
+          return `throw new Error(
+  "This module cannot be imported from a Client Component module. " +
+  "It should only be used from a Server Component."
+);`;
+        }
+        // No-op in server environments (rsc, ssr)
+        return 'export {};';
+      }
+
+      if (id === CLIENT_ONLY_VIRTUAL) {
+        if (!isClient) {
+          return `throw new Error(
+  "This module cannot be imported from a Server Component module. " +
+  "It should only be used from a Client Component."
+);`;
+        }
+        // No-op in client environment
+        return 'export {};';
+      }
+
+      return null;
+    },
+  };
+}