@emartech/client-publish

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
• 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.

Configuration	CLI argument	ENV variable	Required	Type	Default value
Basic config
Target deploy environment	-e	DEPLOY_ENV	false	"staging", "production"	"staging"
Local directory to be deployed	-d	LOCAL_DIRECTORY	false	string	"dist"
Revision (version) of the deployed assets	-r	PROJECT_REVISION	false	string	current timestamp
Should a git tag be automatically created?	-t	—	false	boolean	false
S3/Redirector config
Should assets be deployed to Redirector?	—	REDIRECTOR_DEPLOY	false	boolean	true (before v6.0.0: false)
Project name / S3 folder name	—	REDIRECTOR_NAME	true	string	—
Redirector service URL	—	REDIRECTOR_URL	false	string	automatically determined based on target env
Redirector assets URL	—	REDIRECTOR_TARGET	false	string	automatically determined based on target env
Redirector API secret	—	REDIRECTOR_API_SECRET	true	string	—
S3 bucket to use	—	S3_BUCKET	false	string	automatically determined based on target env
S3 bucket ACL setting	—	S3_ACL	false	string	"public-read"
S3 bucket cache control	—	S3_CACHE_CONTROL	false	string	"max-age=315360000, no-transform, public"
AWS region	—	AWS_REGION	false	string	"eu-west-1"
AWS access key	—	AWS_ACCESS_KEY_ID	true	string	—
AWS secret for access key	—	AWS_SECRET_ACCESS_KEY	true	string	—
Cloudflare config
Should assets be deployed to Cloudflare?	—	CLOUDFLARE_DEPLOY	false	boolean	false
Cloudflare client name / R2 folder name	—	CLOUDFLARE_CLIENT_NAME	false	string	—
Cloudflare account ID	—	CLOUDFLARE_ACCOUNT_ID	false	string	—
Cloudflare R2 bucket name	—	CLOUDFLARE_R2_BUCKET	false	string	automatically determined based on target env
Cloudflare R2 access key	—	CLOUDFLARE_R2_ACCESS_KEY_ID	false	string	—
Cloudflare R2 secret for access key	—	CLOUDFLARE_R2_SECRET_ACCESS_KEY	false	string	—
Cloudflare KV store namespace	—	CLOUDFLARE_KV_NAMESPACE	false	string	automatically determined based on target env
Cloudflare KV auth token	—	CLOUDFLARE_KV_AUTH_TOKEN	false	string	—

revision

Gets the current or next suggested revision for the project

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

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 last revision (default: "")
  -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"
}

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

## STAGING WORKFLOW (snippet) ##
jobs:
  deploy:
    name: Deploy
    needs: [ build ]

    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 }}

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"
}