A Guide To Publishing Your First NPM Package

If you’re a developer, you’ve experienced this: you’re installing one (or maybe several) npm packages into your codebase. You watch your terminal as the installation progress bar slowly creeps to finish. You see (and probably ignore) a barrage of mysterious warnings and dependency messages and then, suddenly, your code is equipped with brand new tools to create your next brilliant tech masterpiece.

If you’re a developer and you’re anything like me, you’ve found yourself thinking: “Ok, this is really convenient, but what’s actually happening under the hood?”. For new developers, the seemingly infinite modules, packages, and libraries of npm can really feel like code magic. But, like all things web-development, there is an explanation behind the sorcery. And, to my initial surprise, the mysteries of npm are actually much simpler than you might think.

Ok, back up, what is npm?

Good question! Npm stands for Node Package Manager. It is the world’s largest software registry and it’s the default package manager for Node.js. To date, npm hosts over a million code packages (for free!) that developers can install and use in their projects. Developers can install packages from npm without logging in or creating an account using the command line. The major requirement for using npm, however, is that you must have Node.js installed in order to use it (instructions for Node.js installation can be found here: https://nodejs.org). Installing an npm package from the command line usually looks something like this:

npm install <package>

Look familiar? So, in short, npm is both a set of command line tools for installing packages and an online registry that hosts those packages to be installed.

Now that we’re caught up on the basics, back to publishing:

In theory, any codebase with a package.json file could be published to npm — when a package is published, npm takes the information from the package.json file (the name, version, description, entry point, keywords, GitHub repository, etc, etc, etc.) and packages it to be installed in another codebase.

But, not every codebase is a useful codebase. The simplest way to think about a (useful) npm package is to think of it as a set of functions that can then be installed, required, and used within a separate project. In my opinion, the best way to learn is by getting your hands dirty, so let’s create a (somewhat useful, maybe?) npm library from scratch together.

Creating an Account with npm

Before we even get started with creating our package, we have to create an npm account! You can sign up for a free account at https://www.npmjs.com/. Once you create an account, open your terminal and run

npm adduser

It will then ask for your npm username, password, and email. This will log your computer into your npm account.

Initializing the Codebase

Now that we have created an account, we can get to the fun part! The first step in creating our sample package is to initialize a project. In your terminal, create a new folder. For this example, I’ll be calling the project filterize. To do this, run the command:

mkdir filterize 

Then, cd into that folder with

cd filterize

and open it. I’m using VSCode, so I’ll run

code . 

Once it’s open in your code editor, create an index.js file.

Creating a Function (or many functions — have fun with it!)

In index.js create a function. For my package, I’m creating a function that adds a filter to photos. If you’d like to do the same, you can paste the function below directly into your index.js file. If you are a photography purist and you hate filters, more power to you! Feel free to create whatever functions you’d like to have access to in another project via npm package.

My Filterizing Function

As a note, this function first finds all elements tagged with “.filterize” and saves them as an array into the variable images. Then, it determines what filter the user is passing through the function. The options here are “watercolor”, “faded”, “darken”, and “invert”. Once it determines which filter is being passed to the function as the argument, it saves more complicated styling information about that specific filter into the variable filterInfo. Finally, the function applies the filter to each image using a forEach call on the images array.

Once you have created your function(s), make sure you’re exporting it at the bottom of your file. This is crucial as it will allow other files to access your function(s) wherever it is imported (required) after it has been installed as an npm package. In my sample package, that looks like this:

module.exports.filterize = filterize

Adding a README.md

When you are creating an npm package, it is important to add a README.md file to explain to another developer how they’d use your package. For filterize, my README.md file looks like this:

Connecting to GitHub

Now that your function is created, upload your repo to GitHub. If you’re not sure how to do that, start with this documentation to create the repo on GitHub, and then follow the instructions on Github to push an existing repository from the command line.

Creating Package.JSON

As I mentioned above, the absolute most necessary part of creating an npm package is having a package.json file in your codebase. To create this, run npm init in your project command line. When you run this, it will run through a series of “questions” — like package name, version, etc — so that it can create the file for you. Feel free to add yourself as the author, add a description of your npm package, add keywords (think like, hashtags for your package), etc! Once you finish walking through those steps, you’ll see a package.json file in your file structure.

And now…the moment we’ve all been waiting for…

It’s Time to Publish!

Now that you have created your codebase, your README, your package.json, your function(s), and your GitHub repo, you are ready to publish! First, make sure you are logged in to npm by checking in your terminal. To do this, run npm whoami . If you’re logged in, you should see your username in the terminal. If you see this and you are ready to publish, just run the command npm publish . You’ll see some information logged in your terminal and then — you’re a published npm author!

Important Notes/Common Errors:

When publishing an npm library, you may encounter some errors. Here are some of the most common I’ve seen and how to fix them.

1. You cannot republish your package until 24 hours have passed. Npm only lets you publish or republish a package once a day, so it’s important to make sure that you are really ready when you publish!
2. You cannot use capitals in your npm package name. This one is pretty self-explanatory. Npm doesn’t like capitals so, sorry, no camel case for you.
3. Your npm package name is not available. Bummer — someone had the same idea before you. Once you come up with something even more creative and fun, just change the name of your project in your package.json file and try again.

Ok, filterizing is cool, but I’m ready for the next level.

Amazing! The sky really is the limit when creating npm packages, so code your little heart out. If you want a challenge, but you need a little bit of inspiration, check out this article by my colleague Laura Campbell on creating an Express middleware function to export as an npm library.

Congrats!

You have officially created your first npm library! Don’t forget to tell all of your dev friends to try it out so you can rack up the weekly downloads!