Documentation

Custom Applications

Start developing Custom Applications for the Merchant Center.

Prerequisites

Before you start development, make sure to have the following:

  • A commercetools account and a Project.
  • Node.js installed (version 14.x, recommended >=16). Either yarn or npm as a package manager.
  • Basic knowledge of React, as well as some experience working with web applications.

Install a starter template

The easiest way to get started is to use one of the starter templates.

We recommend creating a new Custom Application using create-mc-app, which automatically sets up one of the starter templates for you.

npx @commercetools-frontend/create-mc-app@latest \
  my-new-custom-application-project \
  --template starter

To start with a TypeScript project, use the --template=starter-typescript flag. Read more about TypeScript in the Adding TypeScript page.

After the installation is complete, follow the instructions to start the development server:

cd my-new-custom-application-project


yarn start
# or
npm start

The browser opens a new tab pointing to http://localhost:3001. You are redirected to the login page of the Merchant Center where you need to enter your commercetools account credentials.

Once you're authenticated, you are redirected to the local development server and have access to the Project.

If you look at the URL structure of the Merchant Center, you notice that the URI path starts with the projectKey (the identifier of your commercetools Project) and the entryPointUriPath (the identifier of the Custom Application):

/:projectKey/:entryPointUriPath

Configure the Custom Application

One of the important parts of a Custom Application is the configuration file: custom-application-config.json. We recommend making yourself familiar the Custom Application Config.

By default the starter template is configured to use the HTTP APIs in the GCP-EU Region. If you plan to run the Custom Application in another environment, change the cloudIdentifier accordingly (see list of cloud identifiers).

User access for local development

To start developing your Custom Application locally, choose a Project belonging to an Organization in which you are a member of the Administrators Team.

As of version 22.5.0, you have the option of assigning granular permissions to teams to enable local development. For more information, see Granular permissions for local development.