Creating Your First npm Package

Creating Your First npm Package

Lately, I’ve been pushing myself to contribute more to open source. I started by contributing to existing projects: small features and writing documentation. I even wrote a blog post about it.

This past week, I was finally able to make the jump from contributing to a project to authoring one. This blog post will discuss how you can get started by writing an npm package.

What is npm?

If you’re not familiar with it, npm is the largest JavaScript package manager in the world. In npm, a package could consist of anything from a single file with some helper functions to a full-scale library. Packages can be published publicly for anyone’s use, or privately, for use only by people in a particular organization (this is a paid feature).

npm has a command line tool that allows you to download, install and publish packages. There is also the website, which primarily has search features for the registered packages and documentation about the tool. Most of the packages that you would want to use will be registered with npm but npm can also install unregistered packages directly from a Github repository.

How do I know what would make a good npm package?

While theoretically anything could be made into an npm package, it’s probably best to limit npm packages to sections of re-usable code that are fairly self-contained. I say, “fairly self-contained” because npm packages will commonly be dependent on other npm packages. When you install the parent package, npm will automatically download and install the children as well. However, when you create a package, you’ll want to identify some code that others will want to use and doesn’t involve heavy integration with the rest of your app.

For example, you may have written a great wrapper for the Fetch API but if your code has the URL for your server hardcoded into it, it limits the reusability for other people.

In my case, I solved an issue a while ago where React Native would run on iOS 8 phones but the JavaScript engine used by those phones didn’t have access to certain new functions. In order to use those functions, it was necessary to polyfill them. After a friend expressed interest in my solution, I decided to turn my polyfill library into an npm package.

How do I create an npm package?

First off, you’ll need to install Node and npm (they come together). Installation typically isn’t too difficult; just follow the installation directions.

Next, you’ll need to move to the macOS terminal, Linux terminal or Windows command prompt. I’ll give the commands for a Mac but they’re actually pretty similar for all platforms.

Now that you’re in the terminal, you’ll want to navigate to the folder where you keep your projects and create a new folder for the package. I keep my projects in a Projects folder and I wanted to name my package, react-native-polyfill.

$ cd Projects/
$ mkdir react-native-polyfill
$ cd react-native-polyfill

To make things a little easier, I give my folder the same name as the package. This is easier because later when you install your package in a project, it will name that folder after your package. Package names commonly use dashes/hyphens to separate the words, but that is not required. npm has other naming requirements that you can read about.

To check if your package name is available, modify this URL in your browser:

https://npmjs.com/package/<my-package-name>

If you also want to make your package available on Github (most packages are available on both), you’ll want to do this now. I usually find it easiest to create the repository on Github’s website (I give the repository the same name as the folder), and then follow the directions on Github to link the directory on your computer with the repository.

With that accomplished, it’s time to make your directory an npm package:

$ npm init

The command line tool will next ask you a series of questions. It’ll use your answers to pre-fill out the package.json file for you. You can edit your answers there later if you’d like. Many of the questions will have a default answer provided for you in parentheses. Just press enter to accept it.

One of the questions you’ll be asked is the version of the package. npm uses Semantic Versioning (semver) to help control which version of a package is installed. npm recommends that any package that will be leaving your computer should be version 1.0.0 or higher. This helps prevent some confusion that happens when the semver version is less than 1 (ie, version 0.x.x).

You’ll also be asked about the license for your package. Any package on npm is open source (unless you’ve paid for private packages). You don’t have to choose a license but there are tools to help you choose one. The MIT license is often recommended if you’re not concerned with how others use your code.

And that’s it! You’ve now created a package. The next steps will be working on your code and publishing the package.

How do I write code for an npm package?

There are no special requirements for the code in an npm package. The code in your package can rely on code from other libraries and packages. You would just specify those as dependencies in your package.json file.

The biggest guideline is the one that I mentioned earlier. The point of publishing an npm package is to allow people to re-use your code. That means that your code should be as generic as possible. Obviously, you’ll need to avoid referencing files or functions that are not public (internal libraries or things that you haven’t open sourced). You’ll probably also want to avoid company specific terms or names. If your code references the DOM, try to use generic classes or ids that other people could use (but not so generic that they might use them by mistake and cause conflicts).

If you want people to use your code, it’s helpful to publish some instructions with your package on what it does, how to use it and how to install it (especially if there are special configuration steps). Simply create a README.md file in the main directory of your package. The md means this is a markdown file so you can use markdown to style it (create headers or links, include images, etc). If your package is also on Github, the same file will be used there as the first thing that people see when they view your repository.

How do I publish an npm package?

Once you’re done with your code, it’s time to publish your package.

If you’re using git or another version control system, commit your code first.

Then head back to your terminal and run the following commands:

$ npm login
$ npm publish

Your package will now be published to the npm registry. You can modify the following URL with your package name to see it live:

https://npmjs.com/package/<my-package-name>

How do I update an npm package?

If you’re updating a package that has already been published to npm, you’ll need to change the version number on your package so that you don’t break someone else’s project if they were relying on a specific version of your package.

npm has guidelines on how to update the semver for your package:

changes should be handled as follows:

• Bug fixes and other minor changes: Patch release, increment the last number, e.g. 1.0.1
• New features which don’t break existing features: Minor release, increment the middle number, e.g. 1.1.0
• Changes which break backwards compatibility: Major release, increment the first number, e.g. 2.0.0

You can update the version of your package manually by changing the package.json file or you can use the npm version tool. The options for the version tool are pretty complicated but I can give a simple example.

I recently published my package, react-native-polyfill, at version 1.0.0. At some point, I would like to add tests to my package. Per the guidelines above, this would be a minor change so I would be updating the patch (right-most) number of the version. To do that, I would run:

$ npm version patch

This would update the version in my package.json to v1.0.1

Conclusion

The npm package registry is enormous and a powerful tool used by JavaScript developers around the world. The npm CLI has an incredible number of options and commands but, as you can see, the basic usage isn’t very complicated.

With just a few commands, you can begin contributing to this worldwide community.