publishing-an-npm-package.md

Publishing an NPM package

Here's what I do when I publish an NPM package.

1: Make sure you're up to date

I always like to check what's going on in a repo before I do anything:

clear && ls -G && echo '------' && git status && echo && git branch -v && echo

Then if I need to commit anything, then do that. If any files need to be added, add them (e.g. git add .) before committing.

Next, I like to pull to make sure I'm up to date:

git pull

Finally, I like to push everything before proceeding, just to keep things simple:

git push

2. Tag the release

The NPM command-line tool comes with this neat utility called npm version. When you run it, it will automatically increment the version in the package.json file, make a git commit (locally), and make a new git tag (locally.)

For example:

npm version patch

There are three ways to use npm version, and the right way depends on what kind of changes were made since the last release:

Command to run	What changed?	Example
npm version patch	Just a bug fix- the package can be used exactly the same as before, and the behavior is the same. No breaking changes and no new functionality.	0.0.9 would become 0.0.10; 153.2.55 would become 153.2.56
npm version minor	New functionality was added. There are no breaking changes though (apps using the module before are unaffected) One exception is when the major version is less than 1.0.0-- in that case, it is acceptable to use minor versions when you would normally use major versions.	0.0.9 would become 0.1.0; 1.9.55 would become 1.10.0
npm version major	There were one or more breaking changes since the last release, which means this new version is not backwards compatible- users would need to make changes to their code if they want to upgrade	0.0.9 would become 1.0.0; 9.2.55 would become 10.0.0

When unsure, er on the side of bumping the version too much. For example, if you can't remember if there are breaking changes and there just isn't time to check, always bump up a major version. Two things to keep in mind:

• minor version bumps AND patch version bumps will be automatically picked up by users whose package.json files reference us as a dependency like: ^0.3.0
• patch version bumps will be automatically picked up by users whose package.json files reference us as a dependency like: ~0.3.0

3. Push up the new commit and the tag to GitHub

This will be the first commit of the new version on GitHub. The special version-number-only commit makes the current NPM version easy to track, and the tag will make the version-number-only commit appear under "Releases". This is really important for users/contributors to understand what changed between versions, and to hvae confidence that they understand what code they're using when they install from NPM.

git push -u origin master && git push --tags

4. Publish to the NPM registry

npm publish

You can check that it worked by looking at the package on npmjs.org and checking that it has the new version (e.g. https://www.npmjs.com/package/sails.)

Hey @mikermcneil, I believe the below is not entirely incorrect:

minor version bumps AND patch version bumps will be automatically picked up by users whose package.json files reference us as a dependency like: ^0.3.0

As per node-semver

Many authors treat a 0.x version as if the x were the major "breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes between 0.2.4 and 0.3.0 releases, which is a common practice.

So minor version bumps AND patch version bumps will be automatically picked up by users whose package.json files reference us as a dependency like: ^1.3.0 but for ^0.3.0 only patch version bumps are picked up.

PS: good guide!

@dmarcelino nice catch, thanks!