Configuration Files

With configuration files, you can customize many aspects of how your PWA Kit application works, including: API access, URL formatting, handling multiple sites, request proxying, and server-side rendering.

A configuration file can be written in your choice of JavaScript, YAML, or JSON. The following file extensions are supported: .js, .yml, .yaml, and .json.

When a PWA Kit project is created with the Retail React App template, it comes with a single configuration file: /config/default.js. The configuration objects that it exports are set based on the options provided to pwa-kit-create-app, but you can update your configuration at any time. Updates are often necessary after the initial project generation to stay in sync with changes to B2C Commerce instances.

To support isomorphic rendering, configuration values are serialized to page. Don't place secrets in your configuration!

You can replace default.js or complement it with additional configuration files because PWA Kit supports environment-specific configurations, which are covered later in this guide.

Let's start by looking at the specific configuration objects and properties available in default.js or any configuration file.

The project string that associates your application with Managed Runtime is not part of a configuration file, but can be found in the name property at the top of the package.json file at the root of your project directory. After initial project generation, you can change the value of name to match the project ID that you see in Runtime Admin.

Before version 1.5.0 of PWA Kit, these settings were in api.config.js.

To configure access to the B2C Commerce API and Open Commerce API (OCAPI), you can edit the app.commerceAPI object that is exported from the configuration file.

Here's an annotated code snippet with example values:

To configure access to the Einstein API, you can edit the app.einsteinAPI object.

Here's another annotated code snippet with example values:

For more information on the CommerceAPI class that consumes the configuration object in the previous code snippet, see our architecture guide to The Retail React App.

For more information on the setup tasks in Account Manager and Business Manager to enable API access for a B2C Commerce instance, see our guide to Set Up API Access.

You can customize how storefront URLs are formatted in the app.url object.

The app.url object is configured with the following values by default:

With these defaults settings, both the current site and locale are displayed in the URL path.

You can choose how the current locale appears (or doesn’t appear) in the URL by setting url.locale to one of the following values:

  • path: Locale is included in the URL path. Example: /en-US/women/dress
  • query_param: Locale is included as a query parameter. Example: /women/dress?locale=en-US
  • none: Locale isn’t included in the URL. Example: /women/dress

url.showDefaults: This boolean value dictates whether the default site or locale values are shown in the url. Defaults to: false.

We extract the sites configured for your application into its own file called config/sites.js. This file is imported into each configuration file and exported within the app object. Separating the files this way allows you to more easily synchronize the sites supported by your application and the sites defined in your Business Manager backend. (You can define your sites directly in the configuration file, if you prefer.)

The app object also contains other settings for managing multiple sites and their aliases. These settings are covered in more detail in our guide to Multiple Sites.

Request proxying is configured in the ssrParameters.proxyConfigs array, which is covered in detail in our guide to Proxying Requests.

Before version 1.5.0 of PWA Kit, these settings were in package.json.

The following table highlights the configuration options related to server-side rendering. These options are not part of the app object and are expressed as individual properties of the main exports object.

Property Description
ssrParameters.ssrFunctionNodeVersion String that determines which version of Node to use for running the App Server.

Allowed values: Supported Node version

ssrEnabled Boolean that enables or disables building the files necessary for server-side rendering. Setting this value to false is deprecated as of August 2021.
ssrOnly Array of glob expressions where * is a wildcard matching zero or more instances of any character.

Determines which files are available exclusively to the server-side rendering system and are not available through the /mobify/bundle/ path.

Defaults for a newly generated project: ['ssr.js', 'ssr.js.map', 'node_modules/**/*.*']
ssrShared Array of glob expressions where * is a wildcard matching zero or more instances of any character.

Determines which files are available to the server-side rendering system and available through the /mobify/bundle/ path.

Defaults for a newly generated project:

You can include multiple configuration files in the config directory, including configuration files for specific environments.

Environment-specific configurations can make your deployments more efficient and flexible. For example, you can:

  • Deploy a single bundle to multiple Managed Runtime environments and have each of environment connect to a different B2C Commerce instance.
  • Connect to your own on-demand sandbox during local development but connect to different instances when deployed to Managed Runtime.

To create an environment-specific configuration file, follow the same conventions used in default.js, but use the name of the target environment as the base name of the file. Use any of the supported file formats and the corresponding file extension. Examples: production.js, staging.json.

A PWA Kit application chooses the right configuration file to load by searching the config directory and asking the following questions, in the following order:

  1. Is there a file that matches the name of the currently running environment on Managed Runtime?
  2. If it's running locally, is there a file called local with a supported file extension?
  3. If no configuration file has been found yet, is there a file called default with a supported file extension?

As soon as the answer to one these questions is "Yes," PWA Kit stops looking and loads the file in question.

If two files have the same base name but different file extensions, the file extension with the highest assigned precedence is chosen. The supported file extensions are assigned precedence in the following order, ranging from highest to lowest precedence: .js, .yml, .yaml, or .json. That means that between default.js and default.json, PWA Kit would load default.js because it has the higher precedence.