The iconic logo of the npm registry

npm-publish

a guide to releasing your first npm package

Introduction

npm (node package manager) is the world’s largest software registry. According to the documentation, npm consists of three distinct components:

• the registry
• the website
• the CLI

The registry is an immense database containing all the node packages & modules ever published, complete with version info and metadata.

On the website, you can search for and view packages, create an npm profile, and manage user settings.

The CLI provides the primary means of interacting with npm, including the publishing of packages & modules, which we will now cover in-depth.

Prerequisites:

1. an npm account
2. a GitHub account
3. the current version of Node.js
4. the current stable version of npm

npm install npm@latest -g

Package vs Module

It is important to understand the two types of objects you can publish to the registry.

How is a package defined?

• a) A folder containing a program described by a package.json file.
• b) A gzipped tarball containing (a).
• c) A URL that resolves to (b).
• d) A <name>@<version> that is published on the registry with (c).
• e) A <name>@<tag> that points to (d).
• f) A <name> that has a latest tag satisfying (e).
• g) A git URL that, when cloned, results in (a).

How is a module defined?

Any file or directory within node_modules that can be loaded by the Node.js require() function. To comply, at least one of these formats must be used.

• A folder with a package.json file containing a "main" field.
• A folder with an index.js file in it.
• A JavaScript file.

A module can also be a package, but not all modules are packages by default.

Private vs Public

This parameter determines the visibility of your new npm package. For this article, it is assumed that you will elect to create a public package, but you may always reference the documentation for more details.

Scoped vs Unscoped

Here you will define whether you want to release your code completely to the public domain (unscoped) or publish the code within a retained namespace (scoped).

• Unscoped packages are always public.
• Private packages are always scoped.
• Scoped packages are private by default; you must pass a command-line flag when publishing to make them public.

The command line interprets your decision by how your package is named. I’ll create examples based on my own npm account username.

PUBLIC/UNSCOPED: npm publish my-package
PUBLIC/SCOPED: npm publish @killshot13_npm/my-package --access public
PRIVATE/SCOPED: npm publish @killshot13_npm/my-package

To avoid confusing the reader, I shall refrain from much discussion about teams, organizations, and enterprise accounts. Since this article is about publishing our first npm package, I doubt these factors will be of much concern at present. Just be aware of the concepts for future knowledge.

Create | Review | Test | Publish

At last, the moment you have been waiting for! These four simple steps are what you will be using to publish your package or module to the registry.

WARNING: If you deviate from this path or omit one of these steps, chances are you will encounter errors and spend a considerable amount of time debugging your files.

Create

mkdir my-package
cd my-package

Now that you have a root directory, initiate git and npm

git init
git remote add origin git://YOUR URL HERE
npm init
// Follow the prompts to create a package.json file. 
// Consider the conventions listed above when naming your package.

Now open the directory in your favorite code editor and add a README.md file and the rest of your package code files.

Review

In this step, use whatever means are at your disposal to double-check your code for environmental variables, including passwords, API keys, and other sensitive data.

If necessary, create the appropriate files and replace your existing code with default variables as needed to protect your secrets.

.gitignore | .npmignore | .env | PROCESS.ENV

Test

Almost there! Just one more quick (hopefully) thing to wrap up before you publish. To keep bugs out of the registry, especially when publishing publically, you should first test your package in your own environment.

Since you are already using the npm CLI, you can just run this command.

npm install my-package
// Use the full path to your project directory.

If everything functions as designed, congratulations, you are ready to publish your first package!

Publish

This is the simplest and most satisfying step. Navigate back to the root directory of your npm package.

cd /path/to/package

Are you ready?

npm publish my-package

If npm prints something that looks like this, you are golden!

Photo courtesy Dev Community

Tips & Tricks

• Once you npm publish, you CANNOT change your package name! Take a moment to solidify your choice of words. Try to keep package names short and descriptive. For an example of what not to do, imagine installing this npm package.

I pity the fool!

npm install --save @teambit/staged-components.component-status-resolver

• Sometimes, even with an unscoped public package, npm refuses to publish unless you include a flag. Add --access public to your command and try again.

npm publish my-package --access public

• If you enabled 2FA when creating your npm account, you will have to provide the one-time token in your publish command.

npm publish my-package --otp=811486

Conclusion

I hope you enjoyed this article. Feel free to add suggestions or ask questions in the comments below, and I will get back to you. Thank you for reading, and happy coding!

— killshot13

If you found this article useful or interesting, please 👏 and share it!
Follow me (M Rehnert) on Medium and check out my most popular articles below!