client-publish

Deployer for client side projects. Uploads the bundled client application to target distribution platform (Amazon S3/Cloudflare R2), and sets up redirection through the Redirector Service or version routing through the Client Version Worker.

Install

npm install @emartech/client-publish --save-dev

Usage

This package exposes a command called client-publish. This command line utility has several subcommands:

• deploy: Deploys assets to the given platforms
• rollback: Rolls back your client to an earlier version
• revision: Gets the current or next suggested revision for the project
• tag: Creates a new git tag for the project with a given revision
• merge: Merge master branch into production for production deploys

deploy

Deploys assets to the given platforms

Example usage:
  $ client-publish deploy --target-env production --revision 4.2.0 --create-tag

Options:
  -e, --target-env <env>     the target environment the deployment is for (choices: "staging", "production", default: "staging", env: DEPLOY_ENV)
  -r, --revision <revision>  the revision to use when deploying (default: current timestamp, env: PROJECT_REVISION)
  -t, --create-tag           create a git tag for the new revision (default: false)
  -h, --help                 display help for command

Configuration must be passed as command line arguments and/or environment variables on the CI/CD pipeline.

rollback

Rolls back a client to an earlier version

Example usage:
  $ client-publish rollback --revision 4.2.0 --target-env production

Options:
  -e, --target-env <env>     the target environment the deployment is for (choices: "staging", "production", default: "staging", env: DEPLOY_ENV)
  -r, --revision <revision>  the revision to rollback to (default: current timestamp, env: PROJECT_REVISION)
  -h, --help                 display help for command

revision

Gets the current or next suggested revision for the project

Example usage:
  $ client-publish revision --type git-tag --next
  $ client-publish revision --type git-tag --offset 1

Options:
  -t, --type <type>      the way to get the revision (choices: "env", "timestamp", "package", "git-tag", default: "timestamp")
  -n, --next             get the next revision based on conventional commit messages (default: false)
  -p, --prefix [prefix]  the prefix to use when searching for the latest revision (default: "")
  -o, --offset [offset]  the offset to use when searching for an earlier revision (default: 0)
  -h, --help             display help for command

tag

Creates a new git tag for the project with a given revision

Example usage:
  $ client-publish tag --revision 4.2.0 --prefix "v" --yes

Options:
  -r, --revision [revision]  the revision to use for the tag (env: PROJECT_REVISION)
  -p, --prefix [prefix]      the prefix to add to the version number (default: "")
  -y, --yes                  automatic yes to prompt (default: false)
  -h, --help                 display help for command

merge

Merges the `master` branch into the `production` branch

Example usage:
  $ client-publish merge --yes

Options:
  -y, --yes   automatic yes to prompt (default: false)
  -h, --help  display help for command

CI/CD configuration

Set up the following NPM scripts in your package.json. You can pass additional arguments (e.g. revision) to the client-publish command here.

"scripts": {
  "deploy:staging": "client-publish d -e staging",
  "deploy:production": "client-publish d -e production",
  "rollback:staging": "client-publish rb -e staging",
  "rollback:production": "client-publish rb -e production"
}

Usage with GitHub Actions

1. Enable the required deploy environments in your workflow file:

   • For Redirector: REDIRECTOR_DEPLOY
   • For Cloudflare: CLOUDFLARE_DEPLOY

2. Set the required environment variables in your workflow file:

   • For Redirector: REDIRECTOR_NAME
   • For Cloudflare: CLOUDFLARE_CLIENT_NAME

3. Map secrets to environment variables according to your target environment. The following secrets are available as organization secrets for the emartech organization so you don't have to set them:

   • For Redirector: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, REDIRECTOR_API_SECRET_STAGING, REDIRECTOR_API_SECRET_PRODUCTION
   • For Cloudflare: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_R2_ACCESS_KEY_ID, CLOUDFLARE_R2_SECRET_ACCESS_KEY, CLOUDFLARE_KV_AUTH_TOKEN, CLOUDFLARE_KV_NAMESPACE, CLOUDFLARE_KV_REPOSITORY_NAMESPACE

Deploy

