Set an Environment Base Path (Pilot)

Environment Base Paths is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

If your store domain is backed by multiple Managed Runtime environments (MRT), use environment base paths to route requests to the correct environment. Set an environment base path for each environment to route requests via a CDN. Environment base paths are available starting in PWA Kit v3.12.

Prior to PWA Kit v3.12, routes that the application requires, such as /mobify paths, /callbacks, and other express routes, can only be accessed from the root of a domain. In a typical PWA Kit environment, the bundle assets and proxies are placed at the root level. For example, your environment can have its bundle assets accessed at https://pwa-kit.mobify-storefront.com/mobify/bundle/... and its proxies at https://pwa-kit.mobify-storefront.com/mobify/proxy/.... PWA Kit v3.12 introduces the concept of an environment base path that is added before all /mobify paths, /callbacks, and other express routes. For example, this URL contains the shop base path: https://pwa-kit.mobify-storefront.com/shop/mobify/proxy/....

An example use case for multiple MRT environments is an environment for each geographical location. You can create base paths for each location, such as location1 and location2, under your site's domain. This is an example of the bundle asset URL with the location1 base path, https://www.example.com/location1/mobify/bundle/..., and proxies URL with the location1 base path: https://www.example.com/location1/mobify/proxy/....

Storefront routes, which are handled by React Router, aren't affected by these changes.

  • PWA Kit version 3.12.0 or later
  • Commerce SDK React 4.0.0 or later
  • Retail React App 8.0.0 or later
  • A CDN, such as eCDN, set up in front of your Managed Runtime Environment (MRT)

Base paths is in pilot and has some limitations. Check out these limitations before enabling this feature.

  • Base paths aren't compatible with Storefront Preview.
  • When base paths are enabled, you must go through a CDN to access your MRT environment.
    • The storefront on your MRT remote environment isn't accessible directly.
    • If using eCDN, file a support request to update the eCDN URL rewrite rules. This request has a turnaround time of up to two weeks.

This section shows you how to set up an environment base path for your PWA Kit application.

The environment base path is applied to URLs required for the application to run, such as:

  • /mobify/... URLs: Includes /mobify/bundle/..., /mobify/proxy/... and so on.
  • /callback URLs: Includes SLAS callback urls used for authentication, password reset, and so on.
  • Express routes: Includes /worker.js and any custom express endpoints defined inside ssr.js.

Be aware that all of these endpoints are e-Commerce site and locale agnostic. The URLs service the same resource regardless of the base path.

The environment base path isn't added to application URLs that are defined with React Router. These URLs, which correspond to storefront pages and routes defined in route.jsx, can instead be set with a site ID or locale ID.

You can set an environment base path by specifying the envBasePath property inside your PWA configuration file.

For example, in config/default.js, you can set:

After you set the base path, start the local app and observe that your /mobify and express routes now include envBasePath in the URL.

After starting the app, the login calls don't work. The reason is because SLAS clients send requests to two fields, redirect_uri and callback_url, as part of the login process. The URLs you set to these fields must be updated to contain the base paths of your environments.

For example, if you have two environments with base paths of /shop and /store and your domain is www.example.com, set your SLAS client redirect_uri to:

www.example.com/shop/callback | www.example.com/store/callback

After updating your SLAS client redirect_uri and call_back_url fields, start the local app again and verify that your SLAS calls succeed.

Add the envBasePath property to all outbound /mobify and express routes.

Make sure you test your application. If you notice any URLs where the base path is missing, update the URL to include the environment base path via getEnvBasePath().

You can import the getEnvBasePath() by using this import statement.

For example, this is how getEnvBasePath() is used inside the _app-config.jsx file:

To set an environment base path for your remote Managed Runtime environment, you must update a few more configurations.

Each Managed Runtime environment can have its own PWA configuration file. These config files are in the same directory as default.js. The name of the configuration file must match the environment ID of your Managed Runtime environment.

For example, if your Managed Runtime environment ID is production, your config file will be named production.js.

Inside your environment config file, you can inherit and override properties from default.js as follows.

Managed Runtime environments expect incoming /mobify routes to go to the root.

As a result, you must have a CDN in front of your Managed Runtime environment. The CDN must rewrite any incoming /mobify requests to remove the base path before forwarding the request to Managed Runtime.

For example, if your envBasePath is set to /jp, in your CDN, your URL rewrite rule looks similar to the rule in this image.

URL rewrite rule

Make sure that your URL rewrite rules apply to the needed routes only, such as /mobify routes. Check that rewrite rules don't remove the base path, or any base path equivalent strings, from any URLs that you didn't add the environment base paths to in PWA.

Set up origin rules to route your domain and paths to the underlying Managed Runtime environments serving your site.

For example, your site can be accessed at www.example.com/jp and www.example.com/au and you want to route these URLs to the MRT environment apac-production.mobify-storefront.com. In addition, you have configured your envBasePath to be /apac-production. Your origin rule may look like:

Origin routing rule

When using origin routing rules to route requests with a base path to different environments along with URL rewrite rules, keep in mind your CDN’s order of operations.

You generally want to have the origin rule run before the URL rewrite rule so that you can determine which environment to route a request to before removing the base path.

In environments where the URL rewrite rules are applied before origin rules, such as eCDN and Cloudflare, update your origin rules to use the unmodified path, for example raw.http.request.uri.path rather than http.request.uri.path), to ensure your origin rule has access to the base path.

  • If your site ID and environment base path are the same, make sure that any URLs with a site ID don't also contain the environment base path and vice versa. For example, www.example.com/us/us/... is an invalid URL and isn't supported.
  • When defining custom express endpoints, don't set your endpoint’s first URI part to be equivalent to the base path. For example, app.get('/:basePath/:otherParam/test') isn't ideal because it can lead to the previously mentioned scenario.