How to Create, Search, Install, Update and Publish npm Packages

Create a package

Creating an npm package is really simple. Just run npm init from the directory you would like to create the package in and then follow the interactive terminal UI to create your package.

Properly install your dependencies

It’s really important to properly install packages when using npm to make sure that things work for other people on other computers as well as when you have multiple projects that use the same packages on one computer.

Don’t globally install packages (npm install --global my-package or npm install -g my-package) unless you absolutely have to. When a package is globally installed it is not added to your packages dependencies so if your package were installed on another computer, the dependency you installed globally won’t be installed and your package will be broken. Another reason not to install packages globally is that if you have multiple packages with the same global dependency, they must require the same version, since you can only have one version globally installed.

Always use npm install --save my-package or npm install -save-dev my-package. If you don’t save the package to either your package’s dependencies or devDependencies, then your package will not install that dependency for other users or clean installs on your computer. You should use --save for dependencies that your package needs to run, things like react, lodash or jQuery. --save-dev should be used for dependencies that are required for development, but not to run your package, things like eslint, jest or mocha.

Use executables like a pro

npm packages containing executables should be installed locally (not globally). A few examples of packages containing executable are eslint, webpack and jest. When these packages are installed, they add an executable to node_modules/bin/, that can be run from anywhere in the package.

The easiest way to run executables installed by npm is through package.json’s scripts, like this:

// package.json
{
"scripts": {
"lint": "eslint *.js"
}
}

When you are ready to run the eslint, all you have to do is npm run lint. npm adds all executables to the path for the commands executed from package.json’s scripts section.

You can also run the same eslint executable from anywhere else in the package like this node_modules/.bin/eslint. This can be useful from other scripts or when testing things quickly from the command line.

Maintain your packages dependencies

Keeping your packages dependencies up to date is very important, it will improve security, performance and compatibility with other packages. npm uses semantic versioning (semver) for packages, if you aren’t familiar with it, you should read this before continuing.

Using semver effectively is the easiest way to keep dependencies up to date. If your dependenices and devDependencies look like this "react": "15.0.0" npm will install version 15.0.0 every time you run npm install. We can take advantage of the fact that semver says only major version changes can cause breaking changes to a packages public API and declare our dependencies as "react": "^15.0.0". What this means is that when you run npm install npm will install the latest version of react that doesn’t have an increase in major version number (15.0.1, 15.1.0, 15.2.2, etc). This is beneficial because you will get and patch or minor upgrades without manually having to update your dependencies.

npm outdated is your friend. It will list all of the dependencies in your package that have new versions that your package.json’s depndencies don’t allow npm to automatically update to. The output looks like this:

Since under sermver, only major version changes introduce breaking public API changes npm allows you to declare dependencies like "react": "^15.0.0"

Searching for packages

You can search for packages using npm search from the command line or npm’s official website https://www.npmjs.com/. While both of these work, they have a lot of shortcomings and their are better alternatives. npms is the search I use and recommend to others. It has a much smarter search, as well as quality, popularity and maintenance numbers for each package (keep in mind these numbers are by no means totally accurate, but they are a helpful quick sort).

Another useful tool for searching for packages is npm Discover. It is great for finding packages that are commonly used with a given package.

Publishing packages

npm has it’s own set of commands for publishing packages, but Sindre Sorhus created the utility package np that claims to be “a better npm publish” and it really is. After installing np and authenticating npm it is really as easy as typing np and then following the interactive terminal UI to publish your package.


There is plenty more that can be done with npm, but this should give you the knowledge you need to create, install, update and publish packages to npm. Please let me know in the comments if you think anything is missing or incorrect.