An Open Source Maintainer's Guide to Publishing npm Packages
Tags: npm, publishing, opensource, javascript
Published: 2020-05-23 16:34:49

The JavaScript community is built on Open Source and being able to give back to the community feels most gratifying. However, publishing a package for the first time might feel rather daunting, and publishing a release candidate may be a bit scary even for experienced authors. I hope to give some insight and helpful tips, especially for new authors.

I have owned two open source libraries: a tiny utility library for DraftJS called [draftjs-md-converter](https://github.com/kadikraman/draftjs-md-converter) and a React Native security library called [react-native-app-auth](https://github.com/FormidableLabs/react-native-app-auth). I am certainly not as heavily involved in Open Source as some, but I have had the sole responsibility of publishing new versions of these libraries for several years so I think I have enough experience to justify this blog post! I remember how scary it was to publish a library for the first time, and I still remember how apprehensive I felt publishing a release candidate. The purpose of this writeup is to produce a guide on how to publish packages: both a comprehensive guide for new authors, and a sanity check for future me.

I will cover the following:
- Setting up your repo for publishing
- Publishing a package (initial release)
- Versioning
- Publishing a package (subsequent releases)
- Publishing alpha / beta / release candidate versions

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:

### Check the package name
The [`name`](https://docs.npmjs.com/files/package.json#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

```js
import ... from "package-name";
```

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

### Set the 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:

```json
{
  "version": "0.0.1"
}
```

or

```json
{
  "version": "1.0.0"
}
```

NPM packages use [semver](https://semver.org/) 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.

### Make sure your repository is not private
In the `package.json` you may have an attribute `"private": true`. It is a [built in protection](https://docs.npmjs.com/files/package.json#private) 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.

### Add a license
Ensure you have set the [license](https://docs.npmjs.com/files/package.json#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](https://snyk.io/blog/mit-apache-bsd-fairest-of-them-all/). I have always used the "MIT" license.

### Check the entry point
The [`main`](https://docs.npmjs.com/files/package.json#main) field in your `package.json` defined the main entry file for the package. This is the file the users will access then importing your package. It'll usually be something like `./index.js` or `./src/index.js` depending on the location of your entry file.

### Restrict the files you want to publish
Be 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](https://docs.npmjs.com/files/package.json#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.

### Add a 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:

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

This will be run automatically when you run the publish command. For example in [this package](https://github.com/kadikraman/draftjs-md-converter/blob/master/package.json) 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](https://docs.npmjs.com/misc/scripts).

## 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/](https://www.npmjs.com/) if you don't have one already, and use these credentials to log in on your terminal:

```sh
npm login
```

Finally, in your project repo, run:

```sh
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:

```bash
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 3 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 minimise 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 will miss `1.3.0`

`^1.2.3` will match any `1.x.x` release including `1.3.0`, but will hold off on `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. [Source.](https://medium.com/@Hardy2151/caret-and-tilde-in-package-json-57f1cbbe347b)

## 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:

```
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 for.

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 install`s 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

That's pretty much it! Publishing packages can be a bit scary the first few times, but like anything it gets easier the more you do it.

Thank you for contributing to Open Source!