## STAGING DEPLOY WORKFLOW (snippet) ##
jobs:
  deploy:
    name: Deploy (staging)
    needs: [ build ]
    runs-on: ubuntu-latest

    steps:
      - name: Deploy
        run: npm run deploy:staging

        env:
          REDIRECTOR_DEPLOY: true
          REDIRECTOR_NAME: my-project
          REDIRECTOR_API_SECRET: ${{ secrets.REDIRECTOR_API_SECRET_STAGING }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          CLOUDFLARE_DEPLOY: true
          CLOUDFLARE_CLIENT_NAME: my-project
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_R2_ACCESS_KEY_ID: ${{ secrets.CLOUDFLARE_R2_ACCESS_KEY_ID }}
          CLOUDFLARE_R2_SECRET_ACCESS_KEY: ${{ secrets.CLOUDFLARE_R2_SECRET_ACCESS_KEY }}
          CLOUDFLARE_KV_AUTH_TOKEN: ${{ secrets.CLOUDFLARE_KV_AUTH_TOKEN }}
          CLOUDFLARE_KV_NAMESPACE: ${{ secrets.CLOUDFLARE_KV_NAMESPACE }}
          CLOUDFLARE_KV_REPOSITORY_NAMESPACE: ${{ secrets.CLOUDFLARE_KV_REPOSITORY_NAMESPACE }}

Rollback

## STAGING ROLLBACK WORKFLOW (snippet)

on:
  workflow_dispatch:
    inputs:
      revision:
        description: Revision to rollback to
        required: true

jobs:
  rollback:
    name: Rollback (staging)
    runs-on: ubuntu-latest

    steps:
      - name: Rollback
        run: npm run rollback:staging -- -r ${{ github.event.inputs.revision }}

        env:
          REDIRECTOR_DEPLOY: true
          REDIRECTOR_NAME: my-project
          REDIRECTOR_API_SECRET: ${{ secrets.REDIRECTOR_API_SECRET_STAGING }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          CLOUDFLARE_DEPLOY: true
          CLOUDFLARE_CLIENT_NAME: my-project
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_R2_ACCESS_KEY_ID: ${{ secrets.CLOUDFLARE_R2_ACCESS_KEY_ID }}
          CLOUDFLARE_R2_SECRET_ACCESS_KEY: ${{ secrets.CLOUDFLARE_R2_SECRET_ACCESS_KEY }}
          CLOUDFLARE_KV_AUTH_TOKEN: ${{ secrets.CLOUDFLARE_KV_AUTH_TOKEN }}
          CLOUDFLARE_KV_REPOSITORY_NAMESPACE: ${{ secrets.CLOUDFLARE_KV_REPOSITORY_NAMESPACE }}

Usage with CodeShip

1. Set the required environment variables on your deploy pipeline: For Redirector:
   • REDIRECTOR_NAME
   • REDIRECTOR_API_SECRET_STAGING, REDIRECTOR_API_SECRET_PRODUCTION
   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY For Cloudflare:
   • CLOUDFLARE_CLIENT_NAME
   • CLOUDFLARE_ACCOUNT_ID
   • CLOUDFLARE_R2_ACCESS_KEY_ID
   • CLOUDFLARE_R2_SECRET_ACCESS_KEY
   • CLOUDFLARE_KV_AUTH_TOKEN

Set up deployment for master and production branch.

## MASTER BRANCH ##
export REDIRECTOR_API_SECRET=REDIRECTOR_API_SECRET_STAGING
# Run deploy scripts
npm run build
npm run deploy:staging

Legacy Usage (Deprecated)

For compatibility with older versions, this package also exposes four other commands:

• client-deploy: deploy application
• client-deploy-staging: sets defaults for staging and deploy application
• client-deploy-production: sets defaults for production and deploy application
• client-merge: merge and push to production from master

To use these commands, the environment variables in the Deployment Configuration section must be present. You can also use these commands NPM scripts.

"scripts": {
  "deploy-staging": "client-deploy-staging",
  "deploy-production": "client-deploy-production",
  "merge-production": "client-merge"
}