Documentation Nexus Repository Manager 3.0

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

Chapter 9. Node Packaged Modules and npm Registries

Available in Nexus Repository OSS and Nexus Repository Pro

9.1. Introduction

The command line tool npm is a package management solution for Javascript-based development. It is used to create and use node packaged modules and is built into the popular Javascript platform Node.js, which is mostly used for server-side application development.

The npmjs website, available at https://www.npmjs.org, provides search and other convenience features to access the public registry at https://registry.npmjs.org/. It is the default package registry, from which components can be retrieved. It contains a large number of open source packages for Node.js based server-side application development, build tools like bower or grunt and many other packages for a variety of use cases.

Nexus Repository Manager Pro and Nexus Repository Manager OSS support the npm registry format for proxy repositories. This allows you to take advantage of the packages in the npm registry and other public registries without incurring repeated downloads of packages, since they will be proxied in the repository manager.

In addition, Nexus Repository Manager supports running your own private registry - also known as a hosted repository using the npm format. You can share internally developed, proprietary packages within your organization via these private registries allowing you to collaborate efficiently across development teams with a central package exchange and storage location.

To simplify configuration Nexus Repository Manager supports aggregation of npm registries. This allows you to expose all the external packages from the npm registry and other public registries as well as the private registries as one registry, which greatly simplifies client configuration.

To share a package or tool with npm, you create a npm package and store it in the npm registry hosted by the repository manager. Similarly, you can use packages others have created and made available in their NPM repositories by proxying them or downloading the packages and installing them in your own private registry for third party packages.

9.2. Proxying npm Registries

To reduce duplicate downloads and improve download speeds for your developers and CI servers, you should proxy the registry hosted at https://registry.npmjs.org. By default npm accesses this registry directly. You can also proxy any other registries you require.

To proxy an external npm registry, you simply create a new npm (proxy) as documented in Section 4.3, “Repository Management”.

Minimal configuration steps are:

  • Define Name
  • Define URL for Remote storage e.g. https://registry.npmjs.org
  • Select Blob store for Storage

9.3. Private npm Registries

A private npm registry can be used to upload your own packages as well as third-party packages. You can create a private npm registry by setting up a hosted repository with the npm format in the repository manager. It is good practice to create two separate hosted repositories for these purposes.

To create a hosted repository with npm format, simply create a new npm (hosted) as documented in Section 4.3, “Repository Management”.

Minimal configuration steps are:

  • Define Name
  • Select Blob store for Storage

The npm registry information is immediately updated as packages are deployed or deleted from the repository.

9.4. Grouping npm Registries

A repository group is the recommended way to expose all your npm registries repositories from the repository manager to your users, without needing any further client side configuration. A repository group allows you to expose the aggregated content of multiple proxy and hosted repositories with one URL to npm and other tools. This is possible for npm repositories by creating a new npm (group) as documented in Section 4.3, “Repository Management”.

Minimal configuration steps are:

  • Define Name
  • Select Blob store for Storage
  • Add npm repositories to the Members list in the desired order

A typical, useful example would be to group the proxy repository that: proxies the npm registry, a npm, hosted repository with internal software packages and another npm, hosted repository with third-party packages.

Using the URL of the repository group as your npm repository URL in your client tool will give you access to the packages in all three repositories with one URL. Any new packages added as well as any new repositories added to the group will automatically be available.

9.5. Browsing npm Registries and Searching Modules

You can browse npm repositories in the user interface inspecting the components and assets and their details as documented in Section 3.4, “Browsing Repositories and Repository Groups”.

Searching for npm modules can be performed in the user interface as described in Section 3.3, “Searching for Components”. This search will find all npm modules images that are currently stored in the repository manager, either because they have been pushed to a hosted repository or they have been proxied from an upstream repository and cached in the repository manager.

9.6. Configuring npm

Once you have set up your hosted and proxy repositories for npm packages, and created a repository group to merge them, you can access them with the npm tool on the command line as one registry.

You can configure the registry used by npm in your .npmrc file located in your user’s home directory with the npm config command and the public URL of your repository group in the repository list in the Repository Path column.

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

The command inserts the configuration in the .npmrc file in your users home directory.

Registry configuration in .npmrc

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

With this configuration any npm commands will use the new registry from the repository manager. The command line output will reference the URLs in --verbose mode or with info logging for the downloads of the requested packages:

$ npm --loglevel info install grunt
...
npm http fetch GET http://localhost:8081/repository/npmjs-org/grunt/-/grunt-0.4.5.tgz
npm http fetch 200 http://localhost:8081/repository/npmjs-org/grunt/-/grunt-0.4.5.tgz
...
npm http fetch GET http://localhost:8081/repository/npm-all/underscore/-/underscore-1.7.0.tgz
npm http fetch 200 http://localhost:8081/repository/npm-all/underscore/-/underscore-1.7.0.tgz

...

9.7. npm Security

By default any anonymous user has read access to the repositories and repository groups. If anonymous access, as documented in Section 5.6, “Anonymous Access” is disabled, or write access is required for publishing a package, the user needs to authenticate to the repository manager.

This authentication requires the npm Bearer Token Realm. Simply add the realm to the active realms in the Realms feature of the Security menu from the Administration menu to activate it as documented in Section 5.2, “Realms”.

Once the realm is activated, a user can establish the authentication to a repository with the npm login command.

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

Provide your repository manager username and password as well as your email address when prompted. Upon successful completion, a line for authentication of this combination is automatically added to your .npmrc configuration file for the specific repository.

Further details on npm login can be found on the npm website.

9.8. Publishing npm Packages

Publishing your own packages to a npm hosted repository allows you to share packages across your organization or with external partners. With authentication configured you can publish your packages with the npm publish command.

The npm publish command uses a registry configuration value to know where to publish your package. There are several ways to change the registry value to point at your hosted npm repository.

Since the .npmrc file usually contains a registry value intended only for getting new packages, a simple way to override this value is to provide a registry to the publish command:

npm publish --registry http://localhost:8081/repository/npm-internal/

Alternately, you can edit your package.json file and add a publishConfig section:

  "publishConfig" : {
    "registry" : "http://localhost:8081/repository/npm-internal/"
  },

Detailed information about package creation can be found on the npm website.

If your package requires the use of npm scope, the repository manager supports this functionality. Packages published to the repository manager with a defined scope are reflected with the scope value populating the repository group field in Browse and Search. Details on scoping are available on the npm website also.

Once a package is published to the private registry in the repository manager, any other developers or build servers that access the repository manager via the repository group have instant access to it.

9.9. Deprecating npm Packages

Once your packages have been pushed to an npm hosted repository, you can mark them as deprecated. This is useful when a newer version of the package is available, and you want to warn people that the old package has reached end of life or you want to avoid usage and warn your users for some other reason.

The npm deprecate command uses a registry configuration value to inform where the package lives. To deprecate an existing package, use a command like the following:

npm deprecate --registry http://localhost:8081/repository/npm-internal/ testproject1@0.0.1 "This package is deprecated"

If you change your mind, you can reverse this action using the same command. To undeprecate a package, pass an empty string to the deprecate command:

npm deprecate --registry http://localhost:8081/repository/npm-internal/ testproject1@0.0.1 ""

The message text is persisted in the deprecated attribute of the packageJson section for the asset and can be viewed in the user interface.