Configure Multisite URLs

Storefront Next supports serving multiple B2C Commerce sites and locales from a single deployment. This configuration applies whether you operate a single site or multiple sites—in both cases, the multisite middleware handles site and locale resolution. Configure how site and locale identifiers appear in your URLs—in the path, as query parameters, or a combination of both. For single-site storefronts, you can omit identifiers from the URL entirely and let the middleware resolve everything from cookies and headers.

Multisite configuration controls how site and locale identifiers appear in your storefront URLs. The url config determines the URL pattern, and the detection config determines how the middleware reads site and locale back from incoming requests.

Configuration is in config.server.ts under three areas:

• commerce.sites defines the available sites and their supported locales.
• defaultSiteId determines the fallback site when no site can be resolved from the URL, cookie, or header.
• url defines the URL pattern, which includes the path prefix, query parameters, and excluded routes.

The Storefront Next template defaults to a convention where all URLs—including the homepage—use site and locale prefixes (for example, /global/en-GB/ for the homepage, /global/en-GB/product/123 for subpages). Requests to bare / are redirected server-side to the default site and locale prefix. This makes all URLs shareable and fully deterministic.

The bare / redirect is handled in the homepage loader (_app._index.tsx), so you can customize the redirect behavior as needed.

Sites and locales are defined under commerce.sites in config.server.ts. By default, sites and their locales are retrieved from the MRT Data Store. See MRT Data Store Sites. If the MRT Data Store sites option is turned off, sites and locales are retrieved from config.server.ts.

Each field serves a specific purpose:

• id — The B2C Commerce site ID. This must match the site ID configured in Business Manager.
• defaultLocale — The locale used when no locale can be resolved from the URL, cookie, or header.
• defaultCurrency — The fallback currency when no currency preference exists.
• supportedLocales — An array of locales available for this site. Each entry includes an id and a preferredCurrency that is applied when the user selects that locale.
• supportedCurrencies — The currencies available for manual selection on this site.
• defaultSiteId — Defined at the app level, this determines which site is used on a first visit when no site_id cookie exists.

On by default. When commerce.sitesFromDal is on, live site data synced through the MRT Data Store replaces the static commerce.sites for site, locale, and currency resolution, resolved per request. defaultSiteId, siteAliasMap, and localeAliasMap stay static and derived from config, never from the MRT Data Store. Set the flag to false to keep the static commerce.sites authoritative.

Fallback behavior. When the middleware can’t get site data from the MRT Data Store, the storefront keeps serving the static commerce.sites and doesn’t fail the request. This fallback applies whenever commerce.sitesFromDal is off, the MRT Data Store entry is unavailable, the payload yields no usable sites, or the usable sites omit the site named by defaultSiteId. That last case logs a warning naming the missing default and the site IDs actually present, so the issue is visible in monitoring.

URL aliasing stays config-owned. The MRT Data Store supplies which sites exist and their locale and currency data, but not how their URLs are aliased. siteContextMiddleware runs after the data store rewrite and derives each resolved site’s routing alias from the config siteAliasMap, keyed by site id (the same key for the data store and static sites), so siteAliasMap and localeAliasMap stay the config-owned source for the :siteId and :localeId URL refs. A per-site alias on the data store payload would be overwritten before routing reads it, so the rewrite drops it at the source. This is what keeps multi-site URLs stable when sites go live from the data store.

The url config in config.server.ts controls how multisite URLs are constructed.

• prefix — Path segments prepended to subpage URLs. Use :siteId and :localeId as placeholders that are replaced with the resolved values at URL build time.
• search — Query parameters appended to subpage URLs. Use the same :siteId and :localeId placeholder syntax.
• excludeRoutes — Glob patterns for routes that skip prefixing (e.g., API resource routes and server actions).
• seoRoutes — Business Manager-mirrored product, category, and optional standalone-content prefixes keyed by Commerce site ID. Prefixes are static segments without slashes. Category mode is id-suffix or slug-path.

