How to publish a scoped NPM package for your organization

I published my first package to the NPM registry this week. I was expecting it to be really difficult but it was surprisingly simple.

As I was working on the first open source project for my company, I wanted it to look cool and to mimic the style I’d seen on a lot of other packages – the organization name preceded by an at symbol (“@”), followed by a slash (“/”) and the package name.

This is called “scoping” a package, where the scope is your organization. It both looks great and ensures your package doesn’t clash with other published packages on NPM, even if they have the same name.

Here’s how you can do it.

Sign up to the NPM registry

If you haven’t already signed up to the NPM registry (npmjs.com), you’ll need to do it to publish your package.

To do this, just head to the site and hit “Sign up” in the menu bar.

Once you’ve signed up, click on your avatar that’s appeared in the menu bar and select “Add organization”.

You’ll be taken to a new page where you can choose to sign up for a new organization or convert your individual account into an organization. I chose the former because I wanted to keep my personal account separate from the organization I was creating.

Then, you choose a name for your organization – this will be the part that follows the “@” symbol in your package name.

You’ll also be asked whether or not you’d like to pay for your organization. I said no to this because our company want to publish open source projects on NPM so everyone can use them – that’s free. If you’d like to publish your packages privately, however, you can pay a small fee for that.

The organization creation screen on npmjs.org.

Once you’ve chosen the name and type of organization you’re creating, you’ll be prompted to invite people to it.

Congrats – you’ve created your first organization on the NPM registry! Now you can start publishing your packages to it.

Setting up your package and your terminal

Assuming the package you want to publish to the NPM registry is ready to go, head to the package directory in your favoured terminal (I use iTerm or VSCode, depending on my mood).

Once you’re there, double check your package.json has two important things:

1. Check the “name” field fits the following naming structure: @organization/your-package-name. It must contain the “@”, your organization name and the slash before your package name to correctly scope to your organization.
2. Check you’re happy with the package version number. This will be published alongside the content of your package on the NPM registry, and users of your package will be able to install this version by adding it to the end of their package install commands, such as: npm install @organization/your-package-name@1.2.3.

Now you’re happy with your package name and the version number, run the command npm adduser in your terminal to log in to NPM. This will ensure you have the right permissions to publish your package in the next step.

Publish your package

Now run the command npm publish --access public to publish your package to the NPM registry.

That’s it.

Wait just a few minutes and head to npmjs.com and you should be able to see your your package listed under your organization’s, and if you head to https://npmjs.com/@<organization>/<your-package-name> you should be able to see the newly-created package page from which people will be able to read about and download your scoped package.

Thanks for sticking around! Like this post? Buy me a coffee ☕️