How to Develop Your Own NPM Package

September 19th, 2019

Building an npm package is a great way to contribute to the open source software ecosystem. Not only will you learn more from supporting the needs of different developers, you will also become more involved in the community you are helping.

In this article I'm going to go over some basics for setting up your package. It's important to have a good workflow down for development of your package, as you will likely get many bug reports and feature requests if your package is even mildly successful.

Getting started

The first thing you'll need to do is run the npm init command in your project directory. This will get you set up with the basic package.json file that contains all the information npm needs about the project.

We'll be testing whether our package works by having it installed on another project locally during development. We do this by running the npm link command in our package directory. This creates a symlink to your package from the global modules folder. Once you have a project you want to test your package in, you'll add your package to the project by running the npm link [package name] command in your project directory. Now your npm package will act like a regular module in the test project and any updates to the package can be quickly tested locally.

Creating a build process

If you're looking to develop using newer Javascript features, you might consider compiling the code using Babel for the sake of compatibility. For this we'll be installing three packages: Babel for compiling, the Babel cli, and cross-env for setting environment variables easily across platforms.

npm install --save-dev @babel/cli @babel/core cross-env

Once those are installed, open your package.json file in the npm package and add find the area for scripts. Let's assume for this that we have ES7 code in a folder called src and we want the compiled code in the root directory.

{
    ...
    "scripts": {
        "build": "babel src --out-dir .",
        "prepare": "cross-env NODE_ENV=production npm run build"
    }
}

Now when you make updates to the package, you can run npm run prepare and it will output code ready to be distributed. You can add a .npmignore file to stop the ES7 code from being included in the package. It works in the same was as a .gitignore file.

Writing instructions

When people use your package, they'll be looking for instructions on how to use it. Npm works the same way as Github, in that they will display the README.md file along with your package. This is a Markdown file that allows for formatting. If you're not familiar with Markdown, it's pretty easy to use and you can learn more about it here.

Keeping this file up-to-date with detailed instructions can save you a lot of time and hassle. You don't want to be inundated with people filing Github issues because they couldn't get your package to work. Typically you'll want to cover: what problem the package is solving, how to install it, how to use it, an explanation of any options, and if you're feeling generous a way to contact you for support.

Publishing to the registry

The process of getting your package onto npm is fairly simple. You'll obviously need an account with them, and then you'll need to add your account to the project. You can do this by running the npm adduser command. Double check the package.json file to make sure all the information is correct including your name, package name, and version number. Npm will block you from publishing the package if there is already a version with the same version number. When you're ready, simply use the npm publish command. It will package up the directory and upload it to their service.

When publishing to npm, I highly recommend first submitting a beta version to test. This way people looking for certain fixes can help you test them, and those that don't want unexpected surprises can install the package free from worry. You'll want to make sure your version reflects the beta state. It should look something like 1.0.0-beta.0. The last 0 being the beta version. When you're publishing a beta package to npm, you can tag it to make it easy for people to download.

npm publish --tag beta

Conclusion

Publishing to npm can get more advanced than this, but you should now have all the knowledge you need to get you started. It's amazing how large the open source community is, and now that you're the proud owner of your own package, you get to be a part of it!