@timber-js/app 0.1.17 → 0.1.18

package/dist/plugins/shims.d.ts

@@ -1,14 +1,19 @@
 /**
- * timber-shims — Vite sub-plugin for next/* → timber shim resolution.
+ * timber-shims — Vite sub-plugin for next/* → timber shim resolution
+ * and #/ subpath import canonicalization.
  *
- * 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.
+ * Two responsibilities:
+ * 1. 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.
+ * 2. Canonicalizes #/* subpath imports (package.json "imports" field) to
+ *    absolute file paths, preventing Vite dev from creating duplicate
+ *    module instances when the same file is reached via different import
+ *    paths (e.g., #/client/router-ref.js vs ./router-ref.js).
  *
- * 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).
+ * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports
+ * (except @timber-js/app/server). Those are handled by Vite's native
+ * package.json `exports` resolution, which maps them to dist/ files.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */

package/dist/plugins/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6DhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAkIvD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAmFhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAmJvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/router-ref.ts

@@ -1,9 +1,17 @@
 // Global router reference — shared between browser-entry and client hooks.
 // This module has no dependencies on virtual modules, so it can be safely
 // imported by client hooks without pulling in browser-entry's virtual imports.
+//
+// The router is stored as a module-level variable. The timber-shims plugin
+// canonicalizes #/* subpath imports to absolute file paths, ensuring that
+// all import chains (shim chain, browser-entry relative imports, etc.)
+// resolve to the same module instance in Vite's module graph.
+//
+// See design/18-build-system.md §"Subpath Import Canonicalization"
 
 import type { RouterInstance } from './router.js';
 
+/** Module-level singleton — set once during bootstrap. */
 let globalRouter: RouterInstance | null = null;
 
 /**
@@ -32,3 +40,12 @@ export function getRouter(): RouterInstance {
 export function getRouterOrNull(): RouterInstance | null {
   return globalRouter;
 }
+
+/**
+ * Reset the global router to null. Used only in tests to isolate
+ * module-level state between test cases.
+ * @internal
+ */
+export function resetGlobalRouter(): void {
+  globalRouter = null;
+}

package/src/client/use-router.ts

@@ -27,16 +27,6 @@ export interface AppRouterInstance {
   prefetch(href: string): void;
 }
 
-/** No-op router returned during SSR or before bootstrap. All methods are safe no-ops. */
-const SSR_NOOP_ROUTER: AppRouterInstance = {
-  push() {},
-  replace() {},
-  refresh() {},
-  back() {},
-  forward() {},
-  prefetch() {},
-};
-
 /**
  * Get a router instance for programmatic navigation.
  *
@@ -47,7 +37,7 @@ const SSR_NOOP_ROUTER: AppRouterInstance = {
  * because during hydration, React synchronously executes component render
  * functions *before* the router is bootstrapped in browser-entry.ts.
  * If we eagerly captured the router during render, components would get
- * the SSR_NOOP_ROUTER and be stuck with silent no-ops forever.
+ * a null reference and be stuck with silent no-ops forever.
  *
  * Returns safe no-ops during SSR or before bootstrap. The `typeof window`
  * check is insufficient because Vite's client SSR environment defines
@@ -60,7 +50,9 @@ export function useRouter(): AppRouterInstance {
       const router = getRouterOrNull();
       if (!router) {
         if (process.env.NODE_ENV === 'development') {
-          console.error('[timber] useRouter().push() called but router is not initialized. This is a bug — please report it.');
+          console.error(
+            '[timber] useRouter().push() called but router is not initialized. This is a bug — please report it.'
+          );
         }
         return;
       }

package/src/plugins/shims.ts

@@ -1,20 +1,26 @@
 /**
- * timber-shims — Vite sub-plugin for next/* → timber shim resolution.
+ * timber-shims — Vite sub-plugin for next/* → timber shim resolution
+ * and #/ subpath import canonicalization.
  *
- * 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.
+ * Two responsibilities:
+ * 1. 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.
+ * 2. Canonicalizes #/* subpath imports (package.json "imports" field) to
+ *    absolute file paths, preventing Vite dev from creating duplicate
+ *    module instances when the same file is reached via different import
+ *    paths (e.g., #/client/router-ref.js vs ./router-ref.js).
  *
- * 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).
+ * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports
+ * (except @timber-js/app/server). Those are handled by Vite's native
+ * package.json `exports` resolution, which maps them to dist/ files.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */
 
 import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { PluginContext } from '#/index.js';
 
