@salesforce/storefront-next-dev 0.2.0 → 0.3.0-alpha.0

package/dist/react-router/Scripts.d.ts

@@ -4,7 +4,7 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
 //#region src/react-router/Scripts.d.ts
 
 /**
- * Enhanced Scripts component that wraps React Router's Scripts component with Odyssey-specific functionality.
+ * Enhanced Scripts component that wraps React Router's Scripts component with Storefront Next-specific functionality.
  *
  * This component extends the standard React Router Scripts component by injecting additional
  * bundle configuration scripts during server-side rendering. It ensures that bundle metadata

package/dist/react-router/Scripts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scripts.d.ts","names":[],"sources":["../../src/react-router/Scripts.tsx"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoFgB,OAAA,QAAe,KAAA,CAAM,sBAAsB,aAAmB,kBAAA,CAAA,GAAA,CAAA"}
+{"version":3,"file":"Scripts.d.ts","names":[],"sources":["../../src/react-router/Scripts.tsx"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuFgB,OAAA,QAAe,KAAA,CAAM,sBAAsB,aAAmB,kBAAA,CAAA,GAAA,CAAA"}

package/dist/react-router/Scripts.js

@@ -1,6 +1,40 @@
 import { Scripts as Scripts$1 } from "react-router";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
+//#region src/utils/paths.ts
+/**
+* Get the configurable base path for the application.
+* Reads from MRT_ENV_BASE_PATH environment variable.
+*
+* The base path is used for CDN routing to the correct MRT environment.
+* It is prepended to all URLs: page routes, /mobify/bundle/ assets, and /mobify/proxy/api.
+*
+* Validation rules:
+* - Must be a single path segment starting with '/'
+* - Max 63 characters after the leading slash
+* - Only URL-safe characters allowed
+* - Returns empty string if not set
+*
+* @returns The sanitized base path (e.g., '/site-a' or '')
+*
+* @example
+* // No base path configured
+* getBasePath() // → ''
+*
+* // With base path '/storefront'
+* getBasePath() // → '/storefront'
+*
+* // Automatically sanitizes
+* // MRT_ENV_BASE_PATH='storefront/' → '/storefront'
+*/
+function getBasePath() {
+	const basePath = process.env.MRT_ENV_BASE_PATH?.trim();
+	if (!basePath) return "";
+	if (!/^\/[a-zA-Z0-9_.+$~"'@:-]{1,63}$/.test(basePath)) throw new Error(`Invalid base path: "${basePath}". Base path must be a single segment starting with '/' (e.g., '/site-a'), contain only URL-safe characters, and be at most 63 characters after the leading slash.`);
+	return basePath;
+}
+
+//#endregion
 //#region src/react-router/Scripts.tsx
 /**
 * Determines if the code is running in a server-side rendering (SSR) environment.
@@ -23,17 +57,19 @@ const isSSR = typeof window === "undefined";
 const InternalServerScripts = () => {
 	if (!isSSR) return null;
 	const bundleId = process.env.BUNDLE_ID || "local";
-	const bundlePath = `/mobify/bundle/${bundleId}/client/`;
+	const basePath = getBasePath();
+	const bundlePath = `${basePath}/mobify/bundle/${bundleId}/client/`;
 	return /* @__PURE__ */ jsx("script", {
 		id: "sf-next-bundle-config",
 		dangerouslySetInnerHTML: { __html: `
         window._BUNDLE_ID = ${JSON.stringify(bundleId)};
         window._BUNDLE_PATH = ${JSON.stringify(bundlePath)};
+        window._BASE_PATH = ${JSON.stringify(basePath)};
     ` }
 	});
 };
 /**
-* Enhanced Scripts component that wraps React Router's Scripts component with Odyssey-specific functionality.
+* Enhanced Scripts component that wraps React Router's Scripts component with Storefront Next-specific functionality.
 *
 * This component extends the standard React Router Scripts component by injecting additional
 * bundle configuration scripts during server-side rendering. It ensures that bundle metadata

package/dist/react-router/Scripts.js.map

@@ -1 +1 @@
-{"version":3,"file":"Scripts.js","names":["ReactRouterScripts"],"sources":["../../src/react-router/Scripts.tsx"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { Scripts as ReactRouterScripts } from 'react-router';\n\n/**\n * Determines if the code is running in a server-side rendering (SSR) environment.\n * Returns true when window is undefined (server), false otherwise (client).\n */\nconst isSSR = typeof window === 'undefined';\n\n/**\n * Internal component that injects bundle configuration scripts during server-side rendering.\n *\n * This component renders a script tag that sets up global bundle variables on the window object,\n * which are used by the client-side application to locate and load the correct bundle assets.\n *\n * The script defines:\n * - `window._BUNDLE_ID`: The unique identifier for the current bundle (from BUNDLE_ID env var, defaults to 'local')\n * - `window._BUNDLE_PATH`: The path to the client bundle assets (e.g., `/mobify/bundle/{bundleId}/client/`)\n *\n * @returns A script element during SSR, or null during client-side rendering\n * @internal\n */\nconst InternalServerScripts = () => {\n    if (!isSSR) {\n        return null;\n    }\n\n    const bundleId = process.env.BUNDLE_ID || 'local';\n    const bundlePath = `/mobify/bundle/${bundleId}/client/`;\n    return (\n        <script\n            id=\"sf-next-bundle-config\"\n            // eslint-disable-next-line react/no-danger\n            dangerouslySetInnerHTML={{\n                __html: `\n        window._BUNDLE_ID = ${JSON.stringify(bundleId)};\n        window._BUNDLE_PATH = ${JSON.stringify(bundlePath)};\n    `,\n            }}\n        />\n    );\n};\n\n/**\n * Enhanced Scripts component that wraps React Router's Scripts component with Odyssey-specific functionality.\n *\n * This component extends the standard React Router Scripts component by injecting additional\n * bundle configuration scripts during server-side rendering. It ensures that bundle metadata\n * (ID and path) are available on the client before any other scripts execute.\n *\n * Usage:\n * ```tsx\n * import { Outlet, Scripts } from 'react-router';\n *\n * export default function Root() {\n *   return (\n *     <html>\n *       <head>...</head>\n *       <body>\n *         <Outlet />\n *         <Scripts />\n *       </body>\n *     </html>\n *   );\n * }\n * ```\n *\n * @param props - Props passed through to the underlying React Router Scripts component\n * @returns A fragment containing internal bundle scripts and React Router scripts\n */\nexport function Scripts(props: React.ComponentProps<typeof ReactRouterScripts>) {\n    return (\n        <>\n            <InternalServerScripts />\n            <ReactRouterScripts {...props} />\n        </>\n    );\n}\n"],"mappings":";;;;;;;;AAqBA,MAAM,QAAQ,OAAO,WAAW;;;;;;;;;;;;;;AAehC,MAAM,8BAA8B;AAChC,KAAI,CAAC,MACD,QAAO;CAGX,MAAM,WAAW,QAAQ,IAAI,aAAa;CAC1C,MAAM,aAAa,kBAAkB,SAAS;AAC9C,QACI,oBAAC;EACG,IAAG;EAEH,yBAAyB,EACrB,QAAQ;8BACM,KAAK,UAAU,SAAS,CAAC;gCACvB,KAAK,UAAU,WAAW,CAAC;OAE9C;GACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BV,SAAgB,QAAQ,OAAwD;AAC5E,QACI,4CACI,oBAAC,0BAAwB,EACzB,oBAACA,aAAmB,GAAI,QAAS,IAClC"}
+{"version":3,"file":"Scripts.js","names":["ReactRouterScripts"],"sources":["../../src/utils/paths.ts","../../src/react-router/Scripts.tsx"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n/**\n * Normalize a file path to use forward slashes.\n * On Windows, Node APIs return backslash-separated paths, but ESM import\n * specifiers and Vite module IDs require forward slashes.\n */\nexport function toPosixPath(filePath: string): string {\n    return filePath.replace(/\\\\/g, '/');\n}\n\n/**\n * Get the Commerce Cloud API URL from a short code\n */\nexport function getCommerceCloudApiUrl(shortCode: string, proxyHost?: string): string {\n    return proxyHost || `https://${shortCode}.api.commercecloud.salesforce.com`;\n}\n\n/**\n * Get the configurable base path for the application.\n * Reads from MRT_ENV_BASE_PATH environment variable.\n *\n * The base path is used for CDN routing to the correct MRT environment.\n * It is prepended to all URLs: page routes, /mobify/bundle/ assets, and /mobify/proxy/api.\n *\n * Validation rules:\n * - Must be a single path segment starting with '/'\n * - Max 63 characters after the leading slash\n * - Only URL-safe characters allowed\n * - Returns empty string if not set\n *\n * @returns The sanitized base path (e.g., '/site-a' or '')\n *\n * @example\n * // No base path configured\n * getBasePath() // → ''\n *\n * // With base path '/storefront'\n * getBasePath() // → '/storefront'\n *\n * // Automatically sanitizes\n * // MRT_ENV_BASE_PATH='storefront/' → '/storefront'\n */\nexport function getBasePath(): string {\n    const basePath = process.env.MRT_ENV_BASE_PATH?.trim();\n\n    // Return empty string if not set or empty\n    if (!basePath) {\n        return '';\n    }\n\n    // Base path prefix must be a single path segment starting with '/', max 63 chars,\n    // using only URL-safe characters (alphanumeric, hyphens, underscores, dots, and other safe symbols)\n    // This aligns with the regex used by MRT\n    if (!/^\\/[a-zA-Z0-9_.+$~\"'@:-]{1,63}$/.test(basePath)) {\n        throw new Error(\n            `Invalid base path: \"${basePath}\". ` +\n                \"Base path must be a single segment starting with '/' (e.g., '/site-a'), \" +\n                'contain only URL-safe characters, and be at most 63 characters after the leading slash.'\n        );\n    }\n\n    return basePath;\n}\n\n/**\n * Get the bundle path for static assets\n */\nexport function getBundlePath(bundleId: string): string {\n    const basePath = getBasePath();\n    return `${basePath}/mobify/bundle/${bundleId}/client/`;\n}\n","/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { Scripts as ReactRouterScripts } from 'react-router';\nimport { getBasePath } from '../utils/paths';\n\n/**\n * Determines if the code is running in a server-side rendering (SSR) environment.\n * Returns true when window is undefined (server), false otherwise (client).\n */\nconst isSSR = typeof window === 'undefined';\n\n/**\n * Internal component that injects bundle configuration scripts during server-side rendering.\n *\n * This component renders a script tag that sets up global bundle variables on the window object,\n * which are used by the client-side application to locate and load the correct bundle assets.\n *\n * The script defines:\n * - `window._BUNDLE_ID`: The unique identifier for the current bundle (from BUNDLE_ID env var, defaults to 'local')\n * - `window._BUNDLE_PATH`: The path to the client bundle assets (e.g., `/mobify/bundle/{bundleId}/client/`)\n *\n * @returns A script element during SSR, or null during client-side rendering\n * @internal\n */\nconst InternalServerScripts = () => {\n    if (!isSSR) {\n        return null;\n    }\n\n    const bundleId = process.env.BUNDLE_ID || 'local';\n    const basePath = getBasePath();\n    const bundlePath = `${basePath}/mobify/bundle/${bundleId}/client/`;\n    return (\n        <script\n            id=\"sf-next-bundle-config\"\n            // eslint-disable-next-line react/no-danger\n            dangerouslySetInnerHTML={{\n                __html: `\n        window._BUNDLE_ID = ${JSON.stringify(bundleId)};\n        window._BUNDLE_PATH = ${JSON.stringify(bundlePath)};\n        window._BASE_PATH = ${JSON.stringify(basePath)};\n    `,\n            }}\n        />\n    );\n};\n\n/**\n * Enhanced Scripts component that wraps React Router's Scripts component with Storefront Next-specific functionality.\n *\n * This component extends the standard React Router Scripts component by injecting additional\n * bundle configuration scripts during server-side rendering. It ensures that bundle metadata\n * (ID and path) are available on the client before any other scripts execute.\n *\n * Usage:\n * ```tsx\n * import { Outlet, Scripts } from 'react-router';\n *\n * export default function Root() {\n *   return (\n *     <html>\n *       <head>...</head>\n *       <body>\n *         <Outlet />\n *         <Scripts />\n *       </body>\n *     </html>\n *   );\n * }\n * ```\n *\n * @param props - Props passed through to the underlying React Router Scripts component\n * @returns A fragment containing internal bundle scripts and React Router scripts\n */\nexport function Scripts(props: React.ComponentProps<typeof ReactRouterScripts>) {\n    return (\n        <>\n            <InternalServerScripts />\n            <ReactRouterScripts {...props} />\n        </>\n    );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,SAAgB,cAAsB;CAClC,MAAM,WAAW,QAAQ,IAAI,mBAAmB,MAAM;AAGtD,KAAI,CAAC,SACD,QAAO;AAMX,KAAI,CAAC,kCAAkC,KAAK,SAAS,CACjD,OAAM,IAAI,MACN,uBAAuB,SAAS,oKAGnC;AAGL,QAAO;;;;;;;;;ACrDX,MAAM,QAAQ,OAAO,WAAW;;;;;;;;;;;;;;AAehC,MAAM,8BAA8B;AAChC,KAAI,CAAC,MACD,QAAO;CAGX,MAAM,WAAW,QAAQ,IAAI,aAAa;CAC1C,MAAM,WAAW,aAAa;CAC9B,MAAM,aAAa,GAAG,SAAS,iBAAiB,SAAS;AACzD,QACI,oBAAC;EACG,IAAG;EAEH,yBAAyB,EACrB,QAAQ;8BACM,KAAK,UAAU,SAAS,CAAC;gCACvB,KAAK,UAAU,WAAW,CAAC;8BAC7B,KAAK,UAAU,SAAS,CAAC;OAE1C;GACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BV,SAAgB,QAAQ,OAAwD;AAC5E,QACI,4CACI,oBAAC,0BAAwB,EACzB,oBAACA,aAAmB,GAAI,QAAS,IAClC"}

package/dist/server.js

@@ -1,4 +1,5 @@
-import { c as warn, r as info } from "./logger.js";
+import { t as logger } from "./logger.js";
+import { o as loadRuntimeConfig } from "./config.js";
 import path from "path";
 import chalk from "chalk";
 import express from "express";
@@ -11,6 +12,14 @@ import compression from "compression";
 import zlib from "node:zlib";
 import morgan from "morgan";
 import { minimatch } from "minimatch";
+import { SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ConsoleSpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { ExportResultCode, hrTimeToTimeStamp } from "@opentelemetry/core";
+import { Resource } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
 
 //#region src/server/ts-import.ts
 /**
@@ -78,18 +87,15 @@ function loadConfigFromEnv() {
 	const shortCode = process.env.PUBLIC__app__commerce__api__shortCode;
 	const organizationId = process.env.PUBLIC__app__commerce__api__organizationId;
 	const clientId = process.env.PUBLIC__app__commerce__api__clientId;
-	const siteId = process.env.PUBLIC__app__commerce__api__siteId;
 	const proxy = process.env.PUBLIC__app__commerce__api__proxy || "/mobify/proxy/api";
 	const proxyHost = process.env.SCAPI_PROXY_HOST;
 	if (!shortCode && !proxyHost) throw new Error("Missing PUBLIC__app__commerce__api__shortCode environment variable.\nPlease set it in your .env file or environment.");
 	if (!organizationId) throw new Error("Missing PUBLIC__app__commerce__api__organizationId environment variable.\nPlease set it in your .env file or environment.");
 	if (!clientId) throw new Error("Missing PUBLIC__app__commerce__api__clientId environment variable.\nPlease set it in your .env file or environment.");
-	if (!siteId) throw new Error("Missing PUBLIC__app__commerce__api__siteId environment variable.\nPlease set it in your .env file or environment.");
 	return { commerce: { api: {
 		shortCode: shortCode || "",
 		organizationId,
 		clientId,
-		siteId,
 		proxy,
 		proxyHost
 	} } };
@@ -115,12 +121,10 @@ async function loadProjectConfig(projectDirectory) {
 	if (!api.shortCode && !proxyHost) throw new Error("Missing shortCode in config.server.ts commerce.api configuration");
 	if (!api.organizationId) throw new Error("Missing organizationId in config.server.ts commerce.api configuration");
 	if (!api.clientId) throw new Error("Missing clientId in config.server.ts commerce.api configuration");
-	if (!api.siteId) throw new Error("Missing siteId in config.server.ts commerce.api configuration");
 	return { commerce: { api: {
 		shortCode: api.shortCode || "",
 		organizationId: api.organizationId,
 		clientId: api.clientId,
-		siteId: api.siteId,
 		proxy: api.proxy || "/mobify/proxy/api",
 		proxyHost
 	} } };
@@ -135,10 +139,41 @@ function getCommerceCloudApiUrl(shortCode, proxyHost) {
 	return proxyHost || `https://${shortCode}.api.commercecloud.salesforce.com`;
 }
 /**
+* Get the configurable base path for the application.
+* Reads from MRT_ENV_BASE_PATH environment variable.
+*
+* The base path is used for CDN routing to the correct MRT environment.
+* It is prepended to all URLs: page routes, /mobify/bundle/ assets, and /mobify/proxy/api.
+*
+* Validation rules:
+* - Must be a single path segment starting with '/'
+* - Max 63 characters after the leading slash
+* - Only URL-safe characters allowed
+* - Returns empty string if not set
+*
+* @returns The sanitized base path (e.g., '/site-a' or '')
+*
+* @example
+* // No base path configured
+* getBasePath() // → ''
+*
+* // With base path '/storefront'
+* getBasePath() // → '/storefront'
+*
+* // Automatically sanitizes
+* // MRT_ENV_BASE_PATH='storefront/' → '/storefront'
+*/
+function getBasePath() {
+	const basePath = process.env.MRT_ENV_BASE_PATH?.trim();
+	if (!basePath) return "";
+	if (!/^\/[a-zA-Z0-9_.+$~"'@:-]{1,63}$/.test(basePath)) throw new Error(`Invalid base path: "${basePath}". Base path must be a single segment starting with '/' (e.g., '/site-a'), contain only URL-safe characters, and be at most 63 characters after the leading slash.`);
+	return basePath;
+}
+/**
 * Get the bundle path for static assets
 */
 function getBundlePath(bundleId) {
-	return `/mobify/bundle/${bundleId}/client/`;
+	return `${getBasePath()}/mobify/bundle/${bundleId}/client/`;
 }
 
 //#endregion
@@ -164,7 +199,7 @@ function createCommerceProxyMiddleware(config) {
 function createStaticMiddleware(bundleId, projectDirectory) {
 	const bundlePath = getBundlePath(bundleId);
 	const clientBuildDir = path.join(projectDirectory, "build", "client");
-	info(`Serving static assets from ${clientBuildDir} at ${bundlePath}`);
+	logger.info(`Serving static assets from ${clientBuildDir} at ${bundlePath}`);
 	return express.static(clientBuildDir, { setHeaders: (res) => {
 		res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
 		res.setHeader("x-local-static-cache-control", "1");
@@ -183,7 +218,7 @@ function getCompressionLevel() {
 	if (raw == null || raw.trim() === "") return DEFAULT;
 	const level = Number(raw);
 	if (!(Number.isInteger(level) && level >= 0 && level <= 9)) {
-		warn(`[compression] Invalid COMPRESSION_LEVEL="${raw}". Using default (${DEFAULT}).`);
+		logger.warn(`[compression] Invalid COMPRESSION_LEVEL="${raw}". Using default (${DEFAULT}).`);
 		return DEFAULT;
 	}
 	return level;
@@ -247,9 +282,7 @@ function createLoggingMiddleware() {
 	});
 	return morgan((tokens, req, res) => {
 		return [
-			chalk.gray("["),
 			tokens["method-colored"](req, res),
-			chalk.gray("]"),
 			tokens.url(req, res),
 			"-",
 			tokens["status-colored"](req, res),
@@ -301,11 +334,13 @@ function createHostHeaderMiddleware() {
 */
 function patchReactRouterBuild(build, bundleId) {
 	const bundlePath = getBundlePath(bundleId);
+	const basePath = getBasePath();
 	const patchedAssetsJson = JSON.stringify(build.assets).replace(/"\/assets\//g, `"${bundlePath}assets/`);
 	const newAssets = JSON.parse(patchedAssetsJson);
 	return Object.assign({}, build, {
 		publicPath: bundlePath,
-		assets: newAssets
+		assets: newAssets,
+		...basePath && { basename: basePath }
 	});
 }
 
@@ -338,6 +373,225 @@ const ServerModeFeatureMap = {
 	}
 };
 
+//#endregion
+//#region src/otel/mrt-console-span-exporter.ts
+var MrtConsoleSpanExporter = class extends ConsoleSpanExporter {
+	export(spans, resultCallback) {
+		for (const span of spans) try {
+			const ctx = span.spanContext();
+			const spanData = {
+				traceId: ctx.traceId,
+				parentId: span.parentSpanId,
+				name: span.name,
+				id: ctx.spanId,
+				kind: span.kind,
+				timestamp: hrTimeToTimeStamp(span.startTime),
+				duration: span.duration,
+				attributes: span.attributes,
+				status: span.status,
+				events: span.events,
+				links: span.links,
+				start_time: span.startTime,
+				end_time: span.endTime,
+				forwardTrace: process.env.SFNEXT_OTEL_ENABLED === "true"
+			};
+			console.info(JSON.stringify(spanData));
+		} catch {}
+		resultCallback({ code: ExportResultCode.SUCCESS });
+	}
+};
+
+//#endregion
+//#region src/otel/setup.ts
+const SERVICE_NAME = "storefront-next";
+/**
+* Initializes OpenTelemetry and returns a Tracer from the provider directly.
+*
+* Returns the tracer via `provider.getTracer()` instead of the global
+* `trace.getTracer()` API. In the Vite SSR module runner, the built
+* dist/entry/server.js and the externalized @opentelemetry/sdk-trace-node
+* resolve @opentelemetry/api to different module instances (different paths
+* through pnpm's strict node_modules). Each instance has its own
+* ProxyTracerProvider singleton, so `provider.register()` sets the delegate
+* on sdk-trace-node's API instance while our code's `trace.getTracer()`
+* reads from a separate API instance with no delegate — returning a tracer
+* backed by a bare BasicTracerProvider with NoopSpanProcessor.
+*
+* Getting the tracer directly from the provider bypasses the global registry
+* entirely, guaranteeing the tracer uses our configured span processors.
+*/
+let cachedTracer = null;
+const UNDICI_REGISTERED_KEY = Symbol.for("sfnext.otel.undici_registered");
+function initTelemetry() {
+	if (cachedTracer) return cachedTracer;
+	try {
+		const provider = new NodeTracerProvider({ resource: new Resource({ [ATTR_SERVICE_NAME]: SERVICE_NAME }) });
+		provider.addSpanProcessor(new SimpleSpanProcessor(new MrtConsoleSpanExporter()));
+		provider.register();
+		if (!globalThis[UNDICI_REGISTERED_KEY]) {
+			globalThis[UNDICI_REGISTERED_KEY] = true;
+			registerInstrumentations({
+				tracerProvider: provider,
+				instrumentations: [new UndiciInstrumentation({ requestHook(span, request) {
+					try {
+						const method = request.method.toUpperCase();
+						const url = `${request.origin}${request.path}`;
+						span.updateName(`${method} ${url}`);
+					} catch {}
+				} })]
+			});
+		}
+		cachedTracer = provider.getTracer(SERVICE_NAME);
+		return cachedTracer;
+	} catch (error) {
+		logger.error("[otel] Failed to initialize OpenTelemetry:", error);
+		return null;
+	}
+}
+
+//#endregion
+//#region src/otel/express/middleware.ts
+function createOtelExpressMiddleware() {
+	const maybeTracer = initTelemetry();
+	if (!maybeTracer) return (_req, _res, next) => next();
+	const tracer = maybeTracer;
+	return (req, res, next) => {
+		try {
+			const url = new URL(req.originalUrl || req.url, "http://localhost").pathname;
+			const method = req.method;
+			tracer.startActiveSpan(`[sfnext] server ${method} ${url}`, { attributes: {
+				"http.request.method": method,
+				"url.path": url
+			} }, (serverSpan) => {
+				try {
+					const spanContext = trace.getSpan(context.active())?.spanContext();
+					if (spanContext) {
+						const flags = spanContext.traceFlags.toString(16).padStart(2, "0");
+						const traceparent = `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`;
+						res.setHeader("traceparent", traceparent);
+					}
+				} catch {}
+				const serverCtx = context.active();
+				const startTime = performance.now();
+				let streamingSpan = null;
+				let ttfbMs = 0;
+				let ended = false;
+				function recordTTFB() {
+					if (streamingSpan) return;
+					try {
+						ttfbMs = Math.round(performance.now() - startTime);
+						serverSpan.setAttribute("sfnext.ttfb_ms", ttfbMs);
+						streamingSpan = tracer.startSpan(`[sfnext] response streaming ${method} ${url}`, { attributes: {
+							"http.request.method": method,
+							"url.path": url,
+							"sfnext.ttfb_ms": ttfbMs
+						} }, serverCtx);
+					} catch {}
+				}
+				const origWriteHead = res.writeHead.bind(res);
+				res.writeHead = ((...args) => {
+					recordTTFB();
+					return origWriteHead(...args);
+				});
+				const origWrite = res.write.bind(res);
+				res.write = ((...args) => {
+					recordTTFB();
+					return origWrite(...args);
+				});
+				function endSpans() {
+					if (ended) return;
+					ended = true;
+					try {
+						const totalMs = Math.round(performance.now() - startTime);
+						const statusCode = res.statusCode;
+						if (streamingSpan) {
+							streamingSpan.setAttribute("http.streaming_duration_ms", totalMs - ttfbMs);
+							streamingSpan.setAttribute("http.response.status_code", statusCode);
+							if (statusCode >= 500) streamingSpan.setStatus({ code: SpanStatusCode.ERROR });
+							streamingSpan.end();
+						}
+						serverSpan.setAttribute("http.response.status_code", statusCode);
+						serverSpan.setAttribute("http.total_duration_ms", totalMs);
+						if (statusCode >= 500) serverSpan.setStatus({ code: SpanStatusCode.ERROR });
+						serverSpan.end();
+					} catch {}
+				}
+				res.once("close", endSpans);
+				res.once("finish", endSpans);
+				next();
+			});
+		} catch {
+			next();
+		}
+	};
+}
+
+//#endregion
+//#region src/server/handlers/health-check.ts
+const DEFAULT_HEALTH_DESCRIPTION = "storefront-next-dev server health";
+const PACKAGE_JSON_NAME = "package.json";
+const RUNTIME_PACKAGE_NAME = "@salesforce/storefront-next-runtime";
+const DEV_PACKAGE_NAME = "@salesforce/storefront-next-dev";
+const BUILD_FOLDER_NAME = "build";
+const LOCAL_BUNDLE_ID = "local";
+const HEALTH_ENDPOINT_PATH = "/sfdc-health";
+/**
+* Reads a package.json file and returns selected metadata.
+*
+* @param path - Absolute path to a package.json file
+* @returns Parsed metadata, or null if missing/unreadable
+*
+* @example
+* ```ts
+* const metadata = readPackageMetadata('/app/package.json');
+* console.log(metadata?.version);
+* ```
+*/
+function readPackageMetadata(path$1) {
+	if (!existsSync(path$1)) return null;
+	try {
+		return JSON.parse(readFileSync(path$1, "utf8"));
+	} catch (error) {
+		logger.debug(`Health check: failed to parse package.json at ${path$1}`, error);
+		return null;
+	}
+}
+/**
+* Creates an Express handler that returns Health+JSON for the project.
+*
+* @param options - Handler options
+* @returns Express request handler for the health endpoint
+*
+* @example
+* ```ts
+* app.get(HEALTH_ENDPOINT_PATH, createHealthCheckHandler({
+*     projectDirectory: process.cwd(),
+*     bundleId: LOCAL_BUNDLE_ID,
+* }));
+* ```
+*/
+function createHealthCheckHandler(options) {
+	const { projectDirectory, bundleId } = options;
+	const projectPackage = readPackageMetadata(bundleId === LOCAL_BUNDLE_ID ? resolve(projectDirectory, PACKAGE_JSON_NAME) : resolve(projectDirectory, BUILD_FOLDER_NAME, PACKAGE_JSON_NAME));
+	const allDependencies = {
+		...projectPackage?.dependencies,
+		...projectPackage?.devDependencies
+	};
+	const devVersion = allDependencies?.[DEV_PACKAGE_NAME];
+	const runtimeVersion = allDependencies?.[RUNTIME_PACKAGE_NAME];
+	const notes = [devVersion ? `Built using ${DEV_PACKAGE_NAME}@${devVersion}.` : null, runtimeVersion ? `Running ${RUNTIME_PACKAGE_NAME}@${runtimeVersion}.` : null].filter(Boolean);
+	return (_req, res) => {
+		const healthResponse = {
+			status: "pass",
+			version: projectPackage?.version,
+			bundleId,
+			description: projectPackage?.description ?? DEFAULT_HEALTH_DESCRIPTION,
+			notes: notes.length > 0 ? notes : void 0
+		};
+		res.status(200).type("application/health+json").json(healthResponse);
+	};
+}
+
 //#endregion
 //#region src/server/index.ts
 /** Relative path to the middleware registry TypeScript source (development). Must match appDirectory + server dir + filename used by buildMiddlewareRegistry plugin. */
@@ -350,6 +604,20 @@ const MIDDLEWARE_REGISTRY_BUILT_EXTENSIONS = [
 ];
 /** All paths to try when loading the built middlewares (base + extension). */
 const RELATIVE_MIDDLEWARE_REGISTRY_BUILT_PATHS = ["bld/server/middleware-registry", "build/server/middleware-registry"].flatMap((base) => MIDDLEWARE_REGISTRY_BUILT_EXTENSIONS.map((ext) => `${base}${ext}`));
+const DEFAULT_BUNDLE_ID = "local";
+/**
+* Load MRT_ENV_BASE_PATH from config.server.ts so getBasePath() works in local dev/preview.
+* On MRT production, this env var is already set by the Lambda from ssrParameters.envBasePath.
+*
+* In dev mode this must be called before Vite starts, since the React Router preset
+* reads getBasePath() at config time to set the basename.
+*
+* @param projectDirectory - Project root directory
+*/
+async function initBasePathEnv(projectDirectory) {
+	const runtimeConfig = await loadRuntimeConfig(projectDirectory);
+	if (runtimeConfig?.ssrParameters?.envBasePath) process.env.MRT_ENV_BASE_PATH = String(runtimeConfig.ssrParameters.envBasePath);
+}
 /**
 * Create a unified Express server for development, preview, or production mode
 */
@@ -358,9 +626,14 @@ async function createServer(options) {
 	if (mode === "development" && !vite) throw new Error("Vite dev server instance is required for development mode");
 	if ((mode === "preview" || mode === "production") && !build) throw new Error("React Router server build is required for preview/production mode");
 	const config = providedConfig ?? loadConfigFromEnv();
-	const bundleId = process.env.BUNDLE_ID ?? "local";
+	const bundleId = process.env.BUNDLE_ID ?? DEFAULT_BUNDLE_ID;
 	const app = express();
 	app.disable("x-powered-by");
+	if (process.env.SFNEXT_OTEL_ENABLED === "true") app.use(createOtelExpressMiddleware());
+	app.get(HEALTH_ENDPOINT_PATH, createHealthCheckHandler({
+		projectDirectory,
+		bundleId
+	}));
 	if (enableLogging) app.use(createLoggingMiddleware());
 	if (enableCompression && !streaming) app.use(createCompressionMiddleware());
 	if (enableStaticServing && build) {
@@ -385,8 +658,14 @@ async function createServer(options) {
 	});
 	if (mode === "development" && vite) app.use(vite.middlewares);
 	if (enableProxy) app.use(config.commerce.api.proxy, createCommerceProxyMiddleware(config));
+	const basePath = getBasePath();
+	if (basePath) app.use((req, res, next) => {
+		if (req.path.startsWith(`${basePath}/`) || req.path === basePath) return next();
+		if (req.path.startsWith("/mobify/")) return next();
+		res.redirect(`${basePath}${req.originalUrl}`);
+	});
 	app.use(createHostHeaderMiddleware());
-	app.all("*", await createSSRHandler(mode, bundleId, vite, build, enableAssetUrlPatching));
+	app.all("*splat", await createSSRHandler(mode, bundleId, vite, build, enableAssetUrlPatching));
 	return app;
 }
 /**
@@ -414,12 +693,13 @@ async function createSSRHandler(mode, bundleId, vite, build, enableAssetUrlPatch
 	} else if (build) {
 		let patchedBuild = build;
 		if (enableAssetUrlPatching) patchedBuild = patchReactRouterBuild(build, bundleId);
+		const requestHandlerMode = process.env.NODE_OPTIONS?.includes("--enable-source-maps") ? "development" : process.env.NODE_ENV;
 		return createRequestHandler({
 			build: patchedBuild,
-			mode: process.env.NODE_ENV
+			mode: requestHandlerMode
 		});
 	} else throw new Error("Invalid server configuration: no vite or build provided");
 }
 
 //#endregion
-export { getCommerceCloudApiUrl as n, loadProjectConfig as r, createServer as t };
+export { loadProjectConfig as i, initBasePathEnv as n, getCommerceCloudApiUrl as r, createServer as t };

package/dist/utils.js

@@ -1,4 +1,4 @@
-import { c as warn, t as debug } from "./logger.js";
+import { t as logger } from "./logger.js";
 import { execSync } from "child_process";
 import os from "os";
 import path from "path";
@@ -25,7 +25,7 @@ const getProjectPkg = (projectDir) => {
 const loadEnvFile = (projectDir) => {
 	const envPath = path.join(projectDir, ".env");
 	if (fs.existsSync(envPath)) dotenv.config({ path: envPath });
-	else warn("No .env file found");
+	else logger.warn("No .env file found");
 };
 /**
 * Get MRT configuration with priority logic: .env -> package.json -> defaults
@@ -36,7 +36,7 @@ const getMrtConfig = (projectDir) => {
 	const defaultMrtProject = process.env.MRT_PROJECT ?? pkg.name;
 	if (!defaultMrtProject || defaultMrtProject.trim() === "") throw new Error("Project name couldn't be determined. Do one of these options:\n  1. Set MRT_PROJECT in your .env file, or\n  2. Ensure package.json has a valid \"name\" field.");
 	const defaultMrtTarget = process.env.MRT_TARGET ?? void 0;
-	debug("MRT configuration resolved", {
+	logger.debug("MRT configuration resolved", {
 		projectDir,
 		envMrtProject: process.env.MRT_PROJECT,
 		envMrtTarget: process.env.MRT_TARGET,
@@ -95,7 +95,7 @@ const getDefaultMessage = (projectDir) => {
 			cwd: projectDir
 		}).trim()}`;
 	} catch {
-		debug("Using default bundle message as no message was provided and not in a Git repo.");
+		logger.debug("Using default bundle message as no message was provided and not in a Git repo.");
 		return "PWA Kit Bundle";
 	}
 };

package/dist/validate-cartridge.js

@@ -0,0 +1,45 @@
+import path from "path";
+import { glob } from "glob";
+import { MetaDefinitionDetectionError, validateMetaDefinitionFile } from "@salesforce/b2c-tooling-sdk/operations/content";
+
+//#region src/cartridge-services/validate-cartridge.ts
+/**
+* Validate all Page Designer metadata JSON files in a directory.
+*
+* Globs for `**\/*.json` in `metadataDir`, validates each file against
+* the appropriate metadefinition schema, and returns a summary.
+*
+* Files whose schema type cannot be detected are skipped and reported
+* in `skippedFiles`.
+*/
+async function validateCartridgeMetadata(metadataDir) {
+	const filePaths = await glob("**/*.json", {
+		cwd: metadataDir,
+		absolute: true,
+		nodir: true
+	});
+	const results = [];
+	const skippedFiles = [];
+	for (const filePath of filePaths) try {
+		const result = validateMetaDefinitionFile(filePath);
+		results.push(result);
+	} catch (error) {
+		if (error instanceof MetaDefinitionDetectionError) {
+			skippedFiles.push(path.relative(metadataDir, filePath));
+			continue;
+		}
+		throw error;
+	}
+	const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+	const validFiles = results.filter((r) => r.valid).length;
+	return {
+		results,
+		totalFiles: results.length,
+		validFiles,
+		totalErrors,
+		skippedFiles
+	};
+}
+
+//#endregion
+export { validateCartridgeMetadata as t };