Publishing node modules to a private repository

May 18, 2015

This is a tutorial on how to use your own private repository to publish node modules to. In most cases this will be a CouchDB based proxy of the public npm registry like Sinopia. I assume that is already set up and all you need is to configure your local development machine to use that registry.

Publishing your first package

1) Set your npm config to point to your private repo.

npm set registry http://your-private-repo:4873/
npm set always-auth true
npm adduser

The last command (adduser) will prompt you for the username, password and email.

2) Go to the location of files you want to be included in your package and make sure you have a valid package.json there. You may also add .npmignore file to exclude some files from being part of your package (i.e. unit tests). node_modules folder is automatically ignored but it won’t hurt to add it just in case. Remember to add the publishConfig property.

3) (optional) If you’re publishing the first version of your package, use npm pack to create a tar file of it. This will help you see what will actually go in the package before you publish it so it will help with detecting issues at an early stage.

4) Once you’re confident that your package is ready and has a unique name, go ahead and type the magic words: npm publish

5) Test your package in a different location. Go ahead with npm install package-name (-g) and confirm that it works as intended. If it doesn’t, read the next section.

6) Congratulate yourself on a job well done.

##Overwriting a published package

When you’ll realise there is something you need to fix, you will want to to overwrite the already published version rather than create a new version of the package. Typical examples of that would be an issue with permissions, paths not resolving correctly, a typo or some inconsistencies in documentation. Using npm publish will result in an error - and rightly so. There’s a built in mechanism to push you to version your package better. In some cases though you still want to publish over a version of a package. When you’re sure that the package is ready to be overwritten, use npm publish -f to force it.

Reverting your config to default

If something went wrong or simply want to go back to public registry, there is a simple way to revert your config to default.

npm set registry

This should work straight away and point your npm back to the original registry.

…but in case it doesn’t, you can simply delete your .npmrc file which stores the credentials. It will most likely be in your home directory (unlink ~/.npmrc should do the trick). It can be stored in other locations too, so if that didn’t work try deleting it from the locations described here:

Updating package.json

Make sure to add the “publishConfig” top-level property to your package.json file, example: