Publishing Packages to NPM

npm centralizes third-party, open-source Node.js packages and libraries within a large, online registry. Contributing to the Node.js ecosystem involves no vetting process, which lets anyone publish packages to the npm registry with little effort. Not only has npm's short process for publishing packages led to the explosive growth of the Node.js ecosystem, but also fosters the development of various types of packages: front-end libraries/frameworks, tooling, bundlers, routers, state management, etc. However, this comes at the cost of more packages being released with more security vulnerabilities and less reliability. Despite these concerns, npm continues to introduce new features and statistics for helping developers identify high quality packages.

A library author uses npm's command line client to publish their library's package to the npm registry and share it. Once published, npm allows developers to update their projects' dependencies with the latest version of this package or install this package within their projects.

Below, I'm going to show you how to publish a package to the npm registry.

I will demonstrate this with the rgb-hex TypeScript library. It will be modified accordingly to get it ready for publishing.

Logging into NPM#

To get started, you must have an npm account. If you do not have an npm account, sign up for an account here.

Within the root of the package directory, run the following command in the terminal:

Logging into your account associates your package with your account.

You will be prompted to enter your npm username, password and e-mail address.

Excluding Files with .npmignore#

When you publish a package to the npm registry, there are some files and directories, such as a testing suite and coverage reports, that can be omitted from the package. A testing suite validates your library's functionality and coverage reports inform you of areas in your code that lack tests. They are not required for end users to consume your library within their projects.

The main benefit of excluding files with .npmignore is reducing the number of files and directories the end user downloads when fetching your package from npm. Ideally, end users should be able to quickly download your package, and your package should not take up unnecessary space on their machines.

If your library uses the Jest testing framework, then you would add the __tests__ and coverage directories to the .npmignore file.


To further reduce the number of files within the package, you can exclude formatting-related configuration files, such as .eslintrc.js, .prettierrc and .editorconfig.


Just think about which files and directories are needed within the package to allow end users to use your library. Whichever files and directories are not necessary should be added to the .npmignore file.

Note: If the project contains a .gitignore file, then the files and directories listed within the .gitignore file will automatically be excluded from the package.

Alternatively, you could list the files to include within the package via package.json's files property.

Updating Entry Point in package.json#

The entry point of your library indicates the file from which execution begins when the library is imported. By default, npm searches for a main property inside of the package.json file to determine the package's entry point. For tooling that supports ESM modules, you can define a module property that points to the package's .mjs file.

Note: module is not an official package.json property. It is a proposal for ES6 module interoperability in Node.js. Read more about it here.

Commonly, your library's generated build will be outputted to a build or dist directory. Therefore, the main and module properties should point to files within either of these directories.


Testing Publishing with npm pack#

To verify the package's contents before publishing to npm (and whether or not the .gitignore and .npmignore files filter out the correct files and directories), create a tar archive of the package. This tar archive contains all of the files and directories that will end up in the published package.

To generate the tarball, run the following command:

In the current directory, you will find a tar file named <package-name>-v<version>.tgz. package-name comes from the name property of package.json, and version comes from the version property of package.json.

To extract and list its contents, run the following command:

The tar -xzf command deposits the contents into a directory named package.

Here, we can see that the package.json file, file and dist directory are included.

Publish to the npm Registry#

Lastly, to publish the package to npm, run the following command:

When prompted to enter a version, press enter to use the version mentioned in the package.json file.

If you run into the following error message, then you will need to enable two-factor authentication for your npm account:

To enable two-factor authentication, visit your npm account's "Account Settings" page and click the "Enable 2FA" button under the "Two Factor Authentication" section.

After you enter your password, npm redirects you to a wizard that walks through the process of enabling two-factor authentication.

Enable two-factor authentication for both authorization and updating/publishing packages.

Scan the QR code with an authenticator app like Authy. Verify that Authy successfully registered npm by entering a six-digit code generated by Authy.

Once two-factor authentication is successfully enabled, you will be shown recovery codes. Save them to a new, empty text file. Without these codes, it will not be possible to recover your account in the event that you are not able to provide the one-time password.

Return to the terminal and re-enter the npm publish command.

Once your package has been published to npm, you can navigate to your package's page at npm's website.

Next Steps#

Try publishing your own packages to npm. You can also check out our new course, The newline Guide to Creating React Libraries from Scratch, where we teach you everything you need to know to succeed in creating a library.