An Open Source Maintainer's Guide to Publishing npm Packages

Being able to contribute to open source can feel incredibly gratifying. The JavaScript community is built on open source, and all of us benefit from it daily. Giving back feels like a natural next step. You could start by submitting PRs to other Open Source libraries — fixing bugs, adding features or even just updating documentation (often underrated, but so appreciated by maintainers). Eventually you might get a project idea of your own — a unique problem you've built a solution for. Something you would like to share with the world. But how to publish it?

I have maintained two open source libraries: a tiny utility library for DraftJS (draftjs-md-converter) and a React Native security library (react-native-app-auth). I've figured out what works by trial and error, and lots of Googling. I often ran into the problem of "unknown unknowns" — that is, gaps of knowledge where I didn't know I had a gap of knowledge. For instance, you can easily find out that npm publish will publish your repository, but it might not be obvious how to update the package version and how these version changes affect your users. The purpose of this writeup is to cover many of these gotchas ahead of time and produce a guide on how to publish packages.

You can use npm or yarn, it's completely up to you. The publish commands are identical. I will be using npm throughout.

Setting up your repo for publishing

Before you're ready to run the publish command, you should check that your package is in a good state to be published. Here are a few things you might want to consider:

Package name

The name field in your package.json will be the name of your published package. So for instance if you name your package package-name, users will import it with

import ... from "package-name";

The name needs to be unique, so make sure you check that the name is available on https://www.npmjs.com/ or your publish command will fail.

Initial version

The version attribute in your package.json will determine the version of the package when published. For your initial release you might use:

{
  "version": "0.0.1"
}

or

{
  "version": "1.0.0"
}

NPM packages use semver for versioning, which means the version consists of 3 numbers: the major, minor, and patch version. We will talk more about versioning in the "Versioning" section.

Privacy settings

In the package.json you may have an attribute "private": true. It is a built-in protection so you wouldn't accidentally publish something that's meant to be private. It is generally a good practice to use this if you're building something that is not meant to be open source, like a personal or a client project. However if you're about to publish the repo as a package, this line should be removed.

License

Ensure you have set the license in your package.json. This is to let people know how you are permitting them to use your package. The most common licenses are "MIT" and "Apache-2.0". They are both permissive, allowing users to distribute, modify, or otherwise use the software for any purpose. You can read more about the differences here. I have always used the "MIT" license.

Entry point

The main field in your package.json defined the main entry file for the package. This is the file the users will access when importing your package. It'll usually be something like ./index.js or ./src/index.js depending on the location of your entry file.

Which files to publish

By default, publishing a package will publish everything in the directory. Sometimes you might not want to do that, e.g. if your repository includes an example folder or if you have a build step and only want to publish the built bundle. For that purpose, there is a files field in the package.json. If omitted, the field defaults to ["*"], but when set, it includes only the files and directories listed in the array. Note that certain files are always included, even if not listed: package.json, README, CHANGES / CHANGELOG / HISTORY, LICENSE / LICENCE, NOTICE, and the file in the "main" field.

Build step

Sometimes you may need a build step. For example if you've written your package using Flow, TypeScript, or cutting-edge JavaScript features that aren't implemented in all browsers, and want to compile/transpile your package to vanilla JavaScript that anyone could use. For this you can use a prepublish script like so:

{
  "scripts": {
    "prepublish": "npm run your-build-script"
  }
}

This will run automatically when you run the publish command. For example in this package I use the prepublish script to rebuild the app in the dist directory. Notice also that the main field in this package.json is set to "main": "dist/index.js" since I want the users to access the built file. There are more built-in scripts for various occasions, but this is the only one I've had to use when publishing packages. You can read more about other available scripts here.

Publishing a package (initial release)

Clone your repo, and make sure you're on the latest master branch (or whatever your main branch is) with no uncommitted changes. Create an account on https://www.npmjs.com/ if you don't have one already, and use these credentials to log in on your terminal:

npm login

Finally, in your project repo, run:

npm publish

If you've set up two factor authentication, you'll get a prompt for it in your terminal before the publish is completed. Once the command has finished successfully, you should be able to instantly see your package at https://www.npmjs.com/package/package-name where package-name is the name of your package set in the package.json, and people will be able to install your package with:

