Documentation
All Release Notes

Migrate Custom Applications to the new host naming scheme

10 June 2020
Composable Commerce
Merchant Center Customizations
Announcement
Merchant CenterConfiguration

Recently we introduced a new host naming scheme for the commercetools APIs, including the Merchant Center, to increase region and cloud provider transparency.

While the previous hostnames such as *.sphere.io (Google Cloud, Belgium), *.commercetools.com (Google Cloud, Belgium), and *.commercetools.co (Google Cloud, Iowa) continue to be operational, we strongly recommend to migrate to the new hostname structure.

In regards to Custom Applications, the runtime configuration needs to be updated to support both the new and the legacy hostnames to allow users to log in with the new Merchant Center hostname, and to be backwards compatible with the legacy hostnames.

If you are using the [new application config file][/development/application-config], you can ignore the migration steps as the hostnames are automatically configured.

Here are the steps to take.

1. Update dependencies

Make sure that the application kit dependencies are updated to at least version >= 16.2.1, in particular the @commercetools-frontend/application-shell package. This is important to ensure that certain functionalities related to the hostname migration are available.

To update all the application kit packages to a specific version, you can use the following script:

npx bulk-update-versions \
  --match '^@commercetools-frontend/(?!ui-kit)(.*)' \
  --force-latest


yarn install

The bulk-update-versions script with the --force-latest option bumps all packages matching the specified pattern to their latest version.

If you are upgrading the application kit packages from older versions prior to v16, follow the instructions in the changelogs.

2. Update the env.json

Change the mcApiUrl in the env.json to use the new hostname.

For example:

Changing the hostname for GCP EUjson
{
  "applicationName": "merchant-center-application-template-starter",
  "frontendHost": "localhost:3001",
  "mcApiUrl": "https://mc-api.europe-west1.gcp.commercetools.com",
  "location": "eu",
  "env": "development",
  "cdnUrl": "http://localhost:3001",
  "servedByProxy": false
}

In production, the <ApplicationShell> takes care of inferring the correct Merchant Center Gateway API hostname based on the Merchant Center hostname that the user is logged into. This results in the Custom Application to work in both new and legacy hostnames, even though the mcApiUrl is configured to a specific value.

This feature is available from version 16.2.1 onwards.

3. Update the headers.json

Update the Content Security Policy to allow both new and legacy hostnames.

For example:

Updating the Content Security Policy for GCP EUjson
{
  "csp": {
    "script-src": ["my-app.vercel.app"],
    "connect-src": [
      "my-app.vercel.app",
      "mc-api.europe-west1.gcp.commercetools.com",
      "mc-api.commercetools.com"
    ],
    "style-src": ["my-app.vercel.app"]
  }
}

4. Re-deploy the Custom Application

That's it. Re-deploy the Custom Application with the updated configuration. Users can now access the Custom Application using both new and legacy hostnames (for backwards compatibility).