{inall}
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.
{pro} and {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 the will be proxied.
In addition, {pro} and {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. See [rhc] for details. |
To simplify configuration {pro} and {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.
|
Important
|
npm support is a feature of version 2.10 and higher and is available in {pro} and {oss} and requires npm version 1.4 and above. |
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 [confignx-sect-manage-repo]. 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 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 |
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 [confignx-sect-manage-repo]. A sample configuration for an internal releases npm hosted repository is displayed in 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 [scheduled-tasks].
A repository group is the recommended way to expose all your npm 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 [repository-groups].
An example would be to group the proxy repository that proxies the npm registry, an npm hosted repository with internal software packages, and another npm hosted repository with third-party packages.
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 repositories with one URL. Any new packages added as well as any new repositories added to the group will automatically be available.
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 = 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 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. You can create this encoded string with the command line call openssl e.g.: for the default admin user:
echo -n 'admin:admin123' | openssl base64
Optionally, you can generate a longer encoded string to a single line with this command:
echo -n 'username:password' | openssl base64 -A
Other tools for the encoding are uuencode or, for Windows users, 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-----
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=
|
Tip
|
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.