@emartech/client-publish

client-publish

Deployer for client side projects. Uploads the bundled client application to target distribution platform (Firebase and/or Amazon S3) and sets up redirection for S3 deploys through the Redirector Service.

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
Firebase config
Should assets be deployed to Firebase?	—	FIREBASE_DEPLOY	false	boolean	true (before v5.0.0: false)
GCP project for Firebase Hosting	—	FIREBASE_PROJECT	true (1)	string	—
Name of the Firebase Hosting site to use	—	FIREBASE_SITE	true (1)	string	—
Service account credentials (JSON) for deployer user	—	FIREBASE_CREDENTIALS	true (1)	string	—
File where the service account credentials will be stored temporarily (3)	—	GOOGLE_APPLICATION_CREDENTIALS	true (1)	string	no default, use: "credentials.json"
S3/Redirector config
Should assets be deployed to Redirector?	—	REDIRECTOR_DEPLOY	false	boolean	false (before v5.0.0: true)
Project name / S3 subdirectory name	—	REDIRECTOR_NAME	true (2)	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 (2)	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 (2)	string	—
AWS secret for access key	—	AWS_SECRET_ACCESS_KEY	true (2)	string	—

(1): unless Firebase deploy is disabled
(2): only if Redirector deploy is enabled
(3): must be set as an environment variable for the Firebase deploy tool to work

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. Set up your secretes in the "Actions secrets" interface:
   • FIREBASE_CREDENTIALS_STAGING, FIREBASE_CREDENTIALS_PRODUCTION
   • The AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, REDIRECTOR_API_SECRET_STAGING, REDIRECTOR_API_SECRET_PRODUCTION are added as Organization secrets for the emartech organization.
2. Set the required environment variables in your workflow file:
   • FIREBASE_PROJECT
   • FIREBASE_SITE
   • REDIRECTOR_NAME (optional)

Map secrets to environment variables according to your current environment:

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

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

    env:
      FIREBASE_PROJECT: my-project
      FIREBASE_SITE: my-project
      FIREBASE_CREDENTIALS: ${{ secrets.FIREBASE_CREDENTIALS_STAGING }}
      # Optional ENV vars for S3/Redirector deployment
      REDIRECTOR_DEPLOY: true  # Required for Redirector deploy after v5.0.0
      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 }}

Usage with Codeship

1. Set the required environment variables on your deploy pipeline:
   • FIREBASE_PROJECT_STAGING, FIREBASE_PROJECT_PRODUCTION
   • FIREBASE_CREDENTIALS_STAGING, FIREBASE_CREDENTIALS_PRODUCTION
   • FIREBASE_SITE_STAGING, FIREBASE_SITE_PRODUCTION
   • REDIRECTOR_NAME (optional)
   • REDIRECTOR_API_SECRET_STAGING, REDIRECTOR_API_SECRET_PRODUCTION (optional)
   • AWS_ACCESS_KEY_ID (optional)
   • AWS_SECRET_ACCESS_KEY (optional)

Set up deployment for master and production branch.

## MASTER BRANCH ##
export FIREBASE_PROJECT=FIREBASE_PROJECT_STAGING
export FIREBASE_SITE=FIREBASE_SITE_STAGING
export FIREBASE_CREDENTIALS=FIREBASE_CREDENTIALS_STAGING
# Optional ENV vars for S3/Redirector deployment
export REDIRECTOR_DEPLOY=true  # Required for Redirector deploy after v5.0.0
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"
}