@commercetools-frontend/application-cli

This is a CLI used internally for Merchant Center applications. We do not provide any guarantees or support for the functionality. For normal Custom Applications development, the @commercetools-frontend/mc-scripts package should be good enough.

This CLI provides useful commands to work with Custom Applications that need to be deployed in a multi cloud environment.

Installation

$ npm install --save @commercetools-frontend/application-cli

Usage

Please make sure you have Node.js v14 or higher installed as this package uses native ES modules.

Command: compile-deployments

This command compiles the deployments for each of the given cloud environments.

pnpm application-cli compile-deployments \
  --build-revision=<git_sha>

The environments to compile the deployments for must be specified in a storage-buckets cosmiconfig file for example storage-buckets.config.cjs with the bucket region mapping to multiple environments. For example:

/**
 * @type {import('@commercetools-frontend/application-cli').TStorageBucketsConfig}
 */
module.exports = {
  'merchant-center-north-america': {
    cloudEnvironment: 'ctp_production_gcp_us-central1_v1',
    bucketEnvironment: 'ctp-gcp-production-us',
  },
};

The above configuration would compile for one environment in gcp-production-us with its respective region. Yielding a /deployments folder for the application with the following structure:

- gs
  - gcp-production-us
     - application.html
     - upload-index.sh
  - upload-assets-merchant-center-north-america.sh
  - upload-assets-merchant-center-asia.sh

1. The gs folder signals that these files will be uploaded to Google Storage which is the default storage provider
2. The upload-index.sh and upload-assets-<bucket>.sh scripts are generated pre-configured bash scripts for uploading the application.html and static assets to the respective storage bucket using gcloud storage.
3. The public folder contains shared static assets for all environments.
4. The application.html references the static assets from its respective environment's bucket

Depending on the environment you are deploying to, you need to:

• Upload the static assets using the upload-assets-*.sh scripts to all respective buckets.
• Upload the application.html using the upload-index.sh script. This is effectively the actual deployment of the application.

Additionally, when specifying the --dotenv-folder option, you can specify a dotenv file for each environment (for example .env.gcp-production-eu) and a single .env.production dotenv file. These files are then loaded when compiling the application for the respective environment.

The configuration also using a defineBucketConfig helper function to opt into defaults for bucket region and their environments:

const {
  defineStorageBucketsConfig,
} = require('@commercetools-frontend/application-cli');

module.exports = defineStorageBucketsConfig();

Given the configuration above upload scripts and application.html files would be generated for all default bucket regions and cloud environments. These can then be picked up by the CircleCI Orb for upload.

If you need to disable certain bucket regions or cloud environments, you can use the options parameter of defineBucketConfig:

You can disable existing bucket regions or environments:

module.exports =  defineStorageBucketsConfig({
  options: {
    disabledBucketRegions: ['merchant-center-north-america']
    disabledEnvironments: ['vw_production_aws_eu-central-1_v1']
  },
});

Command: compile-menu

This command compiles the menu configuration defined in the application config into a menu.json file.

This is mostly useful for internal Merchant Center applications.

pnpm application-cli compile-menu

Command: validate-menu

This command validates the menu.json file generated by compile-menu command.

This is mostly useful for internal Merchant Center applications.

pnpm application-cli validate-menu \
  --input-file=<filepath> \
  --navigation=top  #option to switch between navbar (side) and appbar schema (top)

Command: create-version

This command outputs a JSON string containing a list of deployed versions.

This is mostly useful for internal Merchant Center applications.

pnpm application-cli create-version \
  --version-url=https://cdn/version.json
  --build-revision=<git_sha>