Skip to main content

Node Packaged Modules and npm Registries in Nexus Repository 2

Nexus Repository 2

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 addition, Nexus Repository Manager Pro and Nexus Repository Manager OSS support 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.

Note

Users can enable Repository Health Check on a repository using the npm format to retrieve all metadata from components in the repository, such as security and license.

To simplify configuration Nexus Repository Manager Pro and Nexus Repository Manager OSS support aggregation of npm registries. This allows you to expose all the external package 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 repository manager-based npm registry. 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.

Note

npm support is a feature of version 2.10 and higher and is available in Nexus Repository Manager Pro and Nexus Repository Manager OSS and requires npm version 1.4 and above.

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. It is accessed directly by npm out-of-the-box. You can also proxy any other registries you require.

To proxy an external npm registry, you simply create a new Proxy Repository as documented in Managing Repositories. The Provider has to be set to NPM . The Remote Storage Location has to be set to the URL of the remote repository you want to proxy. The official URL for the main npm registry is

https://registry.npmjs.org

A complete configuration for proxying the default npm registry is visible in Figure 16.1, “Proxy Repository Configuration for the npm Registry”.

329795.png

Figure 16.1. Proxy Repository Configuration for the npm Registry

Warning

Browsing the registry storage or the remote registry and searching for packages in the repository manager is not supported

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 Hosted Repository and set the Provider to npm as documented in Managing Repositories. A sample configuration for an internal releases npm hosted repository is displayed in Figure 16.2, “Example Configuration for a Private npm Registry”.

329794.png

Figure 16.2. Example Configuration for a Private npm Registry

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

Warning

Browsing the registry storage or searching for packages is not supported.

The scheduled tasks to recreate the npm metadata database based on the components in a hosted repository and to back up the database are documented in Managing Scheduled Tasks.

Grouping npm Registries

A repository group is the recommended way to expose all your npm registries repositories to your users, without needing any further client side configuration. A repository group allows you to expose the aggregated content of multiple repositories with one URL to npm and other tools. This is possible for npm repositories by creating a new Repository Group with the Provider set to npm as documented in Managing Repository Groups.

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. The configuration for such a setup is displayed in Figure 16.3, “An npm Group Combining the npm Registry and Two Private Registries”.

329793.png

Figure 16.3. An npm Group Combining the npm Registry and Two Private Registries

Using the Repository Path 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.

Configuring npm

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

As shown below, you can configure the registry used by npm in your .npmrc file located in your user’s home directory. If the file does not exist simply create it and add the registry configuration with the URL of your npm repository group. You can find the public URL of your group repository in the repository list in the Repository Path column.

Registry configuration in .npmrc

registry = http://localhost:8081/nexus/content/groups/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 

By default any anonymous user has read access to the repositories and repository groups. If desired, the repository manager can be configured to require authentication by adding always-auth=true to the .npmrc file and adding the encoded authentication details as documented in Publishing npm Packages.

Publishing npm Packages

Publishing your own packages to a npm hosted repository allows you to share packages across your organization or with external partners.

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/nexus/content/repositories/npm-internal/

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

 "publishConfig" : {
    "registry" : "http://localhost:8081/nexus/content/repositories/npm-internal/"
  },

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 a hosted or proxy repository. Scoped packages are distinguishable with an @ placed in front of the scope, followed by a slash ( / ) and package name (e.g. @scope/project-name).

When you publish the package, the user interface will contain a new folder with an @ preceding name of the scope. You can browse scoped packages from the Repository Path column. These packages are alphabetically indexed, in tree view, amid your repository’s overall list of packages.

Further details on scoping are available on the npm website.

Publishing requires authentication. It can be configured by adding an _auth value to .npmrc. The value has to be generated by base64-encoding the string of username:password.

Encoding Credentials on Linux

You can create this encoded string on Linux with the openssl command line tool. For example, for the default admin user:

echo -n 'admin:admin123' | openssl base64

Encoding Credentials on Windows using "certutil"

To use certutil on Windows you need to put the credentials to be encoded into a file:

admin:admin123 

Then run:

c:\certutil /encode in.txt out.txt

After this the base64 encoded credentials can be found in between the begin and end certificate lines in the output file:

-----BEGIN CERTIFICATE-----
YWRtaW46YWRtaW4xMjM=
-----END CERTIFICATE----- 

Encoding Credentials on Windows using Powershell

$Bytes = [System.Text.Encoding]::UTF8.GetBytes("admin:admin123")
[Convert]::ToBase64String($Bytes)

Adding Credentials to the npm Configuration

Once you have the encoded credentials the value as well as author information can then be added to the .npmrc file:

init.author.name = Jane Doe
init.author.email = jane@example.com
init.author.url = http://blog.example.com
# an email is required to publish npm packages
email=jane@example.com
always-auth=true
_auth=YWRtaW46YWRtaW4xMjM=

Note

Using whatever tool you are generating the encoded username and password string, try to encode the string admin:admin123. The result is YWRtaW46YWRtaW4xMjM=. Another example for a valid setup is jane:testpassword123 resulting in amFuZTp0ZXN0cGFzc3dvcmQxMjM=.

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

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