@@ -26,6 +32,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = __dirname.endsWith('plugins')
   ? resolve(__dirname, '..', '..')
   : resolve(__dirname, '..');
+const SRC_DIR = resolve(PKG_ROOT, 'src');
 const SHIMS_DIR = resolve(PKG_ROOT, 'src', 'shims');
 
 /**
@@ -55,18 +62,6 @@ const SHIM_MAP: Record<string, string> = {
   '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'),
-};
-
 /**
  * Strip .js extension from an import specifier.
  *
@@ -77,6 +72,39 @@ function stripJsExtension(id: string): string {
   return id.endsWith('.js') ? id.slice(0, -3) : id;
 }
 
+/**
+ * Resolve a #/* subpath import to an absolute file path.
+ *
+ * The package.json "imports" field maps #/* → ./src/*. Vite's resolver
+ * handles this via Node.js subpath imports, but in dev mode the resulting
+ * module URL can differ from a relative import to the same file. This
+ * causes module duplication — the same file loaded as two separate ES
+ * modules with separate module-level state.
+ *
+ * This function resolves #/foo/bar.js to <PKG_ROOT>/src/foo/bar.ts
+ * (trying .ts first, then .tsx, then .js, then the raw path).
+ * Returns null if the import is not a #/ import or the file doesn't exist.
+ */
+function resolveSubpathImport(id: string): string | null {
+  if (!id.startsWith('#/')) return null;
+
+  // Strip the #/ prefix and map to src/
+  const subpath = id.slice(2);
+  const basePath = resolve(SRC_DIR, subpath);
+
+  // Strip .js extension and try TypeScript extensions first
+  const withoutJs = stripJsExtension(basePath);
+  for (const ext of ['.ts', '.tsx', '.js']) {
+    const candidate = withoutJs + ext;
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // Try the raw path (e.g., if it already has the right extension)
+  if (existsSync(basePath)) return basePath;
+
+  return null;
+}
+
 /**
  * Create the timber-shims Vite plugin.
  *
@@ -92,13 +120,21 @@ export function timberShims(_ctx: PluginContext): Plugin {
     enforce: 'pre',
 
     /**
-     * Resolve next/* imports to shim files.
+     * Resolve imports to canonical file paths.
      *
      * 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. Return null (pass through) for everything else
+     * 2. Canonicalize #/* subpath imports to absolute paths
+     * 3. Strip .js extension from the import specifier
+     * 4. Check next/* shim map (with client environment override for navigation)
+     * 5. Handle @timber-js/app/server
+     * 6. Return null (pass through) for everything else
+     *
+     * #/* canonicalization (step 2) prevents module duplication in Vite dev.
+     * Package.json "imports" maps #/* → ./src/*, but Vite can resolve the
+     * same file to different module URLs depending on the import chain.
+     * By resolving #/ imports to absolute paths here, all import paths
+     * converge to a single module instance.
      *
      * @timber-js/app/server is resolved to src/ so it shares the same module
      * instance as framework internals (which import via #/). This ensures
@@ -112,15 +148,24 @@ export function timberShims(_ctx: PluginContext): Plugin {
       if (id === 'server-only') return SERVER_ONLY_VIRTUAL;
       if (id === 'client-only') return CLIENT_ONLY_VIRTUAL;
 
+      // Canonicalize #/* subpath imports to absolute file paths.
+      // This is the fix for module duplication (LOCAL-302): ensures that
+      // #/client/router-ref.js and ./router-ref.js from the same directory
+      // resolve to the same module URL in Vite's module graph.
+      const subpathResolved = resolveSubpathImport(id);
+      if (subpathResolved) return subpathResolved;
+
       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.
+      // In the client (browser) environment, next/navigation 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.
       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];
+        if (envName === 'client' && cleanId === 'next/navigation') {
+          return resolve(SHIMS_DIR, 'navigation-client.ts');
         }
         return SHIM_MAP[cleanId];
       }