[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

Author: vcua-mobify

packages/commerce-sdk-react/CHANGELOG.md

@@ -2,6 +2,7 @@
 - Upgrade to commerce-sdk-isomorphic v5.0.0 and introduce Payment Instrument SCAPI integration [#3552](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3552)
 - Update storefront preview to support base paths [#3666](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3666)
 
+
 ## v4.4.0-dev (Dec 17, 2025)
 - [Bugfix]Ensure code_verifier can be optional in resetPassword call [#3567](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3567)
 - [Improvement] Strengthening typescript types on custom endpoint options and fetchOptions types [#3589](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3589)

packages/commerce-sdk-react/src/components/StorefrontPreview/storefront-preview.test.tsx

@@ -14,7 +14,16 @@ import {useCommerceApi, useConfig} from '../../hooks'
 
 declare global {
     interface Window {
-        STOREFRONT_PREVIEW?: Record<string, unknown>
+        STOREFRONT_PREVIEW?: {
+            getToken?: () => string | undefined | Promise<string | undefined>
+            onContextChange?: () => void | Promise<void>
+            siteId?: string
+            experimentalUnsafeNavigate?: (
+                path: string | {pathname: string; search?: string; hash?: string; state?: unknown},
+                action?: 'push' | 'replace',
+                ...args: unknown[]
+            ) => void
+        }
     }
 }
 
@@ -28,9 +37,24 @@ jest.mock('./utils', () => {
 jest.mock('../../auth/index.ts')
 jest.mock('../../hooks/useConfig', () => jest.fn())
 
+const mockPush = jest.fn()
+const mockReplace = jest.fn()
+jest.mock('react-router-dom', () => {
+    const actual = jest.requireActual('react-router-dom')
+    return {
+        ...actual,
+        useHistory: () => ({
+            push: mockPush,
+            replace: mockReplace
+        })
+    }
+})
+
 describe('Storefront Preview Component', function () {
     beforeEach(() => {
         delete window.STOREFRONT_PREVIEW
+        mockPush.mockClear()
+        mockReplace.mockClear()
         ;(useConfig as jest.Mock).mockReturnValue({siteId: 'site-id'})
     })
     afterEach(() => {
@@ -107,6 +131,88 @@ describe('Storefront Preview Component', function () {
         expect(window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate).toBeDefined()
     })
 
+    test('experimentalUnsafeNavigate removes base path from path when getBasePath is provided', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => '/mybase'}
+            />
+        )
+
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.('/mybase/product/123', 'push')
+        expect(mockPush).toHaveBeenCalledWith('/product/123')
+
+        mockPush.mockClear()
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.('/mybase/account', 'replace')
+        expect(mockReplace).toHaveBeenCalledWith('/account')
+    })
+
+    test('experimentalUnsafeNavigate does not remove when path does not start with base path', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => '/mybase'}
+            />
+        )
+
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.('/other/product/123', 'push')
+        expect(mockPush).toHaveBeenCalledWith('/other/product/123')
+    })
+
+    test('experimentalUnsafeNavigate does not strip when path has basePath only as substring (e.g. /shop vs /shopping/cart)', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => '/shop'}
+            />
+        )
+
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.('/shopping/cart', 'push')
+        expect(mockPush).toHaveBeenCalledWith('/shopping/cart')
+    })
+
+    test('experimentalUnsafeNavigate strips to / when path exactly equals basePath', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => '/mybase'}
+            />
+        )
+
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.('/mybase', 'push')
+        expect(mockPush).toHaveBeenCalledWith('/')
+    })
+
+    test('experimentalUnsafeNavigate removes base path from location object when getBasePath is provided', () => {
+        ;(detectStorefrontPreview as jest.Mock).mockReturnValue(true)
+
+        render(
+            <StorefrontPreview
+                enabled={true}
+                getToken={() => 'my-token'}
+                getBasePath={() => '/mybase'}
+            />
+        )
+
+        window.STOREFRONT_PREVIEW?.experimentalUnsafeNavigate?.(
+            {pathname: '/mybase/product/123', search: '?q=1'},
+            'push'
+        )
+        expect(mockPush).toHaveBeenCalledWith({pathname: '/product/123', search: '?q=1'})
+    })
+
     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', {})

packages/commerce-sdk-react/src/components/StorefrontPreview/storefront-preview.tsx

@@ -17,20 +17,57 @@ type GetToken = () => string | undefined | Promise<string | undefined>
 type ContextChangeHandler = () => void | Promise<void>
 type OptionalWhenDisabled<T> = ({enabled?: true} & T) | ({enabled: false} & Partial<T>)
 
