Runtime Configuration

env.json

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

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.europe-west1.gcp.commercetools.com",
  "location": "gcp-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.europe-west1.gcp.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

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 (CSP) header.

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. For example, to allow static assets to be served from a third-party Content Delivery Network (CDN).

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"]
  }
}

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

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 headers.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:APP_HOSTNAME} reference to the field csp object directives and pass the actual value using environment variables.

{
  "csp": {
    "script-src": ["${env:APP_HOSTNAME}"],
    "connect-src": [
      "${env:APP_HOSTNAME}",
      "${env:MC_API_HOSTNAME}"
    ],
    "style-src": ["${env:APP_HOSTNAME}"]
  }
}

The APP_HOSTNAME environment variable can be provided in various ways. For example as an inline environment variable when running a script command (APP_HOSTNAME=my-apps.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:

{
  "csp": {
    "script-src": ["my-apps.com"],
    "connect-src": [
      "my-apps.com",
      "mc-api.${env:CTP_REGION}.${env.CTP_CLOUD_REGION}.commercetools.com"
    ],
    "style-src": ["my-apps.com"]
  }
}

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)

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": [
      "${env:APP_HOSTNAME}",
      "${env:MC_API_HOSTNAME}"
    ],
    "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