Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

CLI

The CLI of Custom Views allows you to start and build your Custom View.

Installation

yarn add @commercetools-frontend/mc-scripts

You could also install the CLI globally, but we recommend local installation instead.

Commands

start

This command starts the application in development mode. It uses Webpack Dev Server with hot-code reloading, error reporting, and more.

mc-scripts start

By default the application starts at http://localhost:3001.

build

This command bundles the application in production mode and creates an optimized production build of your application in the public folder.

mc-scripts build

By default, the build command compiles the index.html, included in the public folder. You can opt-out of the compilation step by using the option --build-only. See Going to Production for more information.

Options

  • --build-only: Generates production bundles without compiling the index.html. To compile it, run compile-html.

compile-html

This command compiles the index.html.template file into an index.html file according to the Custom View config. The production assets are then copied to the public folder and are ready to be deployed.

mc-scripts compile-html

See Going to Production for more information.

By default, compiling the index.html is implicitly done in the build command, unless the option --build-only is used. In that case, you need to execute the compile-html command separately.

Options

  • --transformer <path>: the path to a JavaScript module exporting a function. This can be used as a way to programmatically configure something based on the compiled information, for example, related to your deployment or hosting provider. The function is called with the following signature.

    type TransformerFunctionOptions = {
      // The runtime environment specified within the Custom View config.
      env: Json;
      // The compiled HTTP headers, including the Content-Security-Policy headers.
      headers: Json;
      // The final HTML content of the `index.html`.
      indexHtmlContent: string;
    }
    type TransformerFunction = (options: TransformerFunctionOptions) => void;

serve

This command starts a HTTP server to serve the previously built and compiled Custom View, from the public folder. This is useful for testing the production build locally.

mc-scripts serve

We recommend to set up the following scripts in your package.json:

package.jsonjson
{
  "scripts": {
    "compile-html:local": "MC_APP_ENV=development mc-scripts compile-html --transformer @commercetools-frontend/mc-dev-authentication/transformer-local.js",
    "start:prod:local": "yarn compile-html:local && mc-scripts serve"
  }
}

By default the application starts at http://localhost:3001.

login

This command enables users to log in to their Merchant Center account through the CLI. An interactive prompt will be displayed asking the user to enter the login credentials.

Upon login, an API token is generated and stored. The API token will be used by other CLI commands that require a valid API token.

mc-scripts login

The command uses the cloud Region environment information from the Custom View config. The API tokens are stored separately for each cloud Region.

config:sync

This command allows users to synchronize the local Custom View config with the Merchant Center. The sync implies that a new Custom View will be created or an existing one will be updated.

Developers can use the config:sync command to automatically manage the configuration of a Custom View from the config file instead of having to manually fill out the information in the Merchant Center.

If a new Custom View needs to be created, an interactive prompt will ask the user to select the Organization where the Custom View should be configured to.

Additionally, after creating a new Custom View using the config:sync command, you must add the generated Custom View ID to the Custom View config file, following the instructions in the terminal.

Note that this command requires a valid API token. You can get one by using the mc-scripts login command.

mc-scripts config:sync

The command uses the cloud Region environment information from the Custom View config.

Using dotenv files

The mc-scripts CLI has the dotenv features built-in.

By default, the following dotenv files are loaded according to the current environment values specified on each command: process.env.MC_APP_ENV or process.env.NODE_ENV. The files are merged and overwritten prioritized from top to bottom (highest defined variable overrides lower).

  • .env.development.local, .env.test.local, .env.production.local: local overrides of environment-specific settings.
  • .env.development, .env.test, .env.production: environment-specific settings.
  • .env.local: local overrides. This file is loaded for all environments except test.
  • .env

Please refer to the dotenv documentation for more details.

Furthermore, you can pass additional dotenv files by using the following option:

  • --env <path>: Parses the file path as a dotenv file and adds the variables to the environment. Multiple flags are allowed.

These files will take higher priority over the standard environment dotenv files.