Both prefix and search are optional. Use either, both, or neither depending on your URL strategy.

When url.search is configured, buildUrl injects the search params using searchParams.set(). This overwrites any existing query param with the same key, but preserves all other query params. For example, a product search URL like /product?q=shoes with search: '?lng=:localeId' resolves to /global/product?q=shoes&lng=en-GB—the existing q param is preserved and lng is appended. If your URL already contained a lng param, the configured value takes precedence.

When configured, seoRoutes registers the union of every site’s product, category, and content prefixes as static {prefix}/* routes. A build fails if a prefix is invalid, reserved, shared across resource types, or collides with another route branch. Product, category, and standalone-content route modules must be leaf routes when aliases are enabled.

Use the semantic builders for product, category, and standalone-content destinations. They return only the functional path; the storefront Link and navigation wrappers add the outer site and locale prefix.

Product builders preserve slug hierarchies, remove a terminal Commerce-generated .html suffix, and encode each path segment. If the product ID itself ends in .html, the builder emits .html.html; the resolver removes only the final extension and preserves the complete ID. In slug-path mode, use authoritative Category.slug or PathRecord.slug; don’t substitute an ID or display name. Category suggestions without an authoritative slug link to search by category ID instead. For merchant-authored legacy category paths, use createCategoryUrlFromLegacyPath().

Every active site must have an seoRoutes entry. Do not enable it until every site’s PDP and PLP grammar is decided. The slug-path mode requires Shopper Products 1.13 and Shopper Search 1.15.

Configuring content.prefix enables /{content-prefix}/content/{optional-slug-path}/{contentId} and /{content-prefix}/page/{optional-slug-path}/{pageId}. The explicit content or page segment selects the Shopper Experience API. A trailing .html is permanently redirected to the suffix-free canonical URL.

For a standalone Page Designer page with an above-the-fold region, expose a string criticalRegionId in the page type’s data and set it to that top-level region ID. The route marks only that region as critical; all other regions keep their streaming behavior.

Business Manager is the source of truth for SEO URL grammar. Map its product, category, category-mode, and optional content prefixes to the corresponding seoRoutes.<siteId> values. This mapping is manual: when a Business Manager setting changes, update config.server.ts, rebuild, and redeploy.

Keep Business Manager URL Rules, url.seoRoutes, and seoFallback.sites aligned. For an otherwise-unmatched GET or HEAD, the terminal route can make one Shopper SEO URL Mapping call without the incoming query string, retries, or mapping-chain traversal. Valid product, category, owned-content, URL redirect, and hybrid mappings redirect through the configured builders; mapping misses and rejected results remain 404 responses.

External redirect origins and forwarded query parameters are denied unless the active Commerce site explicitly allows them in seoFallback.sites. Origins must be exact HTTPS origins. contentOwned authorizes fallback mappings only; direct deterministic content routes don’t call URL Mapping.

Map B2C Commerce site IDs and locale IDs to shorter, URL-friendly aliases. Define these at the app level in config.server.ts.

With siteAliasMap, the site RefArchGlobal appears as global in URLs: /global/en-GB/product/123

With localeAliasMap, the locale en-GB appears as gb: /global/gb/product/123

Both alias maps are optional. Without them, the raw B2C Commerce IDs appear in URLs.

The URL config (prefix, search) controls how URLs are built. The detection config controls how site and locale are read back from incoming requests. These must stay in sync.

The default detection config is:

The middleware checks each source in the specified order and uses the first match.

Each field controls a specific detection behavior:

• order—The priority sequence for resolving the value. The middleware tries each source in order and uses the first match. For example, ['path', 'querystring', 'cookie', 'header'] checks the URL path first, then query parameters, then cookies, then HTTP headers.
• lookupFromPathIndex—Which URL path segment to read when 'path' is in the order. 0 means the first segment (e.g., /global/en-GB/... → 'global'), 1 means the second segment (e.g., /global/en-GB/... → 'en-GB').
• lookupQuerystring—The query parameter name to check when 'querystring' is in the order. For example, 'site' looks for ?site=global, and 'lng' looks for ?lng=en-GB.
• lookupCookie—The cookie name to check when 'cookie' is in the order. For example, 'site_id' checks the site_id cookie, and 'lng' checks the lng cookie.
• lookupHeader—The HTTP header to check when 'header' is in the order. For example, 'X-Site-Id' checks the X-Site-Id request header, and 'Accept-Language' checks the Accept-Language header.
• caches—Where to persist the resolved value. ['cookie'] means the resolved value is stored in a cookie for subsequent requests, ensuring consistency across page navigations.

The siteContext config in config.server.ts controls how site-context cookies are stored. Site-context cookies are site, locale, and currency cookies. The siteContext fields are optional.

• currencyCookieName—The cookie name used to persist the shopper’s selected currency. Defaults to 'currency'.
• cookieOptions—Cookie attributes that are applied to all three site-context cookies: site, locale, and currency. Valid options include httpOnly, maxAge, secure, sameSite, path, domain, and so on. These options follow the standard Cookie options from React Router. Defaults to { path: '/', sameSite: 'lax', secure: true, httpOnly: true }.

Below are common URL patterns you can achieve by combining prefix, search, and the corresponding detection config overrides. The available placeholders are :siteId and :localeId, which are resolved from the current site and locale, after alias mapping.

This is the default configuration. Both site and locale are visible in every URL, including the homepage. The default detection config expects site at path index 0 and locale at path index 1, which matches this pattern. No detection config override is needed.

Best for: Most multisite storefronts. Clean, fully deterministic URLs.

With this pattern, the site is resolved via the detection fallback chain. You must update localeDetectionConfig to set lookupFromPathIndex: 0, because the locale is now the first path segment instead of the second. It is also recommended to explicitly remove 'path' from siteDetectionConfig.order so that the middleware does not attempt to interpret the locale string (for example, en-GB) as a site ID.

Best for: Single-site storefronts with multiple locales, or when the site is determined by cookie or domain.

The site is resolved from path index 0. Because the locale is not in the path, remove path from its detection order so the middleware reads ?lng= before falling back to the cookie or header.

Best for: Shorter path segments while keeping locale in the URL for shareability.

Without a prefix, React Router doesn’t need site or locale route params in its route definitions. Remove path from both detection orders so the middleware reads the query parameters before cookies or headers.

Best for: Storefronts that want clean paths and don’t mind query params.

Remove path from both detection orders. The locale resolves from ?lng= and the site resolves from the query string when configured, then from the cookie or header.

Best for: Single-site storefronts that want locale-aware URLs without path changes.

This configuration produces the cleanest possible URLs with no site or locale identifiers at all. The multisite middleware still runs, but it resolves site and locale entirely from cookies and headers using the detection fallback chain. On a first visit with no cookies, the defaultSiteId and defaultLocale values from config.server.ts determine which site and locale are used.

Remove path from both detection orders because neither value is represented in the URL path. With one site and one locale, the defaults are used on the first visit and persisted in cookies for subsequent requests.

Best for: Single-site, single-locale storefronts that don’t need site or locale identifiers in the URL.

The Storefront Next template includes built-in switcher components for site, locale, and currency. Each switcher posts to the /action/set-site-context server action, which sets the appropriate cookies and redirects to the updated URL.

The site switcher component is at src/components/site-switcher. When a shopper selects a new site:

1. The dropdown calls i18n.changeLanguage with the default locale of the new site.
2. A POST is submitted to /action/set-site-context with the new siteId and localeId.
3. The server action sets the site_id and lng cookies and issues a redirect.
4. The page reloads with the new site and locale applied.

The locale switcher component is at src/components/locale-switcher. When a shopper selects a new locale:

1. The current URL path is stripped of its site/locale prefix using stripPathPrefix.
2. The new URL is rebuilt with the updated locale using buildUrl.
3. i18n.changeLanguage is called with the new locale string.
4. A POST is submitted to /action/set-site-context with the updated localeId.
5. The server action sets the lng cookie.
6. React Router triggers a full loader revalidation so all page data is reloaded with the new locale context.

When a shopper selects a currency, the currency switcher posts the new currency to /action/set-site-context, which stores it in the currency cookie (default name: currency). React Router then automatically revalidates all loaders, updating prices across the page.

The active currency is resolved using the following priority order:

Use useSite() to access the current site, language, and currency in React components:

useSite() throws if called outside a SiteProvider. In the template, SiteProvider is mounted in root.tsx and wraps the entire app.

Storefront Next provides multisite-aware navigation utilities that automatically prepend the active site and locale prefix to every URL. Always use these instead of the standard React Router equivalents.

Import Link and NavLink from @/components/link instead of from React Router. These components are drop-in replacements that automatically prefix paths with the active site and locale.

External URLs are passed through unchanged. Object to values with rooted pathnames are site-prefixed. Search-only strings and pathname-less objects with search resolve against the current route before URL context is applied. Empty, hash-only, and relative object targets retain React Router’s native resolution.

Import useNavigate from @/hooks/use-navigate instead of from React Router. The returned navigate function applies the site and locale prefix automatically.

Use the useCurrentSiteAndLocaleRef hook when you need to build URLs manually outside of Link or useNavigate:

React Router’s <Form> component does not go through buildUrl. If you pass an action prop to <Form>, you must prefix it manually:

All redirect() calls in loaders and actions must include the site-context prefix. Use buildUrlFromContext, which reads the resolved site and locale from router context.

Engagement adapters are initialized once at application startup with static configuration from config.server.ts. The current site and locale are injected at event-send time through EventSiteInfo, resolved from the site-context middleware.

useAnalytics gets the active { site, language } from useSite(), constructs { siteId: site.id, localeId: language }, and passes it to the event mediator for every tracking call.

Engagement adapter configuration is protected. To change it, update config.server.ts, rebuild, and redeploy.

1. Homepage URL uses site and locale prefix. All URLs—including the homepage—use the configured site and locale prefix (e.g., /global/en-GB/). Requests to bare / are redirected server-side to the default site and locale prefix. This redirect is handled in the homepage loader (_app._index.tsx) and can be customized.

2. URL configuration changes require a rebuild. url.prefix, url.excludeRoutes, and url.seoRoutes are protected paths. They can’t be changed via PUBLIC__ environment variables. Update config.server.ts and rebuild the application.

3. Keep URL construction and detection synchronized. When a site or locale is no longer represented in the path, remove path from that value’s detection order. When path indexes or query parameter names change, update the corresponding detection configuration.

4. Query param keys are not arbitrary. The locale query param key must be lng (matching the i18next cookie). The site key defaults to site. Custom keys require matching updates to the detection config.

5. Use multisite-aware navigation. Always use Link and NavLink from @/components/link, useNavigate from @/hooks/use-navigate, and buildUrlFromContext for server-side redirects. These automatically apply the URL prefix. Using React Router’s Link or redirect directly produces URLs without the prefix, resulting in 404 errors.

   In loaders and actions, use buildUrlFromContext from @/lib/url.server to build redirect URLs:

6. Keep i18n and site config in sync. The locale IDs in your i18n.supportedLngs must match the id values in commerce.sites[].supportedLocales. A mismatch causes the locale switcher to show unsupported locales or hide valid ones.

7. Always include framework routes in excludeRoutes. The /resource/** and /action/** patterns must remain in excludeRoutes. Removing them causes resource routes and server actions to be incorrectly prefixed with site/locale segments.

8. Prefix React Router Form action values manually. React Router’s <Form> component does not go through buildUrl. If you use <Form action="/some-path">, prefix the action yourself using buildUrl with useConfig and useCurrentSiteAndLocaleRef. See Navigate with Site Context for a code example.

• Project Configuration
• Internationalization
• Configure SEO-Friendly Storefront URLs