@commercetools-frontend/application-cli/README.md

Internal CLI to manage Merchant Center application deployments across various environments.

# @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

```bash
$ 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.

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

The environments to compile the deployments for must be specified in a `storage-buckets` [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) file for example `storage-buckets.config.cjs` with the bucket region mapping to multiple environments. For example:

```js
/**
 * @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:

```txt
- 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:

```js
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:

```js
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](https://docs.commercetools.com/custom-applications/api-reference/application-config#mainmenulink) into a `menu.json` file.

> This is mostly useful for internal Merchant Center applications.

```bash
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.

```bash
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.

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