npm for contributors - how to release npm packages

Distribute your npm package

This guide describes how to create and release your (open-source) software project, want to share it with the world and want a step-by-step instruction on how to publish this thing on npm?

• Distribute your npm package

  • Create a new npm package
  • Update an existing npm package
  • Add npm version badge in GitHub repo README
• Semantic Versioning overview

Create a new npm package

1. Create an npm account
2. Run $ npm login to login to your (newly created) npm account.
3. Run $ npm init to start a guided process to fill out fields like license, homepage, version etc.
4. Test your package locally by running $ npm install ../path/to/your/project from some other folder. Also check your install instructions in the README file - they will be displayed alongside the npm package on https://www.npmjs.com/.
5. Run $ npm publish to publish your package.
6. It may take a little bit until your package is live - then check it out on the npm homepage.

These steps were taken from this overview.

Update an existing npm package

My npm update routine for my open source projects.

1. Run npm version <update_type> (see this link) where <update_type> equals patch, minor, or major.

   Update types adhere to the principle of semantic versioning:

   • In a version 2.0.3, 2 is the major, 0 the minor and 3 the patch position.

2. Update the project’s CHANGELOG

   • Add a new entry for the new version you’re about to release
   • At the bottom of the CHANGELOG update the link of the unreleased version and create a link for your new version.
   • You don’t have a CHANGELOG.md file yet? - The CHANGELOG of the styled-component library might serve as a nice template. It’s the example which I follow in my open source projects.
3. Add this CHANGELOG change (and perhaps other changes) to the commit generated by the npm version command via git commit --amend.
4. Run npm publish to publish the update to the npm server from your local computer.

The npm part is done. Now we add a tag and release to GitHub:

5. Run git push to push your changes to GitHub.
6. Run git push origin --tags to push the newly created tag to the remote repository so that you can add release notes there.

7. Go to the Github page of the project, then to Releases on the right-hand side.

   • There to the Tags tab at the top. There click on the three dots ... on the right-hand side of the row with the new release tag and click on Create release.
   • As title pick your new version with a v in front, e.g. v2.9.0.
   • Click on Auto-generate release notes or add the created CHANGELOG entry as release notes plus anything else you want to say.

Note: In step 1 you can run npm version patch -m "Upgrade to %s for reasons" to update with a message.

Add npm version badge in GitHub repo README

1. Go to https://badge.fury.io/ and create your npm badge.
2. Copy the Markdown version of the generated badge and add it to your README.md file.

Example in case the package is called my-package:

[![npm version](https://badge.fury.io/js/my-package.svg)](https://badge.fury.io/js/my-package)

Semantic Versioning overview

In a package.json file you’ll encounter versions with ~ or ^. This is what it means:

Depending on whether you prepend ~, ^ or nothing to the version 2.0.3 the following jQuery (it’s just an example) package version will be installed when you run npm install or yarn in each case:

1. ~

   • "jQuery": "~2.0.3",: Most recent jQuery version up to patch release will be installed (i.e. 2.0.something)

2. ^

   • "jQuery": "^2.0.3",: Most recent jQuery version up to minor release will be installed (i.e. 2.something.something)
3. "jQuery": "2.0.3",: That particular jQuery version will be installed (i.e. 2.0.3 and nothing else)

In the package-lock.json or yarn.lock file you can check which exact version is installed.

For example here version 3.6.4 of the package core-js-pure is installed although the package.json file mentions ^3.0.0:

core-js-pure@^3.0.0:
  version "3.6.4"
  resolved "https://registry.yarnpkg.com/core-js-pure/-/core-js-pure-3.6.4.tgz#4bf1ba866e25814f149d4e9aaa08c36173506e3a"
  integrity sha512-epIhRLkXdgv32xIUFaaAry2wdxZYBi6bgM7cB136dzzXXa+dFyRLTZeLUJxnd8ShrmyVXBub63n2NHo2JAt8Cw==