Route Requests to a Single MRT Environment with Environment Base Paths
Consider environment base paths when planning your storefront project with multiple Managed Runtime (MRT) environments and a single domain. To route requests to the correct MRT environment via eCDN, set up environment base paths for each MRT environment. Also, use an environment base path to host the storefront within a specific subpath of a website.
This example diagram shows that two base paths are set up for the www.example.com domain. Each base path points to a distinct MRT environment.

An organization with a single domain can host multiple storefronts for various uses. One example is offering a storefront for each locale. For example, Northern Trail Outfitters (NTO) has multiple locations and has multiple storefront URLs for each region. www.northerntrailoutfitters.com/us/retail is for the US region and www.northerntrailoutfitters.com/ca/retail is for the Canadian region. Set up two base paths: us and ca. Both URLs use the same domain, www.northerntrailoutfitters.com, but the base paths map them to distinct MRT environments.
If a storefront provides all locales within a single MRT environment, use multisite instead of base paths. See Configure Multisite URLs.
Another example is a website that hosts the storefront only in a subpath. For example, www.example.com is the main site with pages showing content. It contains one storefront that’s available under a specific path: www.example.com/shop. This path corresponds to an environment base path of /shop. The base path points to an MRT environment.
Configure base paths in config.server.ts under runtime.ssrParameters.envBasePath:
- Must be a single path segment starting with
/, such as/shopor/site-a. - Can contain a maximum of 63 characters after the leading slash.
- Can contain only URL-safe characters:
a-z A-Z 0-9 _ . + $ ~ " ' @ : -. - Can’t contain nested segments, such as
/a/b. - Can be empty or unset when no base path is needed.
The CDN routes traffic using only the first path segment. Restricting a base path to one segment keeps environment ownership unambiguous. For example, if both /foo and /foo/bar were valid base paths, the CDN couldn’t determine whether /foo/bar/p/123 belongs to /foo at route /bar/p/123 or to /foo/bar at route /p/123.
The base path flows through the system in the MRT_ENV_BASE_PATH environment variable.
| Environment | How MRT_ENV_BASE_PATH is set |
|---|---|
Development (pnpm dev) | Read from config.server.ts at startup. |
Preview (pnpm start) | Read from config.server.ts at startup. |
| Production (MRT) | Set by MRT Lambda from ssrParameters.envBasePath during pnpm push. |
The SDK reads this value through getBasePath(). Don’t set the environment variable directly.
React Router’s basename automatically prefixes page routes. With a base path of /shop, /p/25720052M is served at /shop/p/25720052M.
Bundle asset URLs also include the base path. Server rendering uses Vite’s renderBuiltUrl with MRT_ENV_BASE_PATH, the <Scripts> component supplies a base-path-aware window._BUNDLE_PATH in the browser, and preview mode patches the React Router build.
The SCAPI proxy is available only in development and preview. It remains mounted at its configured path, such as /mobify/proxy/api, without a base-path prefix. In production, the proxy is disabled and SCAPI calls go directly to the API. The server-side SCAPI client always calls the proxy at config.commerce.api.proxy directly, so the base path isn’t involved.
Resource routes used with useFetcher automatically include the base path. Raw browser fetch() and navigator.sendBeacon() calls must prepend it manually.
When multisite uses path-based site or locale detection, the SDK automatically offsets lookupFromPathIndex to skip the base-path segment. For /shop/site-us/en-US/c/womens, path index 0 still resolves to site-us; no detection configuration change is required. This applies to both resolveSite() and resolveLocale() path detection. Other detection methods (cookie, header, querystring) are unaffected.
The SDK implementation in storefront-next-dev reads process.env.MRT_ENV_BASE_PATH for server code, Vite plugins, and the CLI. The template implementation in src/lib/utils.ts reads the same variable on the server and extracts the path from window._BUNDLE_PATH in the browser. Both return the sanitized path, such as /shop, or an empty string.
In development and preview, the base path is read from config.server.ts; redirect middleware sends non-prefixed page requests to the prefixed path and leaves /mobify/ infrastructure paths unchanged. Preview also serves base-path-prefixed static assets and patches the React Router build manifest.
In production, MRT sets MRT_ENV_BASE_PATH but preserves the full URL when invoking the Lambda. React Router strips the basename for matching, redirect middleware redirects direct non-prefixed environment requests, and Vite generates asset URLs with the base path. An eCDN can route requests to the correct environment using that first path segment.
| Context | Base path behavior | Example |
|---|---|---|
useLocation(), useParams() | Stripped | /shop/p/123 becomes pathname: /p/123. |
useHref(), <Link>, <NavLink> | Automatically prepended | useHref('/p/123') becomes /shop/p/123. |
useFetcher | Automatically prepended | Fetcher URLs include the base path. |
redirect() in middleware | Not prepended | Manually prepend the base path. |
request.url in middleware and loaders | Not stripped | Contains the full URL, including the base path. |
The SDK handles the full request URL for multisite detection. Custom middleware that parses request.url must account for the base path.
Express routes mounted at fixed paths, such as /sfdc-health, are accessible without the base-path prefix but not with it. A request to /shop/sfdc-health falls through to React Router because Express route mounts don’t participate in React Router basename stripping.