npm install package-name

Versioning

Publishing subsequent versions of the package involves more thought, because now we need to consider versioning. As mentioned above, npm packages are versioned using semver. This means that there are three types of releases: major, minor, and patch, and you should use these to communicate the types of changes in your library.

• Major changes include anything that is incompatible with the previous versions
• Minor changes are usually new features and bigger bug fixes
• Patch changes are tiny bug fixes or additive changes

One thing to note is that the semver naming is a bit misleading, specifically in "major" — a major release doesn't necessarily mean that a lot has changed. It means that when going from the previous to current version, there is a breaking change, and that the users of your library might need to change something in their code in order to accommodate the latest version. For instance, changing an exported function name or parameter order would be considered major changes. A lot of maintainers tend to collect breaking changes and release them all together to minimize how often the major version is incremented.

The reason you should only do breaking changes in major releases is because the users of your library may opt in to all future patch and minor versions silently, so the next time they run npm install you might end up breaking their build.

In the package.json, this is communicated with ~ and ^ where ~ opts in for all future patch releases and ^ opts in for all future patch and minor releases: ~1.2.3 will match all 1.2.x versions but not 1.3.0

^1.2.3 will match any 1.x.x release including 1.3.0, but not 2.0.0.

Side note: when the major version is 0, the package is considered unstable and so the ^ acts the same as ~ and for all releases before major 1 you may publish breaking changes in minor releases.

There is no option to opt in for all future major releases, because they are expected to be breaking and thus should be manual upgrades.

Publishing a package (subsequent releases)

This is how you do releases after the initial one. As before, you should ensure you're on the master branch with no uncommitted changes. Consider what type of release this is: major, minor, or patch. Now run the command to increment the version in your working directory, using major, minor, or patch depending on the type of the change: sh

npm version minor

This is a convenience method that does a couple of things:

• increments the version in your package.json based on the type of the change
• commits this version bump
• creates a tag for the current release in your .git repo; now all that's left to do is to run the publish command as before:

npm publish

It is important to make sure you do the version bump before the publish. If you try to publish the same version of the library twice, the command will fail. Finally, you'll want to push the version bump commit and the tag:

git push
git push --tags

Notice that you'll have to push the tags separately using the --tags flag. If you're using GitHub to host your repository, the tags will show up under the Releases tab on your repository, e.g. https://github.com/kadikraman/draftjs-md-converter/releases It is good practice to write some release notes against the tag. I usually also use this space to thank any contributors!

Publishing an alpha / beta / release candidate

An alpha / beta / release candidate is usually an early access version of a major release. When you're about to do a major change you might want to give your users a chance to try out the new release first on an opt-in basis but with the expectation that it may be unstable. Basically what we want to achieve is to publish a new version "silently" that would allow only interested users to opt in.

Let's look at how you might create a release candidate. Suppose you are currently on v3.4.5 and you want to do a release candidate for v4.

First, we increment the version. The npm version command allows you to provide your own version number. In this case we're going to say it's the first release candidate for v4:

npm version 4.0.0-rc1

As before, this does the version bump, commits the change, and creates the tag. Now to publish the package. This is the most important step, since you want to ensure none of your users get this release candidate version by default.

The publish command has a --tag argument, which defaults to "latest". This means that whenever someone npm installs your library, they get the last publish that has the "latest" tag. So all we need to do is provide a different tag. This can be anything really, I have usually used "next".

npm publish --tag next

This will publish your package under the next tag, so the users who do npm install package-name will still get v3.4.5, but users who install npm install package-name@next or npm install package-name@4.0.0-rc1 will get your release candidate. Note that if you publish another release candidate with the "next" tag, anyone installing npm install package-name@next will get the latest version.

When you're ready to do the next major release, you can run npm version major (this will bump the version to 4.0.0) and npm publish as normal.

Conclusion

Hopefully this covers the basics of how to get started contributing to Open Source with npm. It's handy to know what these commands do and how they work under the hood, but it's clear that there is quite a lot of room for human error. For everyday use, you might want to consider using the np utility, which guides you through each release and helps prevent common errors.

Thank you for contributing to open source!

"npm" and the npm logos are trademarks owned by npm, Inc.