Documentation

This is the new documentation of Custom Applications. You can still visit the legacy documentation during the migration from Project-level Custom Applications.

Getting Started

Get up and running in a few steps and 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.

Installing 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.

Local development and login are only allowed for users being part of the Administrators Team of your Organization. Therefore, choose a Project that is part of an Organization where you are an administrator of.

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.

Note that Single Sign On is not supported at the moment for development. If you are interested in this functionality, let us know and open a support issue.

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

Configuring 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 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).