How to Create and Publish Your First NPM Package

Publishing your first NPM package feels like a rite of passage for JavaScript developers. Whether you've built a utility function you keep copying between projects or solved a problem that others might face, sharing it on NPM makes your code accessible to millions of developers worldwide.

I'll walk you through the entire process, from choosing a name to seeing your package live on the registry. We'll build a simple example together so you can follow along.

Picking the Perfect Package Name

Before you write a single line of code, you need a name. This is trickier than it sounds because NPM has over a million packages, and yours needs to be unique.

Head over to npmjs.com and search for your desired name. If you find something similar, NPM will likely reject your submission. For example, if there's already a package called hellonpmpackage, you can't publish hello-npm-package because they're too similar.

Don't panic if your name is taken. You have two options: pick a different name or publish a scoped package (which I'll explain later). Scoped packages let you use @yourusername/package-name, so you can still get the name you want.

Setting Up Your Package

Let's create a simple package together. I'll build one called first-hello-npm that returns a greeting.

Getting Node.js Ready

You'll need Node.js installed, which comes with NPM built-in. Grab it from nodejs.org if you don't have it yet.

Initialize Your Project

Create a new folder for your package and set up version control:

mkdir my-npm-package
cd my-npm-package
git init

Now initialize NPM:

npm init

This creates your package.json file. You'll get prompted for details like package name, version, description, and entry point. Here's what each field means:

Package name: Must be unique and lowercase. Hyphens are fine, underscores aren't recommended.

Version: Starts at 1.0.0. Follow semantic versioning when you update later.

Description: Tell people what your package does. Be clear and concise.

Entry point: Usually index.js. This is the file that loads when someone requires your package.

Keywords: Help people find your package when searching NPM.

The rest is pretty self-explanatory. Don't worry about getting everything perfect - you can always edit package.json later.

Writing Your Package Code

Create your main file (probably index.js) and add your functionality:

// index.js
function helloNpm() {
  return "Hello NPM!";
}

module.exports = helloNpm;

That's it! The module.exports line is crucial because it makes your function available when someone installs and requires your package.

Testing Before Publishing

Always test your package before publishing. There's nothing worse than releasing broken code to the world. Here's a simple way to test locally.

In your package directory, run:

npm link

This makes your package available globally on your machine. Now create a test folder somewhere else:

mkdir test-my-package
cd test-my-package
npm link first-hello-npm  # replace with your package name

Create a test.js file and try out your package:

// test.js
const helloNpm = require('first-hello-npm');

console.log(helloNpm()); // Should print "Hello NPM!"

Run it with node test.js. If everything works, you're ready to publish.

Publishing to NPM

First, you need an NPM account. Sign up at npmjs.com/signup if you haven't already.

Back in your package directory, log in through the terminal:

npm login

Enter your credentials. You should see a confirmation message.

Now for the moment of truth:

npm publish

If successful, you'll see output confirming your package is live. Congratulations! You can search for it on npmjs.com to see it in action.

Working with Scoped Packages

Sometimes you want to publish under your username, either because your preferred name is taken or you want to organize your packages. Scoped packages use the format @username/package-name.

Initialize a scoped package like this:

npm init --scope=@yourusername

When prompted for the package name, use the full scoped format: @yourusername/package-name.

Publishing scoped packages requires an extra flag:

npm publish --access public

Without --access public, NPM assumes you want a private package, which requires a paid account for scoped packages.

What Happens After Publishing

Once your package is live, anyone can install it:

npm install your-package-name
# or for scoped packages
npm install @yourusername/package-name

They can then use it in their code just like any other NPM package. Pretty cool, right?

Your package page on NPM will show download statistics, and if you've linked a GitHub repository, it'll display your README file automatically.

A Few Final Tips

Keep your package focused on solving one problem well. The most successful NPM packages do one thing excellently rather than many things poorly.

Write a good README file. This becomes your package's homepage on NPM, so explain what it does, how to install it, and provide usage examples.

Version your updates properly. Use semantic versioning: patch versions for bug fixes (1.0.1), minor versions for new features (1.1.0), and major versions for breaking changes (2.0.0).

Consider setting up automated testing and continuous integration. As your package grows, you'll want confidence that updates don't break existing functionality.

Publishing your first NPM package is exciting. It's your contribution to the massive ecosystem that powers modern JavaScript development. Whether it's a simple utility function or something more complex, you're helping other developers build better software faster.

Now go build something useful and share it with the world. The JavaScript community is waiting for what you'll create next.