@W-21671037@ Merge 3.17.1 back into develop (#3763)

vcua-mobify · nayanavishwa · amittapalli · web-flow · commit f8739e39a572 · 2026-03-20T13:57:24.000-07:00
* Bump versions * @W-21414441@ Bump versions for 3.17.0-preview.1 (#3733) * W-2129587: removed wrapperStyle, add position fixed for LoadingSpinner to have full screen overlay * bump version to preview.1 * @W-21414441@ Bugfix - Fix adding to cart from a master product in the wishlist (#3732) * Fix add to cart bug and add e2e test * Update CHANGELOG.md * W-21432256 fix redirect payment methods status value during preview t… (#3734) * W-21432256 fix redirect payment methods status value during preview testing * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration (#3741) * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration Signed-off-by: d.phan <d.phan@salesforce.com> * add changelog Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> --------- Signed-off-by: d.phan <d.phan@salesforce.com> * clean up changelog --------- Signed-off-by: nayanavishwa <nayana.vishwa@salesforce.com> Signed-off-by: d.phan <d.phan@salesforce.com> Co-authored-by: nayanavishwa <nayana.vishwa@salesforce.com> Co-authored-by: amittapalli <amittapalli@yahoo.com> Co-authored-by: Danny Phan <125327707+dannyphan2000@users.noreply.github.com> * @W-21414441@ Bump versions for 3.17.0-preview.12 (#3744) * W-2129587: removed wrapperStyle, add position fixed for LoadingSpinner to have full screen overlay * bump version to preview.1 * @W-21414441@ Bugfix - Fix adding to cart from a master product in the wishlist (#3732) * Fix add to cart bug and add e2e test * Update CHANGELOG.md * W-21432256 fix redirect payment methods status value during preview t… (#3734) * W-21432256 fix redirect payment methods status value during preview testing * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration (#3741) * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration Signed-off-by: d.phan <d.phan@salesforce.com> * add changelog Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> --------- Signed-off-by: d.phan <d.phan@salesforce.com> * clean up changelog * bump versions * Add missing overrides to extensible app (#3745) * Add missing overrides to extensible app * Update CHANGELOG.md --------- Signed-off-by: nayanavishwa <nayana.vishwa@salesforce.com> Signed-off-by: d.phan <d.phan@salesforce.com> Co-authored-by: nayanavishwa <nayana.vishwa@salesforce.com> Co-authored-by: amittapalli <amittapalli@yahoo.com> Co-authored-by: Danny Phan <125327707+dannyphan2000@users.noreply.github.com> * @W-21414441@ PWA Kit Release 3.17.0 (#3746) * W-2129587: removed wrapperStyle, add position fixed for LoadingSpinner to have full screen overlay * bump version to preview.1 * @W-21414441@ Bugfix - Fix adding to cart from a master product in the wishlist (#3732) * Fix add to cart bug and add e2e test * Update CHANGELOG.md * W-21432256 fix redirect payment methods status value during preview t… (#3734) * W-21432256 fix redirect payment methods status value during preview testing * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration (#3741) * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration Signed-off-by: d.phan <d.phan@salesforce.com> * add changelog Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> --------- Signed-off-by: d.phan <d.phan@salesforce.com> * clean up changelog * bump versions * Add missing overrides to extensible app (#3745) * Add missing overrides to extensible app * Update CHANGELOG.md * Bump versions --------- Signed-off-by: nayanavishwa <nayana.vishwa@salesforce.com> Signed-off-by: d.phan <d.phan@salesforce.com> Co-authored-by: nayanavishwa <nayana.vishwa@salesforce.com> Co-authored-by: amittapalli <amittapalli@yahoo.com> Co-authored-by: Danny Phan <125327707+dannyphan2000@users.noreply.github.com> * @W-21566314@ - Bump version for 3.17.1-preview.0 (#3749) * W-2129587: removed wrapperStyle, add position fixed for LoadingSpinner to have full screen overlay * bump version to preview.1 * @W-21414441@ Bugfix - Fix adding to cart from a master product in the wishlist (#3732) * Fix add to cart bug and add e2e test * Update CHANGELOG.md * W-21432256 fix redirect payment methods status value during preview t… (#3734) * W-21432256 fix redirect payment methods status value during preview testing * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration (#3741) * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration Signed-off-by: d.phan <d.phan@salesforce.com> * add changelog Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> --------- Signed-off-by: d.phan <d.phan@salesforce.com> * clean up changelog * bump versions * Add missing overrides to extensible app (#3745) * Add missing overrides to extensible app * Update CHANGELOG.md * Bump versions * @W-20784635@ Productize base paths (#3614) * @W-20784722@ Move envBasePath into ssrParameters (#3590) * Move envBasePath into ssrParameters * Apply MRT restrictions on supported base paths * Update changelogs * one more changelog * Update express.test.js * Remove whitespace trimming * Remove test base path * Add comment * @W-20784635@ Support adding base paths to shopper facing URLs (#3615) * Add base path to react router routes * Handle basename for urls that bypass react router * Add a feature toggle for app base names * Add tests * Update config templates * Rename getBasename to getRouterBasePath * Update changelogs * Test fixes * Remove unused import and cleanup comments * Apply suggestions * Clean up redundant code * Fix issues from merge conflict * Update CHANGELOG.md * [Storefront Preview] Address base path duplication for manually entered urls (#3666) * Address base path duplication * Update CHANGELOG.md * Update CHANGELOG.md * Update CHANGELOG.md * Apply suggestions * Fix unwanted basePath removal if base path is a substring * Lint * Add console warn * Update refresh component to avoid duplicate base paths * Fix merge issue * Add tests for coverage * Squash changelogs * Remove warning --------- Signed-off-by: vcua-mobify <47404250+vcua-mobify@users.noreply.github.com> * Bump version to 3.17.1-preview.0 * Update CHANGELOG.md --------- Signed-off-by: nayanavishwa <nayana.vishwa@salesforce.com> Signed-off-by: d.phan <d.phan@salesforce.com> Signed-off-by: vcua-mobify <47404250+vcua-mobify@users.noreply.github.com> Co-authored-by: nayanavishwa <nayana.vishwa@salesforce.com> Co-authored-by: amittapalli <amittapalli@yahoo.com> Co-authored-by: Danny Phan <125327707+dannyphan2000@users.noreply.github.com> * @W-21671037@ Release PWA Kit 3.17.1 (#3761) * W-2129587: removed wrapperStyle, add position fixed for LoadingSpinner to have full screen overlay * bump version to preview.1 * @W-21414441@ Bugfix - Fix adding to cart from a master product in the wishlist (#3732) * Fix add to cart bug and add e2e test * Update CHANGELOG.md * W-21432256 fix redirect payment methods status value during preview t… (#3734) * W-21432256 fix redirect payment methods status value during preview testing * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration (#3741) * @W-21551291: [1CC][PWA Kit] Custom billing address lost after OTP registration Signed-off-by: d.phan <d.phan@salesforce.com> * add changelog Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> * lint fix Signed-off-by: d.phan <d.phan@salesforce.com> --------- Signed-off-by: d.phan <d.phan@salesforce.com> * clean up changelog * bump versions * Add missing overrides to extensible app (#3745) * Add missing overrides to extensible app * Update CHANGELOG.md * Bump versions * @W-20784635@ Productize base paths (#3614) * @W-20784722@ Move envBasePath into ssrParameters (#3590) * Move envBasePath into ssrParameters * Apply MRT restrictions on supported base paths * Update changelogs * one more changelog * Update express.test.js * Remove whitespace trimming * Remove test base path * Add comment * @W-20784635@ Support adding base paths to shopper facing URLs (#3615) * Add base path to react router routes * Handle basename for urls that bypass react router * Add a feature toggle for app base names * Add tests * Update config templates * Rename getBasename to getRouterBasePath * Update changelogs * Test fixes * Remove unused import and cleanup comments * Apply suggestions * Clean up redundant code * Fix issues from merge conflict * Update CHANGELOG.md * [Storefront Preview] Address base path duplication for manually entered urls (#3666) * Address base path duplication * Update CHANGELOG.md * Update CHANGELOG.md * Update CHANGELOG.md * Apply suggestions * Fix unwanted basePath removal if base path is a substring * Lint * Add console warn * Update refresh component to avoid duplicate base paths * Fix merge issue * Add tests for coverage * Squash changelogs * Remove warning --------- Signed-off-by: vcua-mobify <47404250+vcua-mobify@users.noreply.github.com> * Bump version to 3.17.1-preview.0 * Update CHANGELOG.md * @W-21671037@ Remove base path from /__pwa-kit requests if showBasePath is false (#3758) * Remove base path from /__pwa-kit requests if showBasePath is false * Update CHANGELOG.md * Use a redirect so client side is able hydrate. * Apply storefront preview component changes to deal with client-side single page navigation * Update CHANGELOG.md * Bump version to 3.17.1 --------- Signed-off-by: nayanavishwa <nayana.vishwa@salesforce.com> Signed-off-by: d.phan <d.phan@salesforce.com> Signed-off-by: vcua-mobify <47404250+vcua-mobify@users.noreply.github.com> Co-authored-by: nayanavishwa <nayana.vishwa@salesforce.com> Co-authored-by: amittapalli <amittapalli@yahoo.com> Co-authored-by: Danny Phan <125327707+dannyphan2000@users.noreply.github.com> * Update CHANGELOG.md --------- Signed-off-by: nayanavishwa <nayana.vishwa@salesforce.com> Signed-off-by: d.phan <d.phan@salesforce.com> Signed-off-by: vcua-mobify <47404250+vcua-mobify@users.noreply.github.com> Co-authored-by: nayanavishwa <nayana.vishwa@salesforce.com> Co-authored-by: amittapalli <amittapalli@yahoo.com> Co-authored-by: Danny Phan <125327707+dannyphan2000@users.noreply.github.com>
diff --git a/packages/commerce-sdk-react/CHANGELOG.md b/packages/commerce-sdk-react/CHANGELOG.md
@@ -1,7 +1,10 @@
-## v5.2.0-dev (Mar 12, 2026)
+## v5.2.0-dev (Mar 20, 2026)
+
+## v5.1.1 (Mar 20, 2026)
 - Update storefront preview to support base paths [#3614](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3614)
+- Remove base path from /__pwa-kit route requests when showBasePath is false [#3758](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3758)
 
-## v5.1.0
+## v5.1.0 (Mar 12, 2026)
 - Add Page Designer Support [#3727](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3727)
 - Bump commerce-sdk-isomorphic to 5.1.0 [#3725](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3725)
 - Update ShopperBasketsV2 hooks documentation and query keys [#3728](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3728)
diff --git a/packages/commerce-sdk-react/src/components/StorefrontPreview/storefront-preview.test.tsx b/packages/commerce-sdk-react/src/components/StorefrontPreview/storefront-preview.test.tsx
@@ -213,6 +213,102 @@ describe('Storefront Preview Component', function () {
         expect(mockPush).toHaveBeenCalledWith({pathname: '/product/123', search: '?q=1'})
     })
 
+    test('experimentalUnsafeNavigate strips base path prefix from /__pwa-kit/ paths when getBasePath returns empty (showBasePath false)', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => ''}
+            />
+        )
+
+        // Runtime Admin sends /test/__pwa-kit/refresh but React Router has no basename
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.(
+            '/test/__pwa-kit/refresh?referrer=/some-page',
+            'replace'
+        )
+        expect(mockReplace).toHaveBeenCalledWith('/__pwa-kit/refresh?referrer=/some-page')
+    })
+
+    test('experimentalUnsafeNavigate strips base path prefix from /__pwa-kit/ location objects when getBasePath returns empty', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => ''}
+            />
+        )
+
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.(
+            {pathname: '/test/__pwa-kit/refresh', search: '?referrer=/some-page'},
+            'replace'
+        )
+        expect(mockReplace).toHaveBeenCalledWith({
+            pathname: '/__pwa-kit/refresh',
+            search: '?referrer=/some-page'
+        })
+    })
+
+    test('experimentalUnsafeNavigate normalizes /__pwa-kit/ paths and then strips router base path (showBasePath true)', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => '/test'}
+            />
+        )
+
+        // Runtime Admin sends /test/__pwa-kit/refresh, normalizePwaKitPath strips to
+        // /__pwa-kit/refresh, then removeBasePathFromLocation is a no-op (doesn't start with /test/)
+        // React Router re-adds the basename, so history receives /__pwa-kit/refresh
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.(
+            '/test/__pwa-kit/refresh?referrer=/test/some-page',
+            'replace'
+        )
+        expect(mockReplace).toHaveBeenCalledWith('/__pwa-kit/refresh?referrer=/test/some-page')
+    })
+
+    test('experimentalUnsafeNavigate does not alter /__pwa-kit/ paths that have no prefix', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => ''}
+            />
+        )
+
+        // Path already starts with /__pwa-kit/ — no prefix to strip
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.(
+            '/__pwa-kit/refresh?referrer=/some-page',
+            'push'
+        )
+        expect(mockPush).toHaveBeenCalledWith('/__pwa-kit/refresh?referrer=/some-page')
+    })
+
+    test('experimentalUnsafeNavigate does not affect non /__pwa-kit/ paths when showBasePath is false', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => ''}
+            />
+        )
+
+        // Regular navigation paths should pass through untouched
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.('/products/123', 'push')
+        expect(mockPush).toHaveBeenCalledWith('/products/123')
+    })
+
     test('cache breaker is added to the parameters of SCAPI requests, only if in storefront preview', () => {
         ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
         mockQueryEndpoint('baskets/123', {})
diff --git a/packages/commerce-sdk-react/src/components/StorefrontPreview/storefront-preview.tsx b/packages/commerce-sdk-react/src/components/StorefrontPreview/storefront-preview.tsx
@@ -27,6 +27,28 @@ function removeBasePathFromPath(path: string, basePath: string): string {
     return matches ? path.slice(basePath.length) || '/' : path
 }
 
+const PWA_KIT_PATH_PREFIX = '/__pwa-kit/'
+
+/**
+ * Runtime Admin always prepends envBasePath to /__pwa-kit/ paths (e.g. /test/__pwa-kit/refresh),
+ * but when showBasePath is false, React Router has no basename and expects /__pwa-kit/refresh.
+ * 
+ * This ensures that regardless of the showBasePath setting, these paths are normalized to 
+ * remove the base path.
+ */
+function normalizePwaKitPath<T>(pathOrLocation: LocationDescriptor<T>): LocationDescriptor<T> {
+    if (typeof pathOrLocation === 'string') {
+        const idx = pathOrLocation.indexOf(PWA_KIT_PATH_PREFIX)
+        return idx > 0 ? pathOrLocation.slice(idx) : pathOrLocation
+    }
+    const pathname = pathOrLocation.pathname ?? '/'
+    const idx = pathname.indexOf(PWA_KIT_PATH_PREFIX)
+    if (idx > 0) {
+        return {...pathOrLocation, pathname: pathname.slice(idx)}
+    }
+    return pathOrLocation
+}
+
 /**
  * Strip the base path from a path
  *
@@ -53,8 +75,8 @@ function removeBasePathFromLocation<T>(
  * @param enabled - flag to turn on/off Storefront Preview feature. By default, it is set to true.
  * This flag only applies if storefront is running in a Runtime Admin iframe.
  * @param getToken - A method that returns the access token for the current user
- * @param getBasePath - A method that returns the router base path of the app. Requird if using
- * base path for router routes (showBasePath is true in url config).
+ * @param getBasePath - A method that returns the router base path of the app.
+ * Required if using a base path for router routes (showBasePath is true in url config).
  */
 export const StorefrontPreview = ({
     children,
@@ -88,7 +110,8 @@ export const StorefrontPreview = ({
                     ...args: unknown[]
                 ) => {
                     const basePath = getBasePath?.() ?? ''
-                    const pathWithoutBase = removeBasePathFromLocation(path, basePath)
+                    const normalizedPath = normalizePwaKitPath(path)
+                    const pathWithoutBase = removeBasePathFromLocation(normalizedPath, basePath)
                     history[action](pathWithoutBase, ...args)
                 }
             }
diff --git a/packages/pwa-kit-create-app/CHANGELOG.md b/packages/pwa-kit-create-app/CHANGELOG.md
@@ -1,4 +1,6 @@
-## v3.18.0-dev (Mar 12, 2026)
+## v3.18.0-dev (Mar 20, 2026)
+
+## v3.17.1 (Mar 20, 2026)
 - Add base path prefix to support multiple MRT environments under 1 domain [#3614](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3614)
 
 ## v3.17.0 (Mar 12, 2026)
diff --git a/packages/pwa-kit-dev/CHANGELOG.md b/packages/pwa-kit-dev/CHANGELOG.md
@@ -1,4 +1,6 @@
-## v3.18.0-dev (Mar 12, 2026)
+## v3.18.0-dev (Mar 20, 2026)
+
+## v3.17.1 (Mar 20, 2026)
 - Add base path prefix to support multiple MRT environments under 1 domain [#3614](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3614)
 
 ## v3.17.0 (Mar 12, 2026)
diff --git a/packages/pwa-kit-react-sdk/CHANGELOG.md b/packages/pwa-kit-react-sdk/CHANGELOG.md
@@ -1,4 +1,6 @@
-## v3.18.0-dev (Mar 12, 2026)
+## v3.18.0-dev (Mar 20, 2026)
+
+## v3.17.1 (Mar 20, 2026)
 - Add base path prefix to support multiple MRT environments under 1 domain [#3614](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3614)
 
 ## v3.17.0 (Mar 12, 2026)
diff --git a/packages/pwa-kit-runtime/CHANGELOG.md b/packages/pwa-kit-runtime/CHANGELOG.md
@@ -1,6 +1,9 @@
-## v3.18.0-dev (Mar 12, 2026)
-- Add additional logging and error handling for SLAS error handling [#3750](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3750).
+## v3.18.0-dev (Mar 20, 2026)
+- Add additional logging and error handling for SLAS error handling [#3750](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3750)
+
+## v3.17.1 (Mar 20, 2026)
 - Add base path prefix to support multiple MRT environments under 1 domain [#3614](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3614)
+- Remove base path from /__pwa-kit route requests when showBasePath is false [#3758](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3758)
 
 ## v3.17.0 (Mar 12, 2026)
 - Add Node 24 support. Migrate deprecated Node.js `url.parse()` and `url.format()` to the WHATWG `URL` [#3652](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3652)
diff --git a/packages/pwa-kit-runtime/src/ssr/server/build-remote-server.js b/packages/pwa-kit-runtime/src/ssr/server/build-remote-server.js
@@ -54,6 +54,7 @@ import logger from '../../utils/logger-instance'
 import {createProxyMiddleware, responseInterceptor} from 'http-proxy-middleware'
 import {hybridProxy} from '../../utils/ssr-server/hybrid-proxy'
 import {convertExpressRouteToRegex} from '../../utils/ssr-server/convert-express-route'
+import {getConfig} from '../../utils/ssr-config'
 import {ServerlessAdapter} from '@h4ad/serverless-adapter'
 import {DefaultHandler} from '@h4ad/serverless-adapter/lib/handlers/default'
 import {CallbackResolver} from '@h4ad/serverless-adapter/lib/resolvers/callback'
@@ -578,18 +579,28 @@ export const RemoteServerFactory = {
          * If the server receives a request containing the base path, remove it before allowing
          * the request through to the other express endpoints
          *
-         * We scope base path removal to /mobify routes and routes defined by the express app
-         * (For example /callback or /worker.js)
+         * We scope base path removal to /mobify routes, /__pwa-kit routes (when showBasePath
+         * is false), and routes defined by the express app (For example /callback or /worker.js).
          * This is to avoid affecting React Router routes where a site id or locale might be present
          * that is equal to the base path.
          *
+         * /__pwa-kit routes are a special case. These are internal PWA Kit routes
+         * (e.g. /__pwa-kit/refresh) that are registered as React Router routes and are invoked
+         * by the Storefront Preview code on Runtime Admin (which always appends a base path if set).
+         * When showBasePath is false, React Router has no basename, so we redirect to the clean
+         * URL (without base path) so the browser navigates to a path that React Router can match
+         * and hydrate correctly on the client.
+         * When showBasePath is true, React Router handles the base path via its basename prop.
+         *
          * For example, if you have a base path of /us and a site id of /us we don't want
          * to remove the /us from www.example.com/us/en-US/category/... as this route is handled by
          * React Router and the PWA multisite implementation.
          *
          * @param req {express.req} the incoming request - modified in-place
          * @private
          */
+        const showBasePath = getConfig()?.app?.url?.showBasePath === true
+
         const removeBasePathMiddleware = (req, res, next) => {
             const basePath = getEnvBasePath()
 
@@ -601,6 +612,15 @@ export const RemoteServerFactory = {
                 return next()
             }
 
+            // /__pwa-kit routes: when showBasePath is false, the browser URL still has the
+            // base path but client-side React Router has no basename, so hydration would fail.
+            // Redirect to the clean URL so the browser navigates to a path React Router matches.
+            if (!showBasePath && req.path.startsWith(`${basePath}/__pwa-kit`)) {
+                const cleanPath = removeBasePathFromPath(req.path)
+                const {search} = parseRequestUrl(req)
+                return res.redirect(302, cleanPath + search)
+            }
+
             // For other routes, only proceed if path equals basePath or path starts with basePath + '/'
             const pathMatchesBasePath = req.path === basePath || req.path.startsWith(basePath + '/')
             if (!pathMatchesBasePath) {
diff --git a/packages/pwa-kit-runtime/src/ssr/server/express.test.js b/packages/pwa-kit-runtime/src/ssr/server/express.test.js
@@ -1397,6 +1397,12 @@ describe('SLAS private client proxy', () => {
 })
 
 describe('Base path tests', () => {
+    beforeEach(() => {
+        // Re-establish the getConfig mock that afterEach's restoreAllMocks clears.
+        // _setupBasePathMiddleware reads getConfig() at setup time.
+        jest.spyOn(ssrConfig, 'getConfig').mockReturnValue({})
+    })
+
     afterEach(() => {
         jest.restoreAllMocks()
     })
@@ -1494,4 +1500,43 @@ describe('Base path tests', () => {
                 expect(response.body.message).toBe('test')
             })
     }, 15000)
+
+    test('should redirect /__pwa-kit routes to clean URL when showBasePath is false', async () => {
+        jest.spyOn(ssrNamespacePaths, 'getEnvBasePath').mockReturnValue('/basepath')
+        jest.spyOn(ssrConfig, 'getConfig').mockReturnValue({
+            app: {url: {showBasePath: false}}
+        })
+
+        const app = RemoteServerFactory._createApp(opts())
+
+        return request(app)
+            .get('/basepath/__pwa-kit/refresh?referrer=/some-page')
+            .expect(302)
+            .then((response) => {
+                // Should redirect to the clean URL without base path
+                expect(response.headers.location).toBe('/__pwa-kit/refresh?referrer=/some-page')
+            })
+    }, 15000)
+
+    test('should not remove base path from /__pwa-kit routes when showBasePath is true', async () => {
+        jest.spyOn(ssrNamespacePaths, 'getEnvBasePath').mockReturnValue('/basepath')
+        jest.spyOn(ssrConfig, 'getConfig').mockReturnValue({
+            app: {url: {showBasePath: true}}
+        })
+
+        const app = RemoteServerFactory._createApp(opts())
+
+        let capturedPath = null
+        app.use((req, res, next) => {
+            capturedPath = req.path
+            next()
+        })
+
+        return request(app)
+            .get('/basepath/__pwa-kit/refresh')
+            .then(() => {
+                // Base path should NOT be stripped since React Router handles it via basename
+                expect(capturedPath).toBe('/basepath/__pwa-kit/refresh')
+            })
+    }, 15000)
 })
diff --git a/packages/template-retail-react-app/CHANGELOG.md b/packages/template-retail-react-app/CHANGELOG.md
@@ -1,4 +1,6 @@
-## v9.2.0-dev (Mar 12, 2026)
+## v9.2.0-dev (Mar 20, 2026)
+
+## v9.1.1 (Mar 20, 2026)
 - Add base path prefix to support multiple MRT environments under 1 domain [#3614](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3614)
 
 ## v9.1.0 (Mar 12, 2026)
