Merchant-center-starter-app NPM

This is a playground application to develop and help testing some of the features from the application-kit packages.

Getting started

Before you jump into developing the application, there are some important information to know beforehand:

the project demonstrate how to set up and develop a Merchant Center Application
a Merchant Center Application is a runnable React application, developed and built using the mc-scripts package
- the mc-scripts start command will start a webpack development server
- the mc-scripts build command will bundle the production assets into the dist folder
the Merchant Center itself is composed by multiple applications running behind a proxy, each one of those serving a specific part of the overall Merchant Center (e.g. dashboard, products, discounts)
building a "custom" Merchant Center Application means building a new part of the overall Merchant Center, where eventually the "custom" app will be hosted by you and served from the proxy within the commercetools systems (more on that will come soon)
in order to have the same main structure and "bootstrap" logic across the different applications, we built a component called ApplicationShell that MUST be rendered by each application within their entry points
- the ApplicationShell contains among other things the NavBar component, where you see the "links" on the left-side menu
- the NavBar component is shared across all the different applications, and needs to contain the main links of all the applications
- the NavBar component by default only contains the links of the "official" applications (e.g. dashboard, products, discounts)
- for custom applications, links are stored in the Merchant Center API and loaded asynchronously for a specific project. This means that you can't "manually" add links to the NavBar but instead you need to configure them with the settings (more on that will come soon)
each Merchant Center Application usually defines ONE main route (e.g. in this example the application defines a /:projectKey/channels route)
- routes should always contain the /:projectKey, as those "custom" application belong to a certain project
- routes for "custom" applications should not conflict with the "official" routes (e.g. dashboard, products, etc), as "official" routes always take precedence
- routes can and should have sub-routes, dependening on how many levels/views the application should have (e.g. /:projectKey/channels/:id, /:projectKey/channels/new, etc)

Project structure

To get you familiar with a recommended project structure, we suggest to inspect the playground folder. Here are some important parts:

src contains all the JS files to build the application
- index.js is the application "entry point" and contains the basic imports to render the React app
- routes.js contains the sub-routes and components rendered by the application (the main route is defined in the <EntryPoint> and is loaded asynchronously using code splitting)
dist contains the production bundles (this is created once you run yarn build)
env.json contains the development config used by the webpack dev server (more on that will come soon)
env.prod.json is an example of the config used by running the application in production mode (see below Running in production)
csp.json contains additional directives for CSP, specific to the domain hosting the app (more on that will come soon)
webpack.config.<env>.js contains the setup for getting the webpack configurations for dev/prod (having those files is important as they are read by mc-scripts)

Development

The dependencies are installed from the root package, using yarn worskpaces.

To start the development server, run:

$ yarn start

A webpack server will start building the source codes and will open up a page in the browser. At this point you can start developing the app and webpack will reload the page whenever you make some changes.

The env.json file contains necessary config to run the application on localhost.

API domains

The MC runs on 2 different data centers: one in EU and one in US. Depending on which one you would like to target for your application, you need to adjust a couple of fields in the env.json file.

The MC API is available at the following domains:

for EU: https://mc-api.commercetools.com
for US: https://mc-api.commercetools.co

Running in production

To run the application in production mode, you need to take a couple of steps:

build the production bundles

$ yarn build

This will output a dist folder containing the JS bundles in the dist/assets subfolder. There is also a index.html.template which will be used to generate the final index.html with the bundle references (see below).

start the HTTP server (as Nodejs process)

The HTTP server comes shipped with the mc-http-server package and provides a binary to start the server (mc-http-server). The server will make sure to serve a valid index.html and it provides additional tools like security headers, etc.

To start the server, you need to provide the path to the config --config=$(pwd)/env.json file and --csp=$(pwd)/csp.json. The env.prod.json is for production usage.

In case you host the JS bundles on an external CDN, you need to point the cdnUrl in the env.json config to the URL serving the assets. However, if you keep the assets within the server itself, you need to pass different arguments to the command:

// Using an external CDN. In the `env.json` you should pass the URL pointing to the folder where
// the assets are stored.
{
  "cdnUrl": "https://my.cdn.com/path/to/folder/"
}

$ mc-http-server --config=$(pwd)/env.prod.json

In case assets are served from the same server, it's recommended to define the path to the server itself (including the host name)

// Not using an external CDN
{
  // this is the default, all assets are served from the root folder
  "cdnUrl": "https://localhost:3001",
  // this is the default, all assets are served from the root folder
  "cdnUrl": "https://localhost:3001"
}

$ mc-http-server --config=$(pwd)/env.prod.json --use-local-assets

start the HTTP server (as Docker image)

⏳ coming soon

Important notice

The application is not meant to be run as a standalone application, instead it should run behind a proxy within the MC environment (more info on that will follow soon).

Furthermore, the MC API used by the application has some strict CORS rules about the domains, which means that running the app as standalone from an random domain won't work.