Commit-publish-template NPM

Package template with CI/CD using Travis CI

Objectives

We want to use Travis CI to build and publish packages to NPM to ensure the build is consistent and tested in a clean environment.

We want to use NPM dist-tags to encourage user to try out latest build, by simply running npm install your-package@master.

We want to make sure every official packages, not pre-releases, will be tagged by GitHub Release.

We depends on version-from-git to bump package version based on Git branch/commit, like 1.0.0-master.1a2b3c4.

Setup your package

You will need to setup:

Setup your project

Download .travis.yml and save under your package.

curl -o .travis.yml https://raw.githubusercontent.com/compulim/commit-publish/master/.travis.yml

Enable Travis CI

Enable Travis CI first so we can use the per-project public key to encrypt secrets.

Visit your Profile page on Travis
Click "Sync account"
Enable Travis CI for your project

You may want to "Limit concurrent jobs" to 1 if you tend to push tags and commits quickly

Update NPM token

NPM token is required to run npm publish.

Run npm token create and write down the GUID token
Encrypt the token thru this webpage
Modify .travis.yml
- Set deploy.npm.api_key.secure to the encrypted token
- Set deploy.npm.email to your NPM email

Update GitHub token

GitHub token is required to create release automatically.

On GitHub, create a personal access token with access to repo/public_repo scope
Encrypt the token thru this webpage
Modify .travis.yml
- Set deploy.releases.api_key.secure to the encrypted token
- Set deploy.releases.email to your NPM email

Deployment

Now, you can do two types of deployment:

Deploy as pre-release

When your GitHub master branch receive a commit, either by accepting pull requests or pushing to master. Travis CI will build and publish to NPM automatically.

Deploy as production release

We follow NPM standard steps to deploy a release.

Run npm version 1.0.0
Run git push origin v1.0.0, this only push to a new tag and not master branch

You should see the following:

$ npm version 1.0.0
v1.0.0

$ git push origin v1.0.0
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 494 bytes | 247.00 KiB/s, done.
Total 5 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
To https://github.com/compulim/your-package.git
 * [new tag]         v1.0.0 -> v1.0.0

Release verification

Visit GitHub Releases should show 1.0.0 release with binaries attached
Run npm show your-package versions should list 1.0.0
Run npm dist-tags ls your-package should tag 1.0.0 as latest

Post-publish steps

Assume you published production release 1.0.0, you may want to prepare for the next pre-release immediately. Otherwise, your next push to master branch could be tagged incorrectly as 1.0.0-master.*, instead of 1.0.1-master.*.

Run npm version prepatch
Run git push

$ npm version prepatch
v1.0.1-0

$ git push
Total 0 (delta 0), reused 0 (delta 0)
To https://github.com/compulim/your-package.git
   a9c47a7..d053fa6  master -> master

Addendum

Encrypting token using Docker

You can also use Docker image caktux/travis-cli to do the encryption. Run docker run --rm caktux/travis-cli encrypt 12345678-1234-5678-abcd-12345678abcd -r your-org/your-repo