Merge pull request #224 from JoviDeCroock/JoviDeCroock/build-time-module-keys

Resolve client module keys exactly via the build-time app dir

Author: JoviDeCroock

.changeset/build-time-module-keys.md

@@ -0,0 +1,5 @@
+---
+"@pracht/vite-plugin": patch
+---
+
+Resolve client module keys exactly against the app manifest directory instead of runtime suffix matching. The virtual client entry previously built a suffix index over every glob key at startup and matched manifest refs by path suffix — ambiguous refs (e.g. two routes both named `index.tsx`) silently resolved to whichever key iterated first. Refs now canonicalize against the manifest file's directory (known at build time) for an exact lookup. In dev, refs that only resolve by suffix still work but log a console error explaining how to fix them; production builds resolve strictly and drop the fallback entirely.

packages/vite-plugin/src/plugin-codegen.ts

@@ -160,6 +160,12 @@ export function createPrachtClientModuleSource(
     ? `${resolved.pagesDir}/**/_app.tsrx`
     : `${resolved.shellsDir}/**/*.tsrx`;
 
+  // Base directory for relative manifest refs: the app manifest file's
+  // directory (refs like "./routes/home.tsx" are written relative to it).
+  const appFilePosix = resolved.appFile.replace(/\\/g, "/").replace(/^\.\//, "");
+  const appFileAbs = appFilePosix.startsWith("/") ? appFilePosix : `/${appFilePosix}`;
+  const appDir = appFileAbs.replace(/\/[^/]*$/, "") || "/";
+
   return [
     'import { resolveApp, initClientRouter, readHydrationState } from "@pracht/core/client";',
     appImport,
@@ -178,31 +184,57 @@ export function createPrachtClientModuleSource(
     "applyRouteLoaderHints(resolvedApp, routeLoaderHints);",
     "",
     ...createApplyRouteLoaderHintsSource(),
-    "function normalizeModuleKey(key) {",
-    '  return key.split("?")[0].replace(/^\\.?\\//, "");',
+    `const APP_DIR = ${JSON.stringify(appDir)};`,
+    "",
+    "// Manifest refs are written relative to the app manifest file",
+    '// ("./routes/home.tsx") while import.meta.glob keys are root-absolute',
+    '// ("/src/routes/home.tsx"). Both sides canonicalize against APP_DIR —',
+    "// known at build time — replacing the previous runtime suffix index.",
+    "function canonicalModuleKey(path) {",
+    '  const raw = path.split("?")[0];',
+    '  const joined = raw.startsWith("/") ? raw : APP_DIR + "/" + raw;',
+    "  const parts = [];",
+    '  for (const segment of joined.split("/")) {',
+    '    if (!segment || segment === ".") continue;',
+    '    if (segment === "..") parts.pop();',
+    "    else parts.push(segment);",
+    "  }",
+    '  return "/" + parts.join("/");',
     "}",
     "",
     "const moduleKeyIndexes = new WeakMap();",
     "function getModuleKeyIndex(modules) {",
     "  let index = moduleKeyIndexes.get(modules);",
     "  if (index) return index;",
     "  index = new Map();",
-    "  for (const key of Object.keys(modules)) {",
-    "    const normalized = normalizeModuleKey(key);",
-    "    if (!normalized) continue;",
-    "    if (!index.has(normalized)) index.set(normalized, key);",
-    '    for (let i = normalized.indexOf("/"); i !== -1; i = normalized.indexOf("/", i + 1)) {',
-    "      const suffix = normalized.slice(i + 1);",
-    "      if (suffix && !index.has(suffix)) index.set(suffix, key);",
-    "    }",
-    "  }",
+    "  for (const key of Object.keys(modules)) index.set(canonicalModuleKey(key), key);",
     "  moduleKeyIndexes.set(modules, index);",
     "  return index;",
     "}",
     "",
     "function findModuleKey(modules, file) {",
     "  if (file in modules) return file;",
-    "  return getModuleKeyIndex(modules).get(normalizeModuleKey(file)) ?? null;",
+    "  const key = getModuleKeyIndex(modules).get(canonicalModuleKey(file));",
+    "  if (key != null) return key;",
+    "  if (import.meta.env?.DEV) {",
+    "    // Dev-only lenient fallback so refs that never canonicalize (written",
+    "    // relative to a file other than the app manifest) keep working while",
+    "    // the console error tells the author to fix them — production builds",
+    "    // resolve strictly and drop this branch.",
+    '    const suffix = "/" + file.split("?")[0].replace(/^\\.?\\//, "");',
+    "    for (const candidate of Object.keys(modules)) {",
+    "      if (canonicalModuleKey(candidate).endsWith(suffix)) {",
+    "        console.error(",
+    "          `[pracht] Module ref ${JSON.stringify(file)} only resolved by suffix matching ` +",
+    "            `against ${JSON.stringify(candidate)}. Write manifest refs relative to the app ` +",
+    '            `manifest file (e.g. "./routes/home.tsx") — suffix matching is disabled in ` +',
+    "            `production builds.`,",
+    "        );",
+    "        return candidate;",
+    "      }",
+    "    }",
+    "  }",
+    "  return null;",
     "}",
     "",
     "const state = readHydrationState();",