@lwrjs/shared-utils 0.21.7 → 0.22.1

package/build/cjs/fs.cjs

@@ -33,6 +33,7 @@ __export(exports, {
   getViewSourceFromFile: () => getViewSourceFromFile,
   hashContent: () => hashContent,
   isLocalPath: () => isLocalPath,
+  joinUrlPath: () => joinUrlPath,
   mimeLookup: () => import_mime_types.lookup,
   normalizeAssetSpecifier: () => normalizeAssetSpecifier,
   normalizeDirectory: () => normalizeDirectory,
@@ -42,7 +43,8 @@ __export(exports, {
   readFile: () => readFile,
   resolveFileExtension: () => resolveFileExtension,
   streamToString: () => streamToString,
-  stringToStream: () => stringToStream
+  stringToStream: () => stringToStream,
+  toForwardSlash: () => toForwardSlash
 });
 var import_fs_extra = __toModule(require("fs-extra"));
 var import_path = __toModule(require("path"));
@@ -173,6 +175,20 @@ function normalizeResourcePath(rawPath, {rootDir, assets, contentDir, layoutsDir
     return alias;
   });
 }
+function toForwardSlash(p) {
+  return p.replace(/\\/g, "/").replace(/%5C/gi, "/");
+}
+function joinUrlPath(...segments) {
+  const parts = segments.filter((s) => s !== "");
+  return parts.map((seg, i) => {
+    let s = toForwardSlash(seg);
+    if (i > 0 && !s.startsWith("/"))
+      s = `/${s}`;
+    if (i < parts.length - 1)
+      s = s.replace(/\/$/, "");
+    return s;
+  }).join("");
+}
 function logMetrics(filePath) {
   if (import_diagnostics2.logger.isDebugEnabled()) {
     let count = files.get(filePath) || 0;
@@ -191,11 +207,11 @@ function normalizeAssetSpecifier(assetId, assetPathMap, resourcePaths, basePath)
     if (!importer) {
       throw Error(`Unable to resolve relative import "${specifier}" without an importer.`);
     }
-    return import_path.default.join(import_path.default.dirname(importer), specifier);
+    return toForwardSlash(import_path.default.join(import_path.default.dirname(importer), specifier));
   }
   if (type === "content-asset") {
     const originSpecifier = !basePath ? specifier : specifier.split(basePath)[1];
-    return import_path.default.join(resourcePaths.contentDir, originSpecifier);
+    return toForwardSlash(import_path.default.join(resourcePaths.contentDir, originSpecifier));
   }
   if (specifier[0] === "$") {
     return normalizeResourcePath(specifier, resourcePaths);

package/build/cjs/mrt-utils.cjs

@@ -29,13 +29,14 @@ __export(exports, {
   getSsgAppRelativePath: () => getSsgAppRelativePath
 });
 var import_path = __toModule(require("path"));
+var import_fs = __toModule(require("./fs.cjs"));
 var MRT_BASE_URL = `/mobify/bundle/${process.env.BUNDLE_ID || "development"}/`;
 var DEFAULT_SSG_ROOT = "site";
 function getSsgAppRelativePath(staticSiteGenerator) {
   return staticSiteGenerator?.outputDir || DEFAULT_SSG_ROOT;
 }
 function getMrtArtifactUrl(basePath, ssgRoot, artifactPath = "") {
-  return import_path.default.join(basePath, MRT_BASE_URL, ssgRoot, artifactPath);
+  return (0, import_fs.joinUrlPath)(basePath, MRT_BASE_URL, ssgRoot, artifactPath);
 }
 function getMrtSsgRoot(staticSiteGenerator) {
   return import_path.default.join(getSsgAppRelativePath(staticSiteGenerator));

package/build/cjs/urls.cjs

@@ -37,9 +37,9 @@ __export(exports, {
   toHostname: () => toHostname
 });
 var import_path_to_regexp = __toModule(require("path-to-regexp"));
-var import_path = __toModule(require("path"));
 var import_os = __toModule(require("os"));
 var import_url = __toModule(require("url"));
+var import_fs = __toModule(require("./fs.cjs"));
 var CONFIG_SUFFIX = "/config.js";
 var SIGNATURE_SIGIL = "s";
 function getClientBootstrapConfigurationUri(routeInfo, runtimeEnvironment, runtimeParams, signature) {
@@ -114,9 +114,9 @@ function getViewUri(routePath, basePath, locale, i18n) {
   }
   let url = basePath;
   if (i18n.uriPattern === "path-prefix" && locale !== i18n.defaultLocale) {
-    url = import_path.default.join(url, `/${locale}`);
+    url = (0, import_fs.joinUrlPath)(url, `/${locale}`);
   }
-  url = import_path.default.join(url, routePath);
+  url = (0, import_fs.joinUrlPath)(url, routePath);
   return url;
 }
 function isURL(uri) {
@@ -134,6 +134,9 @@ function sortedQueryParamString(query) {
   return "?" + sortedKeys.map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(query[key])}`).join("&");
 }
 function crossEnvFileURL(url) {
+  if (typeof __filename !== "undefined") {
+    return url;
+  }
   if (import_os.default.platform() === "win32" && !url.startsWith("@")) {
     return (0, import_url.pathToFileURL)(url).href;
   }

package/build/es/fs.d.ts

@@ -49,6 +49,44 @@ export declare function normalizeToFileUrl(filePath: string, rootDir: string): s
 export declare function normalizeFromFileURL(fileURL: string | undefined, basePath: string): string | null;
 export declare function isLocalPath(filePath: string): boolean;
 export declare function normalizeResourcePath(rawPath: string, { rootDir, assets, contentDir, layoutsDir }: ResourcePaths, allowUnresolvedAlias?: boolean): string;
+/**
+ * Normalize a filesystem path for use in URIs, specifiers, and cache keys
+ * by converting backslashes (`\`) and URL-encoded backslashes (`%5C`) to
+ * forward slashes.
+ *
+ * On macOS/Linux this is a no-op. Node's `path` APIs never produce backslashes.
+ * On Windows, `path.join()` and `path.normalize()` return backslashes, which
+ * break URI routing, `startsWith()` comparisons, and cache-key matching.
+ * Additionally, when a backslash path passes through `encodeURI()` or similar
+ * encoding (e.g. in asset transform plugins), `\` becomes `%5C`. This function
+ * normalizes both forms.
+ *
+ * Wrap any `path.join()` / `path.normalize()` result with this function
+ * whenever the output is used as a URI, specifier, or map key.
+ *
+ * @example
+ * toForwardSlash(path.join(basePath, uri));   // '/base/path/asset.png'
+ * toForwardSlash(path.normalize(assetPath));  // '/app/src/assets/img.png'
+ * toForwardSlash('/public%5Cassets%5Cimg.png'); // '/public/assets/img.png'
+ */
+export declare function toForwardSlash(p: string): string;
+/**
+ * Join URL path segments using string concatenation instead of
+ * path.join(), which is a filesystem API and produces backslashes
+ * on Windows.
+ *
+ * Empty segments are filtered out. Each remaining segment is passed
+ * through toForwardSlash() to normalize backslashes. Trailing slashes
+ * are stripped from all segments except the last, and a leading slash
+ * is ensured between each pair.
+ *
+ * @example
+ * joinUrlPath('/base', '/assets/img.png')             // '/base/assets/img.png'
+ * joinUrlPath('/base/', 'assets', 'img.png')           // '/base/assets/img.png'
+ * joinUrlPath(basePath, MRT_BASE_URL, ssgRoot, '')     // '/bp/mrt/root'
+ * joinUrlPath(basePath, MRT_BASE_URL, ssgRoot, path)   // '/bp/mrt/root/path'
+ */
+export declare function joinUrlPath(...segments: string[]): string;
 export { lookup as mimeLookup };
 /**
  * Tries to convert any URL or $aliased path into a canonical fs path

package/build/es/fs.js

@@ -190,6 +190,58 @@ export function normalizeResourcePath(rawPath, { rootDir, assets, contentDir, la
         return alias;
     });
 }
+/**
+ * Normalize a filesystem path for use in URIs, specifiers, and cache keys
+ * by converting backslashes (`\`) and URL-encoded backslashes (`%5C`) to
+ * forward slashes.
+ *
+ * On macOS/Linux this is a no-op. Node's `path` APIs never produce backslashes.
+ * On Windows, `path.join()` and `path.normalize()` return backslashes, which
+ * break URI routing, `startsWith()` comparisons, and cache-key matching.
+ * Additionally, when a backslash path passes through `encodeURI()` or similar
+ * encoding (e.g. in asset transform plugins), `\` becomes `%5C`. This function
+ * normalizes both forms.
+ *
+ * Wrap any `path.join()` / `path.normalize()` result with this function
+ * whenever the output is used as a URI, specifier, or map key.
+ *
+ * @example
+ * toForwardSlash(path.join(basePath, uri));   // '/base/path/asset.png'
+ * toForwardSlash(path.normalize(assetPath));  // '/app/src/assets/img.png'
+ * toForwardSlash('/public%5Cassets%5Cimg.png'); // '/public/assets/img.png'
+ */
+export function toForwardSlash(p) {
+    return p.replace(/\\/g, '/').replace(/%5C/gi, '/');
+}
+/**
+ * Join URL path segments using string concatenation instead of
+ * path.join(), which is a filesystem API and produces backslashes
+ * on Windows.
+ *
+ * Empty segments are filtered out. Each remaining segment is passed
+ * through toForwardSlash() to normalize backslashes. Trailing slashes
+ * are stripped from all segments except the last, and a leading slash
+ * is ensured between each pair.
+ *
+ * @example
+ * joinUrlPath('/base', '/assets/img.png')             // '/base/assets/img.png'
+ * joinUrlPath('/base/', 'assets', 'img.png')           // '/base/assets/img.png'
+ * joinUrlPath(basePath, MRT_BASE_URL, ssgRoot, '')     // '/bp/mrt/root'
+ * joinUrlPath(basePath, MRT_BASE_URL, ssgRoot, path)   // '/bp/mrt/root/path'
+ */
+export function joinUrlPath(...segments) {
+    const parts = segments.filter((s) => s !== '');
+    return parts
+        .map((seg, i) => {
+        let s = toForwardSlash(seg);
+        if (i > 0 && !s.startsWith('/'))
+            s = `/${s}`;
+        if (i < parts.length - 1)
+            s = s.replace(/\/$/, '');
+        return s;
+    })
+        .join('');
+}
 export { lookup as mimeLookup };
 function logMetrics(filePath) {
     if (logger.isDebugEnabled()) {
@@ -212,11 +264,11 @@ export function normalizeAssetSpecifier(assetId, assetPathMap, resourcePaths, ba
         if (!importer) {
             throw Error(`Unable to resolve relative import "${specifier}" without an importer.`);
         }
-        return pathLib.join(pathLib.dirname(importer), specifier);
+        return toForwardSlash(pathLib.join(pathLib.dirname(importer), specifier));
     }
     if (type === 'content-asset') {
         const originSpecifier = !basePath ? specifier : specifier.split(basePath)[1];
-        return pathLib.join(resourcePaths.contentDir, originSpecifier);
+        return toForwardSlash(pathLib.join(resourcePaths.contentDir, originSpecifier));
     }
     if (specifier[0] === '$') {
         // This is a fs path containing an asset alias

package/build/es/mrt-utils.js

@@ -1,4 +1,5 @@
 import path from 'path';
+import { joinUrlPath } from './fs.js';
 // MRT has a specific URL to fetch associated artifacts from the deployed MRT bundle
 const MRT_BASE_URL = `/mobify/bundle/${process.env.BUNDLE_ID || 'development'}/`;
 // Default generated site root if not set in the config
@@ -10,7 +11,7 @@ export function getSsgAppRelativePath(staticSiteGenerator) {
  * Get the URL for a artifact given the configured SSG root and the path to the artifact
  */
 export function getMrtArtifactUrl(basePath, ssgRoot, artifactPath = '') {
-    return path.join(basePath, MRT_BASE_URL, ssgRoot, artifactPath);
+    return joinUrlPath(basePath, MRT_BASE_URL, ssgRoot, artifactPath);
 }
 /**
  * Get the root directory of the static config in the mrt lambda

package/build/es/urls.d.ts

@@ -37,6 +37,36 @@ export declare function getViewUri(routePath: string, basePath: string, locale:
  * Returns true is the URI starts with http:// or https://
  */
 export declare function isURL(uri: string): boolean;
+/**
+ * Convert a filesystem path to a URL suitable for dynamic module loading.
+ *
+ * On Windows, Node.js ESM `import()` requires `file://` URLs for absolute paths
+ * (raw `C:\...` paths are rejected by the ESM loader). This function wraps the
+ * path with `pathToFileURL()` on Windows so that `import(crossEnvFileURL(path))`
+ * works cross-platform.
+ *
+ * **CJS compatibility:** The CJS build (`build/cjs/`) is generated by esbuild
+ * with `format: 'cjs'` (see `scripts/build-cjs.mjs`), which transpiles
+ * `import()` to `require()`. Since `require()` does NOT accept `file://` URLs,
+ * we detect the CJS context at runtime and return the raw path unchanged.
+ *
+ * Detection mechanism: In Node.js, CJS modules always have `__filename` defined
+ * as a module-scoped variable. ESM modules do not. We use `typeof __filename`
+ * to distinguish the two contexts.
+ *
+ * **Edge cases that could break this:**
+ * - If esbuild's ESM output is generated with `platform: 'node'`, esbuild
+ *   injects a `__filename` shim (`const __filename = fileURLToPath(import.meta.url)`),
+ *   which would make this check return `true` in ESM and skip the `file://`
+ *   wrapping. The current LWR build uses `tsc -b` for ESM output, so this
+ *   does not apply. If the ESM build pipeline changes to esbuild with
+ *   `platform: 'node'`, this check must be revisited.
+ * - If a bundler polyfills `__filename` in ESM context for compatibility,
+ *   the same false-positive would occur.
+ *
+ * @param url - An absolute filesystem path or bare specifier (e.g. `@lwrjs/...`)
+ * @returns The path as-is (CJS or non-Windows), or a `file://` URL (ESM on Windows)
+ */
 export declare function crossEnvFileURL(url: string): string;
 export declare function toHostname(url: string): string;
 //# sourceMappingURL=urls.d.ts.map

package/build/es/urls.js

@@ -1,7 +1,7 @@
 import { pathToRegexp } from 'path-to-regexp';
-import path from 'path';
 import os from 'os';
 import { pathToFileURL } from 'url';
+import { joinUrlPath } from './fs.js';
 const CONFIG_SUFFIX = '/config.js';
 const SIGNATURE_SIGIL = 's';
 export function getClientBootstrapConfigurationUri(routeInfo, runtimeEnvironment, runtimeParams, signature) {
@@ -105,9 +105,9 @@ export function getViewUri(routePath, basePath, locale, i18n) {
     }
     let url = basePath;
     if (i18n.uriPattern === 'path-prefix' && locale !== i18n.defaultLocale) {
-        url = path.join(url, `/${locale}`);
+        url = joinUrlPath(url, `/${locale}`);
     }
-    url = path.join(url, routePath);
+    url = joinUrlPath(url, routePath);
     return url;
 }
 /**
@@ -130,10 +130,45 @@ function sortedQueryParamString(query) {
             .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(query[key])}`)
             .join('&'));
 }
-// Only URLs with a scheme in: file, data, and node are supported by the default ESM loader
-// On Windows, absolute paths must be valid file:// URLs.
-// Without this code for windows, dynamic imports will fail
+/**
+ * Convert a filesystem path to a URL suitable for dynamic module loading.
+ *
+ * On Windows, Node.js ESM `import()` requires `file://` URLs for absolute paths
+ * (raw `C:\...` paths are rejected by the ESM loader). This function wraps the
+ * path with `pathToFileURL()` on Windows so that `import(crossEnvFileURL(path))`
+ * works cross-platform.
+ *
+ * **CJS compatibility:** The CJS build (`build/cjs/`) is generated by esbuild
+ * with `format: 'cjs'` (see `scripts/build-cjs.mjs`), which transpiles
+ * `import()` to `require()`. Since `require()` does NOT accept `file://` URLs,
+ * we detect the CJS context at runtime and return the raw path unchanged.
+ *
+ * Detection mechanism: In Node.js, CJS modules always have `__filename` defined
+ * as a module-scoped variable. ESM modules do not. We use `typeof __filename`
+ * to distinguish the two contexts.
+ *
+ * **Edge cases that could break this:**
+ * - If esbuild's ESM output is generated with `platform: 'node'`, esbuild
+ *   injects a `__filename` shim (`const __filename = fileURLToPath(import.meta.url)`),
+ *   which would make this check return `true` in ESM and skip the `file://`
+ *   wrapping. The current LWR build uses `tsc -b` for ESM output, so this
+ *   does not apply. If the ESM build pipeline changes to esbuild with
+ *   `platform: 'node'`, this check must be revisited.
+ * - If a bundler polyfills `__filename` in ESM context for compatibility,
+ *   the same false-positive would occur.
+ *
+ * @param url - An absolute filesystem path or bare specifier (e.g. `@lwrjs/...`)
+ * @returns The path as-is (CJS or non-Windows), or a `file://` URL (ESM on Windows)
+ */
 export function crossEnvFileURL(url) {
+    // In CJS context, esbuild transpiled import() to require().
+    // require() needs raw filesystem paths, not file:// URLs.
+    if (typeof __filename !== 'undefined') {
+        return url;
+    }
+    // ESM import() on Windows requires file:// URLs for absolute paths.
+    // Raw paths like C:\app\module.js are not valid URL specifiers.
+    // Bare specifiers (e.g. @lwrjs/...) are excluded. They resolve via node_modules.
     if (os.platform() === 'win32' && !url.startsWith('@')) {
         return pathToFileURL(url).href;
     }

package/package.json

@@ -4,7 +4,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "0.21.7",
+    "version": "0.22.1",
     "homepage": "https://developer.salesforce.com/docs/platform/lwr/overview",
     "repository": {
         "type": "git",
@@ -37,7 +37,7 @@
         "build/**/*.d.ts"
     ],
     "dependencies": {
-        "@lwrjs/diagnostics": "0.21.7",
+        "@lwrjs/diagnostics": "0.22.1",
         "es-module-lexer": "^1.5.4",
         "fast-json-stable-stringify": "^2.1.0",
         "magic-string": "^0.30.9",
@@ -50,13 +50,13 @@
         "slugify": "^1.4.5"
     },
     "devDependencies": {
-        "@lwrjs/types": "0.21.7",
+        "@lwrjs/types": "0.22.1",
         "@types/mime-types": "2.1.4",
         "@types/path-to-regexp": "^1.7.0",
         "memfs": "^4.13.0"
     },
     "engines": {
-        "node": ">=20.0.0"
+        "node": ">=22.0.0"
     },
-    "gitHead": "685ec1660fd33420c61437bb3fcd37021036db12"
+    "gitHead": "29d44fb69ae394a4191c6a81024a8a81f2125556"
 }