+/**
+ * Remove the base path from a path string.
+ * Only strips when path equals basePath or path starts with basePath + '/'.
+ */
+function removeBasePathFromPath(path: string, basePath: string): string {
+    const matches =
+        path.startsWith(basePath + '/') || path === basePath
+    return matches ? path.slice(basePath.length) || '/' : path
+}
+
+/**
+ * Strip the base path from a path
+ *
+ * React Router history re-adds the base path to the path, so we
+ * remove it here to avoid base path duplication.
+ */
+function removeBasePathFromLocation<T>(
+    pathOrLocation: LocationDescriptor<T>,
+    basePath: string
+): LocationDescriptor<T> {
+    if (!basePath) return pathOrLocation
+    if (typeof pathOrLocation === 'string') {
+        return removeBasePathFromPath(pathOrLocation, basePath) as LocationDescriptor<T>
+    }
+    const pathname = pathOrLocation.pathname ?? '/'
+    return {
+        ...pathOrLocation,
+        pathname: removeBasePathFromPath(pathname, basePath)
+    }
+}
+
 /**
  *
  * @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.
  */
 export const StorefrontPreview = ({
     children,
     enabled = true,
     getToken,
-    onContextChange
+    onContextChange,
+    getBasePath
 }: React.PropsWithChildren<
     // Props are only required when Storefront Preview is enabled
-    OptionalWhenDisabled<{getToken: GetToken; onContextChange?: ContextChangeHandler}>
+    OptionalWhenDisabled<{
+        getToken: GetToken
+        onContextChange?: ContextChangeHandler
+        getBasePath?: () => string
+    }>
 >) => {
     const history = useHistory()
     const isHostTrusted = detectStorefrontPreview()
@@ -39,6 +76,13 @@ export const StorefrontPreview = ({
 
     useEffect(() => {
         if (enabled && isHostTrusted) {
+            if (process.env.NODE_ENV !== 'production' && !getBasePath) {
+                console.warn(
+                    '[StorefrontPreview] No getBasePath prop provided. ' +
+                        'If your app uses a base path for router routes (showBasePath is true in url config), ' +
+                        'pass getBasePath to avoid base path duplication during navigation.'
+                )
+            }
             window.STOREFRONT_PREVIEW = {
                 ...window.STOREFRONT_PREVIEW,
                 getToken,
@@ -49,11 +93,13 @@ export const StorefrontPreview = ({
                     action: 'push' | 'replace' = 'push',
                     ...args: unknown[]
                 ) => {
-                    history[action](path, ...args)
+                    const basePath = getBasePath?.() ?? ''
+                    const pathWithoutBase = removeBasePathFromLocation(path, basePath)
+                    history[action](pathWithoutBase, ...args)
                 }
             }
         }
-    }, [enabled, getToken, onContextChange, siteId])
+    }, [enabled, getToken, onContextChange, siteId, getBasePath])
 
     useEffect(() => {
         if (enabled && isHostTrusted) {
@@ -99,7 +145,8 @@ StorefrontPreview.propTypes = {
     // to get to a place where both these props are simply optional and we will provide default implementations.
     // This would make the API simpler to use.
     getToken: CustomPropTypes.requiredFunctionWhenEnabled,
-    onContextChange: PropTypes.func
+    onContextChange: PropTypes.func,
+    getBasePath: PropTypes.func
 }
 
 export default StorefrontPreview

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

@@ -26,7 +26,6 @@ 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/pwa-kit-runtime/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## v3.16.0-dev (Dec 17, 2025)
 - Move envBasePath into ssrParameters [#3590](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3590)
 - Support adding base paths to shopper facing URLs [#3615](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3615)
+- Update storefront preview to support base paths [#3666](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3666)
 
 ## v3.15.0 (Dec 17, 2025)
 - Fix multiple set-cookie headers [#3508](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3508)

packages/pwa-kit-runtime/src/ssr/server/build-remote-server.js

@@ -602,8 +602,9 @@ export const RemoteServerFactory = {
                 return next()
             }
 
-            // For other routes, only proceed if path actually starts with base path
-            if (!req.path.startsWith(basePath)) {
+            // 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) {
                 return next()
             }
 

packages/template-retail-react-app/CHANGELOG.md

@@ -2,6 +2,7 @@
 - [Feature] One Click Checkout [#3552](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3552)
 - Move envBasePath into ssrParameters [#3590](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3590)
 - Support adding base paths to shopper facing URLs [#3615](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3615)
+- Update storefront preview to support base paths [#3666](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3666)
 - [Feature] Add `fuzzyPathMatching` to reduce computational overhead of route generation at time of application load [#3530](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3530)
 - [Bugfix] Fix Passwordless Login landingPath, Reset Password landingPath, and Social Login redirectUri value in config not being used [#3560](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3560)
 - [Feature] PWA Integration with OMS

packages/template-retail-react-app/app/components/_app/index.jsx

@@ -303,7 +303,7 @@ const App = (props) => {
 
     return (
         <Box className="sf-app" {...styles.container}>
-            <StorefrontPreview getToken={getTokenWhenReady}>
+            <StorefrontPreview getToken={getTokenWhenReady} getBasePath={getRouterBasePath}>
                 <IntlProvider
                     onError={(err) => {
                         if (!messages) {

packages/template-retail-react-app/app/utils/site-utils.js

@@ -95,6 +95,20 @@ export const getSiteByReference = (siteRef) => {
     )
 }
 
+/**
+ * Remove the base path from a path string only when path equals basePath or path starts with basePath + '/'.
+ * @param {string} path - the path to strip
+ * @param {string} basePath - the base path to remove
+ * @returns {string} the path with base path removed, or the original path
+ */
+export const removeBasePathFromPath = (path, basePath) => {
+    if (!basePath) return path
+    if (path.startsWith(basePath + '/') || path === basePath) {
+        return path.substring(basePath.length) || '/'
+    }
+    return path
+}
+
 /**
  * This function return the identifiers (site and locale) from the given url
  * The site will always go before locale if both of them are presented in the pathname
@@ -107,9 +121,7 @@ export const getParamsFromPath = (path) => {
     // Remove the base path from the pathname if present since
     // it shifts the location of the site and locale in the pathname
     const basePath = getRouterBasePath()
-    if (basePath && pathname.startsWith(basePath)) {
-        pathname = pathname.substring(basePath.length)
-    }
+    pathname = removeBasePathFromPath(pathname, basePath)
 
     const config = getConfig()
     const {pathMatcher, searchMatcherForSite, searchMatcherForLocale} = getConfigMatcher(config)

packages/template-retail-react-app/app/utils/site-utils.test.js

@@ -16,7 +16,8 @@ import {getRouterBasePath} from '@salesforce/pwa-kit-react-sdk/ssr/universal/uti
 import mockConfig from '@salesforce/retail-react-app/config/mocks/default'
 import {
     getParamsFromPath,
-    resolveLocaleFromUrl
+    resolveLocaleFromUrl,
+    removeBasePathFromPath
 } from '@salesforce/retail-react-app/app/utils/site-utils'
 jest.mock('@salesforce/pwa-kit-runtime/utils/ssr-config', () => {
     const origin = jest.requireActual('@salesforce/pwa-kit-react-sdk/ssr/universal/utils')
@@ -341,6 +342,43 @@ describe('getParamsFromPath', function () {
             const result = getParamsFromPath(path)
             expect(result).toEqual({siteRef: 'us', localeRef: 'en-US'})
         })
+
+        test('should not strip when path has basePath only as substring (e.g. /shop vs /shopping/cart)', () => {
+            const basePath = '/shop'
+            getRouterBasePath.mockReturnValue(basePath)
+            getConfig.mockImplementation(() => ({
+                ...mockConfig,
+                app: {
+                    ...mockConfig.app,
+                    url: {
+                        ...mockConfig.app.url,
+                        showBasePath: true
+                    }
+                }
+            }))
+
+            const result = getParamsFromPath('/shopping/cart')
+            expect(result).toBeDefined()
+        })
+    })
+})
+
+describe('removeBasePathFromPath', () => {
+    test('removes when path starts with basePath + "/"', () => {
+        expect(removeBasePathFromPath('/shop/cart', '/shop')).toBe('/cart')
+        expect(removeBasePathFromPath('/test-base/uk/en-GB/foo', '/test-base')).toBe(
+            '/uk/en-GB/foo'
+        )
+    })
+    test('removes to "/" when path exactly equals basePath', () => {
+        expect(removeBasePathFromPath('/shop', '/shop')).toBe('/')
+    })
+    test('does not remove when basePath is only a substring (e.g. /shop vs /shopping/cart)', () => {
+        expect(removeBasePathFromPath('/shopping/cart', '/shop')).toBe('/shopping/cart')
+        expect(removeBasePathFromPath('/shopping', '/shop')).toBe('/shopping')
+    })
+    test('returns path unchanged when basePath is empty', () => {
+        expect(removeBasePathFromPath('/any/path', '')).toBe('/any/path')
     })
 })