@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/src/plugins/server-bundle.ts

@@ -11,8 +11,51 @@
  * Design docs: design/11-platform.md, design/25-production-deployments.md
  */
 
+import { builtinModules } from 'node:module';
 import type { Plugin } from 'vite';
 
+// Every Node built-in as both bare (`stream`) and prefixed (`node:stream`).
+// Available at runtime on all targets (Node natively, Workers via nodejs_compat).
+// Listing explicitly silences Vite's "Automatically externalized" warnings.
+const NODE_BUILTINS: string[] = builtinModules.flatMap((m) => [m, `node:${m}`]);
+
+// Build-time-only packages that must never be bundled into the runtime
+// server environments. With `noExternal: true` rolldown otherwise follows
+// the transitive graph through the user's `timber.config.ts` (loaded by the
+// `virtual:timber-cache-handler` dynamic import) into adapter code, dragging
+// build tooling into the prod server bundle. The most visible symptom is
+// rolldown trying to parse `fsevents.node` as JS and failing with
+// `[UNLOADABLE_DEPENDENCY] … stream did not contain valid UTF-8`.
+//
+//   - `nitro`, `@mdx-js/rollup`              — build-time tooling reachable
+//     transitively through adapter modules and timber's own MDX activation.
+//   - `rollup`                                — pulled in by nitro and
+//     @mdx-js/rollup; declares `fsevents` as an optional native dep.
+//   - `fsevents`, `chokidar`                  — native/optional deps of
+//     rollup/vite. They are macOS-only file watchers with no runtime use
+//     in a server bundle.
+//
+// Mirrored on both rsc and ssr environments. See TIM-988.
+// Cloudflare runtime modules (cloudflare:workers, cloudflare:sockets, etc.)
+// available at runtime on Workers but must not be bundled.
+const CLOUDFLARE_BUILTINS = [
+  'cloudflare:workers',
+  'cloudflare:sockets',
+  'cloudflare:email',
+  'cloudflare:workflows',
+];
+
+const BUILD_ONLY_EXTERNALS: string[] = [
+  ...NODE_BUILTINS,
+  ...CLOUDFLARE_BUILTINS,
+  'vite',
+  'nitro',
+  'rollup',
+  '@mdx-js/rollup',
+  'fsevents',
+  'chokidar',
+];
+
 export function timberServerBundle(): Plugin[] {
   const bundlePlugin: Plugin = {
     name: 'timber-server-bundle',
@@ -80,11 +123,13 @@ export function timberServerBundle(): Plugin[] {
         ssr: { target: 'webworker' },
         environments: {
           rsc: {
-            resolve: { noExternal: true },
+            resolve: { noExternal: true, external: BUILD_ONLY_EXTERNALS },
+            build: { rolldownOptions: { external: [/^cloudflare:/] } },
             define: serverDefine,
           },
           ssr: {
-            resolve: { noExternal: true },
+            resolve: { noExternal: true, external: BUILD_ONLY_EXTERNALS },
+            build: { rolldownOptions: { external: [/^cloudflare:/] } },
             define: serverDefine,
           },
         },
@@ -103,15 +148,18 @@ export function timberServerBundle(): Plugin[] {
   // back to lazy retry on failure. This handles two failure modes:
   //
   // 1. Forward references (e.g. Zod v4): `init_iso` calls `init_schemas`
-  //    which hasn't been defined yet. Eager execution fails, but when the
-  //    function is called lazily later, all dependencies are available.
+  //    which hasn't been defined yet. Eager execution fails silently, but
+  //    when the function is called lazily later, all dependencies are
+  //    available and the retry succeeds (and caches).
   //
   // 2. Optional peer dep shims (e.g. @emotion/is-prop-valid for
   //    framer-motion): Vite generates shims that throw for missing
-  //    optional deps. The throw is deferred to lazy execution where
-  //    the consuming package's try/catch handles it.
+  //    optional deps. The eager attempt swallows the throw; the lazy call
+  //    PROPAGATES it so the consuming package's try/catch handles it.
   //
-  // The key: on failure, `fn` is NOT cleared, so the next call retries.
+  // The key: only the eager attempt swallows errors. Once the helper is
+  // returned, lazy calls use the original Rolldown semantics — a throwing
+  // init propagates to the caller (and clears `fn`, matching upstream).
   // On success, `fn` is set to 0 so subsequent calls are no-ops.
   const esmInitFixPlugin: Plugin = {
     name: 'timber-esm-init-fix',
@@ -122,13 +170,19 @@ export function timberServerBundle(): Plugin[] {
       const lazy = 'var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);';
       if (!code.includes(lazy)) return null;
 
-      // Eager-with-retry: attempt init immediately. On success, mark done
-      // (fn = 0). On failure, leave fn intact so the lazy wrapper retries
-      // on next call — by then forward dependencies are initialized.
+      // Eager-with-retry: attempt init immediately, swallowing failures
+      // (forward refs aren't defined yet). After the eager attempt, flip
+      // to lazy mode where errors propagate to the caller — consumers'
+      // try/catch (framer-motion's optional @emotion dep) must see them.
       const eager = [
         'var __esmMin = (fn, res) => {',
-        '  var l = () => { if (fn) { var f = fn; try { res = f(); fn = 0; } catch(e) {} } return res; };',
+        '  var eager = 1;',
+        '  var l = () => {',
+        '    if (fn) { if (eager) { try { res = fn(); fn = 0; } catch(e) {} } else { res = fn(fn = 0); } }',
+        '    return res;',
+        '  };',
         '  l();',
+        '  eager = 0;',
         '  return l;',
         '};',
       ].join(' ');
@@ -137,5 +191,36 @@ export function timberServerBundle(): Plugin[] {
     },
   };
 
-  return [bundlePlugin, esmInitFixPlugin];
+  // Fix Rolldown's `createRequire(import.meta.url)` CJS interop shim for
+  // Cloudflare Workers. Rolldown emits this for CJS dependencies (e.g.
+  // @opentelemetry/context-async-hooks) that use `require()`. On Workers,
+  // `import.meta.url` is `undefined` for non-entry modules, causing:
+  //   TypeError: The argument 'path' must be a file URL object, a file URL
+  //   string, or an absolute path string. Received 'undefined'
+  //
+  // The fix: provide a fallback URL when `import.meta.url` is undefined.
+  // The actual URL doesn't matter — `createRequire` only needs it for
+  // resolving relative paths, but the only `__require()` calls are for
+  // Node built-ins (events, async_hooks) which resolve from any base.
+  //
+  // The top-level `ssr: { target: 'webworker' }` was supposed to prevent
+  // this, but it doesn't propagate to custom environments (rsc) in Vite's
+  // Environment API. See LOCAL-405.
+  const createRequireFixPlugin: Plugin = {
+    name: 'timber-create-require-fix',
+    applyToEnvironment(environment) {
+      return environment.name === 'rsc' || environment.name === 'ssr';
+    },
+    renderChunk(code) {
+      const pattern = 'createRequire(import.meta.url)';
+      if (!code.includes(pattern)) return null;
+
+      return {
+        code: code.replace(pattern, 'createRequire(import.meta.url || "file:///app")'),
+        map: null,
+      };
+    },
+  };
+
+  return [bundlePlugin, esmInitFixPlugin, createRequireFixPlugin];
 }

package/src/plugins/shims.ts

@@ -5,10 +5,11 @@
  * shim implementations. This enables Next.js-compatible libraries
  * (nuqs, next-intl, etc.) to work unmodified.
  *
- * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports.
- * Those are handled by Vite's native package.json `exports` resolution,
- * which maps them to dist/ files. This ensures a single module instance
- * for shared modules like request-context (ALS singleton).
+ * This plugin also remaps ALL @timber-js/app/* subpath imports to src/ in
+ * server environments (RSC + SSR). This is required because dist/ chunks
+ * are pre-built and miss Vite's RSC transforms (e.g. createContext from
+ * 'react' doesn't exist in RSC's React build). It also ensures a single
+ * module instance for shared mutable state. See SUBPATH_SRC_MAP and TIM-568.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */
@@ -16,7 +17,7 @@
 import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Detect whether we're running from source (src/plugins/) or dist (dist/).
@@ -38,6 +39,82 @@ const SHIMS_DIR = resolve(PKG_ROOT, 'src', 'shims');
 const SERVER_ONLY_VIRTUAL = '\0timber:server-only';
 const CLIENT_ONLY_VIRTUAL = '\0timber:client-only';
 
+/**
+ * Map from @timber-js/app/<subpath> to relative src/ file paths.
+ *
+ * Used by the catch-all resolveId rule to remap subpath imports to src/
+ * in server environments. When adding a new subpath export to package.json,
+ * add it here too — tests/shims-drift.test.ts enumerates package.json
+ * exports and fails if an entry is missing. See TIM-568.
+ *
+ * Exported for the drift test.
+ */
+export const SUBPATH_SRC_MAP: Record<string, string> = {
+  'cache': 'cache/index.ts',
+  'codec': 'codec.ts',
+  'cookies': 'cookies/index.ts',
+  'params': 'params/index.ts',
+  'search-params': 'search-params/index.ts',
+  'segment-params': 'segment-params/index.ts',
+
+  'cache/stores/memory': 'cache/stores/memory.ts',
+  'cache/stores/redis': 'cache/stores/redis.ts',
+  'cache/stores/cloudflare-kv': 'cache/stores/cloudflare-kv.ts',
+  'cache/stores/vercel': 'cache/stores/vercel.ts',
+
+  'cdn': 'cdn/index.ts',
+  'cdn/cloudflare': 'cdn/cloudflare-purge.ts',
+  'cdn/cloudflare-workers': 'cdn/workers-cache-purge.ts',
+  'cdn/fastly': 'cdn/fastly-purge.ts',
+
+  'adapters/cloudflare': 'adapters/cloudflare.ts',
+  'adapters/cloudflare/cache': 'adapters/cloudflare-kv-cache.ts',
+  'adapters/cloudflare/dev': 'adapters/cloudflare-dev.ts',
+  'adapters/nitro': 'adapters/nitro.ts',
+};
+
+/**
+ * Runtime value exports of @timber-js/app/server, stubbed in the client
+ * (browser) environment so a stray client-side import fails with a clear
+ * call-time error instead of a confusing bundler error.
+ *
+ * Must stay in sync with the actual runtime exports of server/index.ts —
+ * tests/shims-drift.test.ts compares this list against
+ * Object.keys(import('../server/index.ts')) and fails on drift.
+ * Type-only exports (DenyOptions, AccessContext, …) are erased at runtime
+ * and must NOT appear here.
+ */
+export const SERVER_STUB_EXPORTS: readonly string[] = [
+  // request-context
+  'getHeaders',
+  'getSegmentParams',
+  // cookie-context
+  'getCookieJar',
+  // primitives
+  'deny',
+  'redirect',
+  'redirectExternal',
+  'RedirectType',
+  'waitUntil',
+  // action-client
+  'createActionClient',
+  'ActionError',
+  'validated',
+  // form-data
+  'coerce',
+  'parseFormData',
+  // form-flash
+  'getFormFlash',
+  // revalidation
+  'revalidatePath',
+  'revalidateTag',
+  // tracing
+  'getTraceId',
+  'getSpanId',
+  'withSpan',
+  'addSpanEvent',
+];
+
 /**
  * Map from next/* import specifiers to shim file paths.
  *
@@ -49,10 +126,14 @@ const SHIM_MAP: Record<string, string> = {
   '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/* and @timber-js/app/fonts/* redirect to the timber-fonts
+  // virtual modules. The fonts plugin's load hook serves the actual module
+  // code. The package.json exports point to shim stubs for non-Vite contexts
+  // (tsc, tests), but in Vite the virtual module takes priority via this map.
   'next/font/google': '\0@timber/fonts/google',
   'next/font/local': '\0@timber/fonts/local',
+  '@timber-js/app/fonts/google': '\0@timber/fonts/google',
+  '@timber-js/app/fonts/local': '\0@timber/fonts/local',
 };
 
 /**
@@ -65,6 +146,16 @@ function stripJsExtension(id: string): string {
   return id.endsWith('.js') ? id.slice(0, -3) : id;
 }
 
+/**
+ * Read the Vite environment name from a plugin hook's `this` context.
+ *
+ * Duck-typed because the hook context type doesn't expose `environment`
+ * in a way that survives our Plugin typing — see Vite's Environment API.
+ */
+function envName(hookCtx: unknown): string | undefined {
+  return (hookCtx as { environment?: { name?: string } }).environment?.name;
+}
+
 /**
  * Create the timber-shims Vite plugin.
  *
@@ -88,14 +179,16 @@ export function timberShims(_ctx: PluginContext): Plugin {
      * 3. Check next/* shim map
      * 4. Return null (pass through) for everything else
      *
-     * @timber-js/app/server is resolved to src/ so it shares the same module
-     * instance as framework internals (which import via #/). This ensures
-     * a single requestContextAls and _getRscFallback variable.
+     * In server environments (RSC + SSR), @timber-js/app/* subpath imports
+     * are remapped to src/ via SUBPATH_SRC_MAP and the explicit branches
+     * below — dist/ chunks miss Vite's RSC transforms and would duplicate
+     * mutable module state (see TIM-568 and the rationale comments below).
      *
-     * @timber-js/app/client is resolved to src/ in the SSR environment so
-     * client hooks share the same module instance as ssr-entry.ts internals.
-     * In RSC it resolves to dist/ (via package.json exports) where 'use client'
-     * is preserved on the entry for client boundary detection.
+     * In the client (browser) environment, imports resolve to dist/ via
+     * package.json exports — except @timber-js/app/client (remapped to src/
+     * to share module instances with browser-entry) and @timber-js/app/server,
+     * which returns a virtual stub: server code must never be bundled into
+     * the browser.
      */
     resolveId(id: string) {
       // Poison pill packages — resolve to virtual modules handled by load()
@@ -110,45 +203,117 @@ export function timberShims(_ctx: PluginContext): Plugin {
       // functions like redirect() and deny(). This prevents server/primitives.ts
       // from being pulled into the browser bundle.
       if (cleanId in SHIM_MAP) {
-        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-        if (envName === 'client' && cleanId === 'next/navigation') {
+        const env = envName(this);
+        if (env === 'client' && cleanId === 'next/navigation') {
           return resolve(SHIMS_DIR, 'navigation-client.ts');
         }
         return SHIM_MAP[cleanId];
       }
 
-      // @timber-js/app/server → src/ in server environments so user code
-      // shares the same module instance as framework internals (single ALS).
-      // In the client environment, return a virtual empty module — server
-      // code must never be bundled into the browser.
+      // ── @timber-js/app/* → src/ resolution in server environments ──
+      //
+      // All @timber-js/app/* subpath imports are remapped to src/ in server
+      // environments (RSC + SSR). This is required for two reasons:
+      //
+      // 1. RSC correctness: dist/ chunks eagerly import from 'react' (e.g.
+      //    createContext in segment-context) which doesn't exist in RSC's
+      //    React build. Vite's RSC plugin only transforms src/ files —
+      //    dist/ chunks are pre-built and served as-is.
+      //
+      // 2. Module singleton correctness: framework internals use relative
+      //    imports that resolve within src/. If user code resolved to dist/
+      //    while framework code resolved to src/, mutable module-level state
+      //    (ALS refs, registered callbacks) would be duplicated. By remapping
+      //    all @timber-js/app/* to src/, everything shares one module graph.
+      //
+      // Exception: @timber-js/app/client in RSC resolves to dist/ where
+      // 'use client' is preserved for client boundary detection.
+      //
+      // In the client (browser) environment, all imports resolve to dist/
+      // via package.json exports (no remapping needed).
+
+      // ── #imports resolution for package-internal modules ─────────────
+      //
+      // #server-internal and #client-internal are Node package imports
+      // (package.json "imports" field). They are only resolvable from
+      // within this package — external consumers get module-not-found.
+      //
+      // In Vite, we intercept them here to resolve to src/ for dev/build
+      // correctness (same rationale as the @timber-js/app/* remap above).
+      if (cleanId === '#server-internal') {
+        const env = envName(this);
+        if (env === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '#client-internal') {
+        // Always resolve to src/ — all environments (RSC, SSR, client)
+        // use src/ for framework internals. In the client env, this
+        // ensures browser-entry and @timber-js/app/client share the
+        // same module graph (both resolve to src/).
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
+      if (cleanId === '#routing') {
+        return resolve(PKG_ROOT, 'src', 'routing', 'index.ts');
+      }
+
+      // Legacy aliases — vitest and monorepo configs may still reference
+      // the old @timber-js/app/server/internal and @timber-js/app/client/internal
+      // specifiers via resolve.alias. When those aliases resolve to the
+      // absolute src/ path, they bypass this plugin entirely. But if the
+      // specifier reaches us unresolved (e.g., in a Vite build without
+      // aliases), handle it the same way as the #imports above.
+      if (cleanId === '@timber-js/app/server/internal') {
+        const env = envName(this);
+        if (env === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '@timber-js/app/client/internal') {
+        // Same as #client-internal above — always resolve to src/.
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
       if (cleanId === '@timber-js/app/server') {
-        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-        if (envName === 'client') {
+        const env = envName(this);
+        if (env === 'client') {
           return '\0timber:server-empty';
         }
+        // RSC + SSR: remap to src/
         return resolve(PKG_ROOT, 'src', 'server', 'index.ts');
       }
 
-      // @timber-js/app/client → src/ in the SSR environment so client hooks
-      // (useParams, usePathname, etc.) share the same module instance as
-      // ssr-entry.ts's internal imports (via #/client/...).
-      //
-      // Without this remap, @timber-js/app/client resolves to dist/ (via
-      // package.json exports), creating a module instance split: ssr-entry.ts
-      // registers the ALS-backed SSR data provider on the src/ instance of
-      // ssr-data.ts, but client component hooks read getSsrData() from the
-      // dist/ instance — which has no provider. Result: hooks like useParams()
-      // return empty defaults during SSR.
-      //
-      // This remap is SSR-only. The RSC environment still resolves to dist/
-      // where 'use client' is preserved on the entry (needed for client
-      // boundary detection). The client (browser) environment uses dist/
-      // for bundling.
       if (cleanId === '@timber-js/app/client') {
-        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-        if (envName === 'ssr') {
+        const env = envName(this);
+        // RSC: return null — needs dist/ for 'use client' boundary detection.
+        // SSR + Client: resolve to src/ so that browser-entry (which uses
+        // relative imports from src/) and user code (which uses the bare
+        // specifier @timber-js/app/client) share the same module instances.
+        // Without this, state.ts is loaded twice (src/ and dist/) and
+        // setGlobalRouter() writes to one copy while getRouterOrNull()
+        // reads from the other (always null).
+        if (env === 'ssr' || env === 'client') {
           return resolve(PKG_ROOT, 'src', 'client', 'index.ts');
         }
+        return null;
+      }
+
+      // Catch-all: remap any other @timber-js/app/<subpath> to src/
+      // in non-client environments (RSC + SSR).
+      if (cleanId.startsWith('@timber-js/app/') && cleanId !== '@timber-js/app/package.json') {
+        const env = envName(this);
+        if (env !== 'client') {
+          const subpath = cleanId.slice('@timber-js/app/'.length);
+          const srcPath = SUBPATH_SRC_MAP[subpath];
+          if (srcPath) {
+            return resolve(PKG_ROOT, 'src', srcPath);
+          }
+        }
       }
 
       return null;
@@ -162,8 +327,8 @@ export function timberShims(_ctx: PluginContext): Plugin {
      * clearly identifies the boundary violation.
      */
     load(id: string) {
-      const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-      const isClient = envName === 'client';
+      const env = envName(this);
+      const isClient = env === 'client';
 
       if (id === SERVER_ONLY_VIRTUAL) {
         if (isClient) {
@@ -193,35 +358,23 @@ export function timberShims(_ctx: PluginContext): Plugin {
       if (id === '\0timber:server-empty') {
         // Export named stubs instead of throwing at evaluation time.
         // Throwing at eval breaks the module system — the browser can't
-        // resolve named imports like `import { notFound } from '...'`.
+        // resolve named imports like `import { deny } from '...'`.
         // Instead, each stub throws at call time with a clear message.
+        // The export names are generated from SERVER_STUB_EXPORTS so the
+        // list cannot drift from server/index.ts (drift test enforced).
+        // RedirectType is a plain const object on the server, so it is
+        // mirrored as one here — libraries read RedirectType.push as a value.
+        const stubExports = SERVER_STUB_EXPORTS.map((name) =>
+          name === 'RedirectType'
+            ? `export const RedirectType = { push: 'push', replace: 'replace' };`
+            : `export const ${name} = stub;`
+        ).join('\n');
         return `
 const msg = "[timber] @timber-js/app/server was imported from client code. " +
   "Server modules (headers, cookies, redirect, deny, etc.) cannot be used in client components. " +
   "If you need these APIs, move the import to a server component or middleware.";
 function stub() { throw new Error(msg); }
-export const headers = stub;
-export const cookies = stub;
-export const searchParams = stub;
-export const deny = stub;
-export const notFound = stub;
-export const redirect = stub;
-export const permanentRedirect = stub;
-export const redirectExternal = stub;
-export const waitUntil = stub;
-export const RenderError = stub;
-export const RedirectType = {};
-export const DenySignal = stub;
-export const RedirectSignal = stub;
-export const createPipeline = stub;
-export const revalidatePath = stub;
-export const revalidateTag = stub;
-export const createActionClient = stub;
-export const ActionError = stub;
-export const validated = stub;
-export const getFormFlash = stub;
-export const parseFormData = stub;
-export const coerce = stub;
+${stubExports}
 `;
       }
     },