Merge pull request #3530 from SalesforceCommerceCloud/bendvc/W-20607771_add-fuzzy-path-matching

@@W-20607771@@ Add `fuzzyPathMatching` option to optimize route configuration

Author: bendvc

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

@@ -1,4 +1,5 @@
 ## v8.4.0-dev (Dec 17, 2025)
+- [Feature] Add `fuzzyPathMatching` to reduce computational overhead of route generation at time of application load [#3530](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3530)
 
 ## v8.3.0 (Dec 17, 2025)
 - [Bugfix] Fix Forgot Password link not working from Account Profile password update form [#3493](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3493)

packages/template-retail-react-app/app/routes.jsx

@@ -144,6 +144,7 @@ export const routes = [
 export default () => {
     const config = getConfig()
     return configureRoutes(routes, config, {
-        ignoredRoutes: ['/callback', '*']
+        ignoredRoutes: ['/callback', '*'],
+        fuzzyPathMatching: true
     })
 }

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

@@ -9,25 +9,99 @@ import {getSites} from '@salesforce/retail-react-app/app/utils/site-utils'
 import {urlPartPositions} from '@salesforce/retail-react-app/app/constants'
 
 /**
- * Construct literal routes based on url config
- *      with site and locale references (ids and aliases) from each in your application config
+ * Build regex patterns for site and locale route parameters.
+ * Creates patterns like "siteA|siteB|siteC" from all valid site/locale refs.
+ *
+ * @param {array} allSites - array of site configurations
+ * @returns {object} - { sitePattern, localePattern }
+ */
+const buildRoutePatterns = (allSites) => {
+    const siteRefs = allSites.flatMap((site) => [site.alias, site.id]).filter(Boolean)
+
+    const localeRefs = allSites
+        .flatMap((site) => site.l10n.supportedLocales)
+        .flatMap((locale) => [locale.alias, locale.id])
+        .filter(Boolean)
+
+    // Remove duplicates and join into regex pattern
+    const sitePattern = [...new Set(siteRefs)].join('|')
+    const localePattern = [...new Set(localeRefs)].join('|')
+
+    return {sitePattern, localePattern}
+}
+
+/**
+ * Configure routes using parameterized paths with regex constraints.
+ * This approach generates fewer routes by using patterns like:
+ *   /:site(siteA|siteB)/:locale(en|fr)/path
+ *
+ * Note: This may match site/locale combinations that aren't valid together
+ * (e.g., a locale not supported by a specific site). Runtime validation
+ * should be performed after route matching.
  *
  * @param {array} routes - array of routes to be reconstructed
- * @param {object} urlConfig
- * @param {object} options - options if there are any
- * @param {array} options.ignoredRoutes - routes that does not need be reconstructed
- * @return {array} - list of routes objects that has site and locale refs
+ * @param {object} urlConfig - url configuration with site/locale positions
+ * @param {array} allSites - array of site configurations
+ * @param {array} ignoredRoutes - routes that should not be reconstructed
+ * @returns {array} - list of parameterized route objects
  */
-export const configureRoutes = (routes = [], config, {ignoredRoutes = []}) => {
-    if (!routes.length) return []
-    if (!config) return routes
+const configureRoutesWithFuzzyMatching = (routes, urlConfig, allSites, ignoredRoutes) => {
+    const {sitePattern, localePattern} = buildRoutePatterns(allSites)
+    const {locale: localePosition, site: sitePosition} = urlConfig
 
-    const {url: urlConfig} = config.app
+    const outputRoutes = []
 
-    const allSites = getSites()
-    if (!allSites) return routes
+    for (const route of routes) {
+        const {path, ...rest} = route
+
+        if (ignoredRoutes.includes(path)) {
+            outputRoutes.push(route)
+            continue
+        }
+
+        if (localePosition === urlPartPositions.PATH && sitePosition === urlPartPositions.PATH) {
+            // Both site and locale in path
+            outputRoutes.push({
+                path: `/:site(${sitePattern})/:locale(${localePattern})${path}`,
+                ...rest
+            })
+        } else if (sitePosition === urlPartPositions.PATH) {
+            // Site only in path
+            outputRoutes.push({
+                path: `/:site(${sitePattern})${path}`,
+                ...rest
+            })
+        } else if (localePosition === urlPartPositions.PATH) {
+            // Locale only in path
+            outputRoutes.push({
+                path: `/:locale(${localePattern})${path}`,
+                ...rest
+            })
+        }
+
+        // Original route as fallback
+        outputRoutes.push(route)
+    }
+
+    return outputRoutes
+}
+
+/**
+ * Configure routes using explicit paths for each site/locale combination.
+ * This is the original approach that generates literal routes like:
+ *   /siteA/en/path, /siteA/fr/path, /siteB/en/path, etc.
+ *
+ * @param {array} routes - array of routes to be reconstructed
+ * @param {object} urlConfig - url configuration with site/locale positions
+ * @param {array} allSites - array of site configurations
+ * @param {array} ignoredRoutes - routes that should not be reconstructed
+ * @returns {array} - list of explicit route objects
+ */
+const configureRoutesWithExplicitMatching = (routes, urlConfig, allSites, ignoredRoutes) => {
+    const {locale: localePosition, site: sitePosition} = urlConfig
 
     let outputRoutes = []
+
     for (let i = 0; i < routes.length; i++) {
         const {path, ...rest} = routes[i]
 
@@ -44,7 +118,6 @@ export const configureRoutes = (routes = [], config, {ignoredRoutes = []}) => {
                     localeRefs.push(locale.id)
                 })
                 localeRefs = localeRefs.filter(Boolean)
-                const {locale: localePosition, site: sitePosition} = urlConfig
 
                 if (
                     localePosition === urlPartPositions.PATH &&
@@ -100,12 +173,57 @@ export const configureRoutes = (routes = [], config, {ignoredRoutes = []}) => {
             outputRoutes.push(routes[i])
         }
     }
+
     // Remove any duplicate routes
     outputRoutes = outputRoutes.reduce((res, route) => {
         if (!res.some(({path}) => path === route.path)) {
             res.push(route)
         }
         return res
     }, [])
+
+    return outputRoutes
+}
+
+/**
+ * Construct routes based on url config with site and locale references
+ * (ids and aliases) from each site in your application config.
+ *
+ * @param {array} routes - array of routes to be reconstructed
+ * @param {object} config - application configuration
+ * @param {object} options - options if there are any
+ * @param {array} options.ignoredRoutes - routes that should not be reconstructed
+ * @param {boolean} options.fuzzyPathMatching - when true, uses parameterized routes with
+ *        regex constraints (e.g., /:site(a|b)/:locale(en|fr)/path) for fewer, more efficient
+ *        route configurations. When false (default), generates explicit routes for each
+ *        site/locale combination. Fuzzy matching may match invalid site/locale combinations
+ *        that require runtime validation.
+ * @returns {array} - list of route objects with site and locale refs
+ */
+export const configureRoutes = (
+    routes = [],
+    config,
+    {ignoredRoutes = [], fuzzyPathMatching = false}
+) => {
+    if (!routes.length) return []
+    if (!config) return routes
+
+    let outputRoutes = []
+    const {url: urlConfig} = config.app
+
+    const allSites = getSites()
+    if (!allSites) return routes
+
+    if (fuzzyPathMatching) {
+        outputRoutes = configureRoutesWithFuzzyMatching(routes, urlConfig, allSites, ignoredRoutes)
+    } else {
+        outputRoutes = configureRoutesWithExplicitMatching(
+            routes,
+            urlConfig,
+            allSites,
+            ignoredRoutes
+        )
+    }
+
     return outputRoutes
 }

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

@@ -288,4 +288,181 @@ describe('configureRoutes', function () {
             expect(paths).toEqual(expectedRes)
         })
     })
+
+    describe('fuzzyPathMatching', function () {
+        // Expected patterns based on sites mock:
+        // Sites: uk (alias) / site-1 (id), us (alias) / site-2 (id)
+        // Locales: en-GB, fr (alias), fr-FR, it-IT (site-1), en-US, en-CA (site-2)
+        const sitePattern = 'uk|site-1|us|site-2'
+        const localePattern = 'en-GB|fr|fr-FR|it-IT|en-US|en-CA'
+
+        const fuzzyCases = [
+            {
+                urlConfig: {
+                    site: 'path',
+                    locale: 'path',
+                    showDefaults: true
+                },
+                expectedRes: [
+                    `/:site(${sitePattern})/:locale(${localePattern})/`,
+                    '/',
+                    `/:site(${sitePattern})/:locale(${localePattern})/category/:categoryId`,
+                    '/category/:categoryId'
+                ]
+            },
+            {
+                urlConfig: {
+                    site: 'path',
+                    locale: 'path',
+                    showDefaults: false
+                },
+                expectedRes: [
+                    `/:site(${sitePattern})/:locale(${localePattern})/`,
+                    '/',
+                    `/:site(${sitePattern})/:locale(${localePattern})/category/:categoryId`,
+                    '/category/:categoryId'
+                ]
+            },
+            {
+                urlConfig: {
+                    site: 'query_param',
+                    locale: 'path',
+                    showDefaults: true
+                },
+                expectedRes: [
+                    `/:locale(${localePattern})/`,
+                    '/',
+                    `/:locale(${localePattern})/category/:categoryId`,
+                    '/category/:categoryId'
+                ]
+            },
+            {
+                urlConfig: {
+                    site: 'query_param',
+                    locale: 'path',
+                    showDefaults: false
+                },
+                expectedRes: [
+                    `/:locale(${localePattern})/`,
+                    '/',
+                    `/:locale(${localePattern})/category/:categoryId`,
+                    '/category/:categoryId'
+                ]
+            },
+            {
+                urlConfig: {
+                    site: 'path',
+                    locale: 'query_param',
+                    showDefaults: true
+                },
+                expectedRes: [
+                    `/:site(${sitePattern})/`,
+                    '/',
+                    `/:site(${sitePattern})/category/:categoryId`,
+                    '/category/:categoryId'
+                ]
+            },
+            {
+                urlConfig: {
+                    site: 'path',
+                    locale: 'query_param',
+                    showDefaults: false
+                },
+                expectedRes: [
+                    `/:site(${sitePattern})/`,
+                    '/',
+                    `/:site(${sitePattern})/category/:categoryId`,
+                    '/category/:categoryId'
+                ]
+            },
+            {
+                urlConfig: {
+                    site: 'query_param',
+                    locale: 'query_param',
+                    showDefaults: true
+                },
+                expectedRes: ['/', '/category/:categoryId']
+            },
+            {
+                urlConfig: {
+                    site: 'query_param',
+                    locale: 'query_param',
+                    showDefaults: false
+                },
+                expectedRes: ['/', '/category/:categoryId']
+            },
+            {
+                urlConfig: {
+                    site: 'path',
+                    locale: 'path',
+                    showDefaults: true
+                },
+                expectedRes: [
+                    `/:site(${sitePattern})/:locale(${localePattern})/`,
+                    '/',
+                    '/category/:categoryId'
+                ],
+                ignoredRoutes: ['/category/:categoryId']
+            }
+        ]
+
+        fuzzyCases.forEach(({urlConfig, expectedRes, ignoredRoutes = []}) => {
+            test(`Should return parameterized routes with fuzzyPathMatching based on ${JSON.stringify(
+                urlConfig
+            )} config${
+                ignoredRoutes.length ? ` and ignore routes ${ignoredRoutes.join(',')}` : ''
+            }`, () => {
+                const config = {
+                    app: {
+                        url: urlConfig
+                    }
+                }
+                const configuredRoutes = configureRoutes(routes, config, {
+                    ignoredRoutes,
+                    fuzzyPathMatching: true
+                })
+                const paths = configuredRoutes.map((route) => route.path)
+                expect(paths).toEqual(expectedRes)
+            })
+        })
+
+        test('Should generate significantly fewer routes with fuzzyPathMatching enabled', () => {
+            const config = {
+                app: {
+                    url: {
+                        site: 'path',
+                        locale: 'path',
+                        showDefaults: true
+                    }
+                }
+            }
+
+            const explicitRoutes = configureRoutes(routes, config, {fuzzyPathMatching: false})
+            const fuzzyRoutes = configureRoutes(routes, config, {fuzzyPathMatching: true})
+
+            // Fuzzy matching should produce significantly fewer routes
+            expect(fuzzyRoutes.length).toBeLessThan(explicitRoutes.length)
+            // With 2 input routes, fuzzy should produce 4 (2 parameterized + 2 fallback)
+            expect(fuzzyRoutes).toHaveLength(4)
+        })
+
+        test('Should preserve route properties when using fuzzyPathMatching', () => {
+            const config = {
+                app: {
+                    url: {
+                        site: 'path',
+                        locale: 'path',
+                        showDefaults: true
+                    }
+                }
+            }
+            const configuredRoutes = configureRoutes(routes, config, {fuzzyPathMatching: true})
+
+            // All routes should have the component and exact properties preserved
+            configuredRoutes.forEach((route) => {
+                expect(route.component).toBeDefined()
+                expect(route.exact).toBe(true)
+            })
+        })
+    })
 })