@W-19265242@ Configurable base paths for /mobify routes (PWA Kit 3.12 version) (#2892)

* Initial restore of base path PR

* Rename path functions

* Update commerce-sdk-react callbacks and slas private proxy endpoint

* Big update

* Replace getAppOrigin calls with useAppOrigin

* WIP - Filter the base path from all incoming requests to the server

* Remove base path from proxied requests + cleanup

* Use functions for proxy pathRewrite

* A bit of PR cleanup

* Lint cleanup

* More cleanup

* Fix tests

* Fix issues found by CI

* Lint for override asset

* Turn off slas private proxy

* Cleanup comments

* Update changelog entries

* Fix config

* Limit base path removal to /mobify or express route

* Adjust express filter

* Lint

* Fix dependency in generated apps

* Comment cleanup

* use envBasePath as a feature toggle for enabling the base path middleware

* Enable basepath removal middlware to handle express routes defined as regexes

* Apply suggestions

* Adjust app config template

* Use pathToRegexp rather than having manual regex interpretation

* escape the base path to not allow regex

* refactor

* Remove ?* from callback url

* Handle ? characters in express route

* Cache express regexes

* Handle properly formatted ()? express groups

* Comment cleanup

* Apply suggestions to reduce use of regex

* Add base path to social login redirectUri

* Lint

* Update comments and test

* Update test with more realistic scenario

* Remove path-to-regexp

* Refine convertExpressRouteToRegex further

* Move express route to regex logic to separate file

* Adjust logger and lock file

* Revert package-lock changes

---------

Signed-off-by: vcua-mobify <47404250+vcua-mobify@users.noreply.github.com>

Author: vcua-mobify

packages/commerce-sdk-react/CHANGELOG.md

@@ -1,5 +1,5 @@
 ## v3.5.0-dev (Jul 22, 2025)
-
+- Add support for environment level base paths on /mobify routes [#2892](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2892)
 - Update USID expiry to match SLAS refresh token expiry[#2854](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2854)
 
 - [Bugfix] Skip deleting dwsid on shopper login if hybrid auth is enabled for current site. [#3151](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3151)

packages/commerce-sdk-react/src/auth/index.ts

@@ -43,6 +43,7 @@ type Helpers = typeof helpers
 interface AuthConfig extends ApiClientConfigParams {
     redirectURI: string
     proxy: string
+    privateClientProxyEndpoint?: string
     fetchOptions?: ShopperLoginTypes.FetchOptions
     fetchedToken?: string
     enablePWAKitPrivateClient?: boolean
@@ -247,12 +248,19 @@ class Auth {
     private hybridAuthEnabled: boolean
 
     constructor(config: AuthConfig) {
-        // Special endpoint for injecting SLAS private client secret.
+        // Special proxy endpoint for injecting SLAS private client secret.
+        // We prioritize config.privateClientProxyEndpoint since that allows us to use the new envBasePath feature
+        // The preexisting hard coded privateClientEndpoint is kept here for now to prevent a breaking change.
+        // TODO: We should remove this in the next major release so we do not have a hard coded proxy path inside commerce-sdk-react
         const baseUrl = config.proxy.split(MOBIFY_PATH)[0]
         const privateClientEndpoint = `${baseUrl}${SLAS_PRIVATE_PROXY_PATH}`
 
         this.client = new ShopperLogin({
-            proxy: config.enablePWAKitPrivateClient ? privateClientEndpoint : config.proxy,
+            proxy: config.enablePWAKitPrivateClient
+                ? config.privateClientProxyEndpoint
+                    ? config.privateClientProxyEndpoint
+                    : privateClientEndpoint
+                : config.proxy,
             parameters: {
                 clientId: config.clientId,
                 organizationId: config.organizationId,
@@ -340,7 +348,9 @@ class Auth {
         this.passwordlessLoginCallbackURI = passwordlessLoginCallbackURI
             ? isAbsoluteUrl(passwordlessLoginCallbackURI)
                 ? passwordlessLoginCallbackURI
-                : `${baseUrl}${passwordlessLoginCallbackURI}`
+                : // This fallback does not take into account the envBasePath feature
+                  // To set an env base path, config.passwordlessLoginCallbackURI must be an absolute url
+                  `${baseUrl}${passwordlessLoginCallbackURI}`
             : ''
 
         this.hybridAuthEnabled = config.hybridAuthEnabled || false

packages/commerce-sdk-react/src/components/StorefrontPreview/utils.ts

@@ -25,6 +25,7 @@ export const detectStorefrontPreview = () => {
 export const getClientScript = () => {
     const parentOrigin = getParentOrigin() ?? 'https://runtime.commercecloud.com'
     return parentOrigin === DEVELOPMENT_ORIGIN
+        // TODO: This will need to be updated to support base paths with storefront preview
         ? `${parentOrigin}${LOCAL_BUNDLE_PATH}/static/storefront-preview.js`
         : `${parentOrigin}/cc/b2c/preview/preview.client.js`
 }

packages/commerce-sdk-react/src/constant.ts

@@ -14,10 +14,23 @@ export const IFRAME_HOST_ALLOW_LIST = Object.freeze([
     'https://runtime-admin-preview.mobify-storefront.com'
 ])
 
-// We hardcode these here since we don't want commerce-sdk-react to have a dependency on pwa-kit-runtime
+/* Deprecating the following path constants since, outside of storefront preview,
+ * the paths they are used for can be passed in via the provider. */
+/**
+ * @deprecated
+ */
 export const MOBIFY_PATH = '/mobify'
+/**
+ * @deprecated
+ */
 export const PROXY_PATH = `${MOBIFY_PATH}/proxy`
+/**
+ * @deprecated
+ */
 export const LOCAL_BUNDLE_PATH = `${MOBIFY_PATH}/bundle/development`
+/**
+ * @deprecated
+ */
 export const SLAS_PRIVATE_PROXY_PATH = `${MOBIFY_PATH}/slas/private`
 
 export const SLAS_SECRET_WARNING_MSG =

packages/commerce-sdk-react/src/provider.tsx

@@ -41,6 +41,7 @@ export interface CommerceApiProviderProps extends ApiClientConfigParams {
     headers?: Record<string, string>
     fetchedToken?: string
     enablePWAKitPrivateClient?: boolean
+    privateClientProxyEndpoint?: string
     clientSecret?: string
     silenceWarnings?: boolean
     logger?: Logger
@@ -138,6 +139,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         currency,
         fetchedToken,
         enablePWAKitPrivateClient,
+        privateClientProxyEndpoint,
         clientSecret,
         silenceWarnings,
         logger,
@@ -164,6 +166,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
             fetchOptions,
             fetchedToken,
             enablePWAKitPrivateClient,
+            privateClientProxyEndpoint,
             clientSecret,
             silenceWarnings,
             logger: configLogger,
@@ -183,6 +186,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         fetchOptions,
         fetchedToken,
         enablePWAKitPrivateClient,
+        privateClientProxyEndpoint,
         clientSecret,
         silenceWarnings,
         configLogger,
@@ -253,6 +257,11 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
             fetchOptions
         }
 
+        // Special proxy endpoint for injecting SLAS private client secret.
+        // This is only used by the ShopperLogin API as that is the only one that interacts with SLAS.
+        // We prioritize config.privateClientProxyEndpoint since that allows us to use the new envBasePath feature
+        // The preexisting hard coded privateClientEndpoint is kept here for now to prevent a breaking change.
+        // TODO: We should remove this in the next major release so we do not have a hard coded proxy path inside commerce-sdk-react
         const baseUrl = config.proxy.split(MOBIFY_PATH)[0]
         const privateClientEndpoint = `${baseUrl}${SLAS_PRIVATE_PROXY_PATH}`
 
@@ -264,7 +273,11 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
             shopperGiftCertificates: new ShopperGiftCertificates(config),
             shopperLogin: new ShopperLogin({
                 ...config,
-                proxy: enablePWAKitPrivateClient ? privateClientEndpoint : config.proxy
+                proxy: enablePWAKitPrivateClient
+                    ? privateClientProxyEndpoint
+                        ? privateClientProxyEndpoint
+                        : privateClientEndpoint
+                    : config.proxy
             }),
             shopperOrders: new ShopperOrders(config),
             shopperProducts: new ShopperProducts(config),

packages/pwa-kit-create-app/CHANGELOG.md

@@ -1,5 +1,8 @@
-## v3.12.0-dev (Jul 28, 2025)
+## v3.12.0-dev (Jul 22, 2025)
 - This feature introduces an AI-powered shopping assistant that integrates Salesforce Embedded Messaging Service with PWA Kit applications. The shopper agent provides real-time chat support, search assistance, and personalized shopping guidance directly within the e-commerce experience. [#2658](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2658)
+- Add support for environment level base paths on /mobify routes [#2892](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2892)
+- Add `--initGit` to automate git repo creation for the generated project [#2817](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2817)
+
 
 - Update _app-config generator template to include `hybridAuthEnabled` prop [#3151](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3151)
 

packages/pwa-kit-create-app/assets/bootstrap/js/config/default.js.hbs

@@ -123,6 +123,10 @@ module.exports = {
             tenantId: '{{answers.project.dataCloud.tenantId}}'
         }
     },
+    // Experimental: The base path for the app. This is the path that will be prepended to all /mobify routes,
+    // callback routes, and Express routes.
+    // Setting this to `/` or an empty string will result in the above routes not having a base path.
+    envBasePath: '/',
     // This list contains server-side only libraries that you don't want to be compiled by webpack
     externals: [],
     // Page not found url for your app

packages/pwa-kit-create-app/assets/bootstrap/js/overrides/app/components/_app-config/index.jsx.hbs

@@ -18,9 +18,13 @@ import {
     resolveLocaleFromUrl
 } from '@salesforce/retail-react-app/app/utils/site-utils'
 import {getConfig} from '@salesforce/pwa-kit-runtime/utils/ssr-config'
-import {proxyBasePath} from '@salesforce/pwa-kit-runtime/utils/ssr-namespace-paths'
+import {
+    getEnvBasePath,
+    slasPrivateProxyPath
+} from '@salesforce/pwa-kit-runtime/utils/ssr-namespace-paths'
 import {createUrlTemplate} from '@salesforce/retail-react-app/app/utils/url'
 import createLogger from '@salesforce/pwa-kit-runtime/utils/logger-factory'
+import {isAbsoluteURL} from '@salesforce/retail-react-app/app/page-designer/utils'
 
 import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
 import {withReactQuery} from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/with-react-query'
@@ -68,6 +72,14 @@ const AppConfig = ({children, locals = {}}) => {
         supportedCountries: STORE_LOCATOR_SUPPORTED_COUNTRIES
     }
 
+    // Set absolute uris for CommerceApiProvider proxies and callbacks
+    const redirectURI = `${appOrigin}${getEnvBasePath()}/callback`
+    const proxy = `${appOrigin}${getEnvBasePath()}${commerceApiConfig.proxyPath}`
+    const slasPrivateClientProxyEndpoint = `${appOrigin}${getEnvBasePath()}${slasPrivateProxyPath}`
+    const passwordlessLoginCallbackURI = isAbsoluteURL(passwordlessCallback)
+        ? passwordlessCallback
+        : `${appOrigin}${getEnvBasePath()}${passwordlessCallback}`
+
     return (
         <CommerceApiProvider
             shortCode={commerceApiConfig.parameters.shortCode}
@@ -76,17 +88,20 @@ const AppConfig = ({children, locals = {}}) => {
             siteId={locals.site?.id}
             locale={locals.locale?.id}
             currency={locals.locale?.preferredCurrency}
-            redirectURI={`${appOrigin}/callback`}
-            proxy={`${appOrigin}${commerceApiConfig.proxyPath}`}
+            redirectURI={redirectURI}
+            proxy={proxy}
             headers={headers}
             defaultDnt={DEFAULT_DNT_STATE}
             logger={createLogger({packageName: 'commerce-sdk-react'})}
-            passwordlessLoginCallbackURI={passwordlessCallback}
-            {{#if answers.project.commerce.isSlasPrivate}}
-            // Set 'enablePWAKitPrivateClient' to true use SLAS private client login flows.
+            passwordlessLoginCallbackURI={passwordlessLoginCallbackURI}
+            // Set 'enablePWAKitPrivateClient' to true to use SLAS private client login flows.
             // Make sure to also enable useSLASPrivateClient in ssr.js when enabling this setting.
+            {{#if answers.project.commerce.isSlasPrivate}}
             enablePWAKitPrivateClient={true}
+            {{else}}
+            enablePWAKitPrivateClient={false}
             {{/if}}
+            slasPrivateClientProxyEndpoint={slasPrivateClientProxyEndpoint}
             // Uncomment 'hybridAuthEnabled' if the current site has Hybrid Auth enabled. Do NOT set this flag for hybrid storefronts using Plugin SLAS.
             // hybridAuthEnabled={true}
         >

packages/pwa-kit-create-app/assets/bootstrap/js/overrides/app/main.jsx

@@ -5,10 +5,11 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 import {start, registerServiceWorker} from '@salesforce/pwa-kit-react-sdk/ssr/browser/main'
+import {getEnvBasePath} from '@salesforce/pwa-kit-runtime/utils/ssr-namespace-paths'
 
 const main = () => {
     // The path to your service worker should match what is set up in ssr.js
-    return Promise.all([start(), registerServiceWorker('/worker.js')])
+    return Promise.all([start(), registerServiceWorker(`${getEnvBasePath()}/worker.js`)])
 }
 
 main()

packages/pwa-kit-create-app/assets/bootstrap/js/overrides/app/ssr.js.hbs

@@ -327,7 +327,7 @@ const {handler} = runtime.createHandler(options, (app) => {
     )
 
     // Handle the redirect from SLAS as to avoid error
-    app.get('/callback?*', (req, res) => {
+    app.get('/callback', (req, res) => {
         // This endpoint does nothing and is not expected to change
         // Thus we cache it for a year to maximize performance
         res.set('Cache-Control', `max-age=31536000`)