BETA

Runtime Configuration

Merchant Center applications require a runtime configuration to work. This is useful for several reasons and for convenience to be able to deploy the application in different environments.

env.json

The configuration is defined in a file named env.json.

For development the env.json file must be in the root path of the project as it's automatically loaded by the Webpack dev server.

The following fields are required but you can provide additional fields specific to your application:

  • applicationName: the name of the application (usually the same as in package.json).
  • frontendHost: the host where the Merchant Center Custom Application is running. See Merchant Center hostnames.
  • mcApiUrl: the API URL for the Merchant Center API Gateway.
  • location: the location where the Merchant Center Custom Application is running. This value is used for logging and error reporting. Usually values refer to the cloud region where the Custom Application is running, for example gcp-eu, gcp-us, aws-ohio, etc.
  • env: the environment value where the Merchant Center Custom Application is running, usually production or development.
  • cdnUrl: the URL where the static assets are stored (see Serving Static Assets).
  • servedByProxy: a flag to indicate if the application is running behind the Merchant Center proxy router or not. This is either true for production and false for local development.

When the index.html.template gets compiled into index.html, the env.json is injected into a global variable window.app. This value should be used in the <EntryPoint> component when rendering the <ApplicationShell>.

const EntryPoint = () => (
<ApplicationShell
environment={window.app}
// other props
/>
);

The environment object is parsed and passed into a React Context, making it available to the entire application. To access it, use the @commercetools-frontend/application-shell-connectors package.

import { useApplicationContext } from '@commercetools-frontend/application-shell-connectors';
const MyComponent = () => {
const applicationName = useApplicationContext(
context => context.environment.applicationName
);
return (<div>{`Welcome to the application ${applicationName}!`}</div>);
};

An example configuration for local development:

{
"applicationName": "merchant-center-application-template-starter",
"frontendHost": "localhost:3001",
"mcApiUrl": "https://mc-api.commercetools.com",
"location": "eu",
"env": "development",
"cdnUrl": "http://localhost:3001",
"servedByProxy": false
}

Using environment variables

Values in an environment configuration JSON file can contain references to environment variables. This can be useful to avoid duplication between various env.json files for multiple different environments. References are specified with a special expansion like syntax ${} while additionally prefixing the environment variable name with env:.

For instance, imagine developing a Custom Application that can be used in the commercetools platform Europe region and North America region. We can assign the ${env:MC_API_URL} reference to the field mcApiUrl and pass the actual value using environment variables.

{
"cdnUrl": "https://bucket.com",
"mcApiUrl": "${env:MC_API_URL}"
}

The MC_API_URL environment variable can be provided in various ways. For example as an inline environment variable when running a script command (MC_API_URL=https://mc-api.commercetools.com yarn start), using a dotenv file or by defining the environment variables in your CI service.

You can also pass multiple references to the same value

{
"mcApiUrl": "https://mc-api.${env:CTP_REGION}.${env.CTP_CLOUD_REGION}.commercetools.com"
}

Production environment

When the application is deployed on a production environment, the application will fail to make requests to the API Gateway. This is due to the fact that the domain, where the application is hosted, is not whitelisted by the CORS rules of the API Gateway.

Therefore, it's important that the application is registered, runs behind the proxy router, and that the servedByProxy option in the env.json is set to true.

It is recommended to have two separate configuration files, one for development and one for production. The env.json must be used for development, therefore for production you can have an env.prod.json file.

headers.json

This configuration file allows to configure HTTP headers. The most important one is the Content Security Policy header.

For development the headers.json file is optional. If used, the file must be in the root path of the project as it's automatically loaded by the Webpack dev server.

Content Security Policy

The Content Security Policy (CSP) header allows to instruct the browser how to deal with security measures, according to the configured instructions. Most of the time it's enough to whitelist the hostnames that the Custom Application uses, for example if static assets are served by a CDN.

Since Custom Applications are hosted on any domain of your choice, it's imperative that any hostname used by the application is whitelisted in the CSP configuration. Furthermore, the API Gateway hostnames must also be listed in the CSP configuration.

For example, given that your application is hosted at my-app.now.sh and runs on the Google Cloud Europe region, the headers.json file must be configured as following:

{
"csp": {
"script-src": ["my-app.now.sh"],
"connect-src": [
"my-app.now.sh",
"mc-api.europe-west1.gcp.commercetools.com",
"mc-api.commercetools.com"
],
"style-src": ["my-app.now.sh"]
}
}

This example includes two hostnames as one of them is a legacy hostname: mc-api.commercetools.com. For more information read about Legacy hostnames.

You can find the list of default directives in the load-headers.js file in the @commercetools-frontend/mc-html-template package.

Production environment

It is recommended to have two separate configuration files, one for development and one for production. The headers.json must be used for development, therefore for production you can have a headers.prod.json file.

csp.json (deprecated)

This file has been deprecated by the headers.json.

To migrate to the new format, wrap the csp.json content into a csp property in the headers.json:

{
"csp": {
"script-src": ["my-apps.com"],
"connect-src": ["my-apps.com"],
"style-src": ["my-apps.com"]
}
}

Additionally, use the --headers over the --csp CLI option to point to the new headers.json.

NODE_ENV=production mc-http-server \
--headers=$(pwd)/headers.json \
--config=$(pwd)/env.json \
--use-local-assets
Developer Center
HTTP APIGraphQL APIBETAPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & Export ToolsSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Copyright © 2020 commercetools