How to Publish to NPM

npm-logo-red

Node Package Manager is an extremely popular tool in the web development world, to the point where I would say it is required. Therefor it is also a great place to publish code tools and packages for distribution.

1. Install NPM

I’ll keep this section short since I’m assuming most people looking for how to publish to NPM would already have it installed. You can download Node directly here and npm is distributed within Node. There is also a tool called Node Version Manager which you can checkout here. Node Version Manager or “nvm” is a great tool if you need to keep multiple versions of node around, and makes installing updates easy.

2. Create an Account

Sign up for an account on https://www.npmjs.com/

3. Create a package.json

If you already have a package.json in your project, you can still follow the steps below. NPM will append/update the appropriate fields, it will not overwrite your whole file. Open terminal/powershell in your projects root directory and run the command

npm init

this will prompt you to provide the following (please note these commands can change slightly with different versions of npm):

  • package name: test-package-chektek
  • version: 0.0.1
  • description: super awesome package
  • entry point: index.js
  • test command:
  • git repository:
  • keywords: test, package, awesome
  • author: Zack Hoherchak
  • license:

It will then ask if it is ok to write the package.json to the directory:

{
	"name": "test-project-chektek",
	"version": "0.0.1",
	"description": "test description",
	"main": "index.js",
	"scripts": {
		"test": "echo \"Error: no test specified\" && exit 1"
	},
	"keywords": ["test", "post", "npm"],
	"author": "Zack Hoherchak",
	"license": "ISC"
}

Note: Depending on how you configure your project, you may want to have two package.json files, one for building and one for distribution. A little more on that later on.

4. Publish

You are now ready to publish! Run the following:

npm login

You will then be prompted for your npm username, password and public email. If all went well congratulations you can now view your package on npm!

Common Issues

You Do Not Have Permission

If you get an error stating something like “You do not have permission to publish package-name. Are you logged in as the correct user?” that could mean the following

  1. You are not logged in, try running npm login again.
  2. You are creating a package that already exists. Search your package name on npmjs and see if anything comes up. You may need to pick a different package name (edit name in your package.json).
  3. You ARE actually logged in as the wrong user, run npm login again.

Versioning

You may get an error stating “You cannot publish over the previously published versions”. This means you need to update your package.json version property to something later than the previously published version.

Tips

Check What Files Will Be Published

You can run the command npm pack --dry-run and you can see exactly what files are going to be published in your package. You can run this command without the dry-run flag to create a tgz with the actual package contents.

Two package.json Files

There are a few ways to accomplish this, but the one that worked best for me is having a deploy folder, containing a second package.json, and only the files I want to be published.

Including/Excluding Files

There are two ways to determine what files will be included in your package.

  1. Setting the files property in your package.json "files": ["/**/*"] includes all of the files for the provided matcher
  2. Creating an .npmignore file will ignore files you add to it working similarly to .gitignore

Note: The .npmignore file will not be used if the files property exists, so these methods cannot be used together. Using the files property in the package.json is preferred, however with my dual package.json setup .npmignore worked better for me.

Example

My first node package was a group of custom angular form validators. You can check it out here:

Last updated on