Damir's Corner.

Using a Private NPM Repository

In corporate environments, there's often a need for a private package manager repository where packages for internal use can be hosted. The free Nexus Repository OSS product from Sonatype is a common choice in such scenarios. Its wide range of supported repository formats includes NPM as well.

Installing Nexus Repository

Basic Windows installation is quite trivial. Assuming you have (64-bit) Java runtime installed, you only need to extract the download archive into a folder and start the server from the bin subfolder:

.\nexus.exe /run

By default, you can access the user interface at http://localhost:8081/. That should be enough for testing purposes. You check the official documentation for more details and recommendations when you're ready for production use. You might even want to consider the fully featured Nexus Repository Pro product.

Creating a Local NPM Repository

Maven and NuGet repositories are already preconfigured when you install the product. But for NPM, you'll have to create the repository yourself. To access Administration tools, you can sign in with the default admin credentials (admin:admin123) and click the gear icon in the toolbar.

Follow these steps, to create a NPM repository for hosting your private packages:

1. Click Repositories in the Administration panel on the left.
2. Click the Create Repository button in the Repositories pane.
3. Select npm (hosted) from the list.
4. Enter a Name for the repository, e.g. npm-hosted.
5. Click the Create repository button at the bottom.

To make life for the developers easier, it's a good idea to also configure Nexus Repository as a proxy for public NPM packages and then create a common group repository for accessing both public and private packages. The following steps will get you there:

1. Click Repositories in the Administration panel on the left.
2. Click the Create Repository button in the Repositories pane.
3. Select npm (proxy) from the list.
4. Enter a Name for the repository, e.g. npm-proxy.
5. Enter the URL of the official NPM repository as Remote storage, i.e. https://registry.npmjs.org/.
6. Click the Create repository button at the bottom.
7. Click Repositories in the Administration panel on the left.
8. Click the Create Repository button in the Repositories pane.
9. Select npm (group) from the list.
10. Enter a Name for the repository, e.g. npm-group.
11. Add both Available NPM repositories (npm-hosted and npm-proxy if you used the same names) as Members.
12. Click the Create repository button at the bottom.

Setting the Repository URL for NPM

To use the newly created repository from NPM, you need to configure it with you NPM tool. You can use the npm config command for that (you can find the repository URL if you click the repository in the list on the Repositories pane):

npm config set registry http://localhost:8081/repository/npm-group/

However, this will set the repository globally on your machine for all projects by creating a .npmrc file in your home directory. This might be okay for you, but if you're working for multiple clients and only want to use a specific repository for their projects, you can create a .npmrc in the root folder of the project with the same contents (and save it in source control for convenience):

registry=http://localhost:8081/repository/npm-group/

Logging into a Repository

In corporate environments, the repository might be secured and will require you to login. The npm login command can be used for this purpose:

npm login --registry=http://localhost:8081/repository/npm-group/

There's one important detail about this command, though. Make sure that you put the trailing slash in the repository URL. If you fail to do that, the npm login command will still report success. But other commands will still complain that you need to login.

Establishing SSL Certificate Trust

You might encounter another issue in corporate environments - SSL certificates issued by the company certificate authority which don't have a valid trust chain. Even if you add the company CA root certificate to the Windows Trusted Root Certificate Authorities certificate store, NPM still won't trust its certificates and will fail with the following error:

request to https://localhost:8081/repository/npm-group/karma failed, reason: unable to verify the first certificate.

To resolve this issue, you will need the root certificate in PEM format. If you only have it in CER format (e.g. exported from a browser), you can convert it using openssl:

openssl x509 -inform der -in certificate.cer -out certificate.pem

You can now put the certificate.pem file in the root folder of your project and add the following line to the .npmrc file in the same folder:

cafile=./certificate.pem

This should resolve the certificate trust issue. Again, having the certificate configured in the project folder and committed to source control makes it easy to share with other developers and doesn't affect other projects.