How to publish a package to npm

npm is "the world’s largest software package repository. We use it to publish our modular code for re-use in projects with the node package manager, usually through a package.json file.

Creating an npm account

1. Create an account on to npmjs.com
2. Set up two-factor authentication
3. Tell an @cagov admin and we will add you to the organization.

Logging in to npm

• Before running the publish command you need to run

npm login

on your command line to establish a session

Publish a package

• The docs for the publish command: https://docs.npmjs.com/cli/v7/commands/npm-publish, the command we run is:

npm publish --access public

• All our npm packages are open source so our organization account is free. We have to pay if we want to publish private packages.
• The publish command needs to be run from the root of the component’s directory where its package.json is
• npm doesn’t allow anyone to unpublish things without contacting npm support anymore(since the left pad incident) so double check the name value in the package.json before publishing a new package
• In the @cagov/design-system repo, npm publish triggers a script which will push compiled packages to a CDN hosted on AWS. See the How to set up aws cli for instructions on how to set up your credentials.

Versioning

• Start brand new components using Semantic Versioning (semver) Example: 0.0.1.

Publishing beta versions

New versions can be tagged using https://docs.npmjs.com/cli/v7/commands/npm-dist-tags

This allows them to be installed only if the dist tag is specified on the install command so they can be tested from npm but people installing the package without specifying the tag won’t get the beta tagged version.

Workflow: - Publish a new version of a package and specify the tag beta

npm publish --tag beta

• Install everywhere you want to test specifiying the pagage@beta when installing
• When tests are complete the beta tag has to be removed from the latest npm package

npm dist-tag rm @cagov/your-package beta

• The package does not have to be version bumped again if no code changes are required
• But the latest tag will have to be manually reapplied after the beta dist tag has been removed from the latest version on npm

npm dist-tag add @cagov/[email protected] latest

Installing a package on a project

• To use your new package in a project folder, you will need to install it in package.json.

Check for package updates on a project

• We mostly use dependabot.