Npm Registry

Configuration

Local Npm Registry

To enable calculation of npm package metadata in local repositories so they are, in effect, npm registries,  set the Package Type to npm when you create the repository:

Repository Layout

Artifactory allows you to define any layout for your npm regsitries. In order to upload packages according to your custom layout, you need to package your npm files using npm pack.

This creates the .tgz file for your package which you can then upload to any path within your local npm repository.

Remote Npm Registry

A Remote Repository defined in Artifactory serves as a caching proxy for a registry managed at a remote URL such as https://registry.npmjs.org.

Artifacts (such as tgz files) requested from a remote repository are cached on demand. You can remove downloaded artifacts from the remote repository cache, however, you can not manually deploy artifacts to a remote npm registry. 

To define a remote repository to proxy a remote npm registry follow the steps below:

Virtual Npm Registry

A Virtual Repository defined in Artifactory aggregates packages from both local and remote repositories.
This allows you to access both locally hosted npm packages and remote proxied npm registries from a single URL defined for the virtual repository.
To define a virtual npm registry, create a virtual repository, set the Package Type  to be npm,  and select the underlying local and remote npm registries to include in the Basic settings tab.

Click "Save & Finish" to create the repository.

Advanced Configuration

The fields under External Dependency Rewrite are connected to automatically rewriting external dependencies for npm packages that need them.

Using the Npm Command Line

To use the npm command line you need to make sure npm is installed. Npm is included as an integral part of recent versions of  Node.js. 

Please refer to  Installing Node.js via package manager on GitHub or the npm README page.

Once you have created your npm repository, you can select it in the Tree Browser and click Set Me Up to get code snippets you can use to change your npm registry URL, deploy and resolve packages using the npm command line tool.

To replace the default registry with a URL pointing to an npm repository in Artifactory (the example below uses a repository with the key npm-repo):

npm config set registry http://localhost:8081/artifactory/api/npm/npm-repo

Once the npm command line tool is configured, every npm install command will fetch packages from the npm repository specified above. For example:

$ npm install request
npm http GET http://localhost:8081/artifactory/api/npm/npm-repo/request
npm http 200 http://localhost:8081/artifactory/api/npm/npm-repo/request
npm http GET http://localhost:8081/artifactory/api/npm/npm-repo/request/-/request-2.33.0.tgz
npm http 200 http://localhost:8081/artifactory/api/npm/npm-repo/request/-/request-2.33.0.tgz

Npm Publish (Deploying Packages)

Setting Your Credentials

The npm command line tool requires that sensitive operations, such as publish, are authenticated with the server using basic HTTP authentication.

To support authentication you need to edit your .npmrc file and enter the following:

• Your Artifactory username and password (formatted username:password) as  Base64 encoded strings 
• Your email address (npm publish will not work if your email is not specified in .npmrc)
• You need to set  always-auth = true

$ curl -uadmin:password "http://localhost:8081/artifactory/api/npm/auth"
_auth = YWRtaW46e0RFU2VkZX1uOFRaaXh1Y0t3bHN4c2RCTVIwNjF3PT0=
email = myemail@email.com
always-auth = true

Deploying Your Packages

There are two ways to deploy packages to a local repository:

• Edit your package.json file and add a publishConfig section to a local repository:
  "publishConfig":{"registry":"http://localhost:8081/artifactory/api/npm/npm-local"}


• Provide a local repository to the npm publish command:
  npm publish --registry http://localhost:8081/artifactory/api/npm/npm-local 

Working with Artifactory without Anonymous Access

By default, Artifactory allows anonymous access to npm repositories. This is defined in the Admin module under Security | General. For details please refer to Allow Anonymous Access.
If you want to be able to trace how users interact with your repositories you need to uncheck the Allow Anonymous Access setting. This means that users will be required to enter their username and password as described in Setting Your Credentials above.

Using OAuth Credentials

Artifactory uses GitHub Enterprise as its default OAuth provider. If you have an account, you may use your GitHub Enterprise login details to be authenticated when using npm login. 

Npm Search

Artifactory supports a variety of ways to search of artifacts. For details please refer to Searching Artifacts.

Artifactory also supports npm search [search terms ...], however, packages may not be available immediately after being published for the following reasons:

When publishing a package to a local repository, Artifactory calculates the search index asynchronously and will wait for a "quiet period" to lapse before indexing the newly published package.

Since a virtual repository may contain local repositories, a newly published package may not be available immediately for the same reason.

You can specify the indexing "quiet period" (time since the package was published) by setting the following system properties (in $ARTIFACTORY_HOME/etc/artifactory.system.properties) .  

artifactory.npm.index.quietPeriodSecs=60
artifactory.npm.index.cycleSecs=60

In the case of remote repositories,  a new package will only be found once Artifactory checks for it according to the Retrieval Cache Period setting.

Cleaning Up the Local Npm Cache

The npm client saves caches of packages that were downloaded, as well as the JSON metadata responses (named .cache.json).

The JSON metadata cache files contain URLs which the npm client uses to communicate with the server, as well as other ETag elements sent by previous requests.

We recommend removing the npm caches (both packages and metadata responses) before using Artifactory for the first time. This is to ensure that your caches only contain elements that are due to requests from Artifactory and not directly from https://registry.npmjs.org.

The default cache directory on Windows is %APPDATA%\npm-cache while on Linux it is ~/.npm.

Npm Scope Packages

Artifactory fully supports npm scope packages. The support is transparent to the user and does not require any different usage of the npm client.

Configuring the npm Client for a Scope Registry

Using Login Credentials

Scopes can be associated with a separate registry. This allows you to seamlessly use a mix of packages from the public npm registry and one or more private registries.

For example, you can associate the scope @jfrog with the registry http://localhost:8081/artifactory/api/npm/npm-local/ by manually altering your ~/.npmrc file and adding the following configuration:

@jfrog:registry=http://localhost:8081/artifactory/api/npm/npm-local/
//localhost:8081/artifactory/api/npm/npm-local/:_password=cGFzc3dvcmQ=
//localhost:8081/artifactory/api/npm/npm-local/:username=admin
//localhost:8081/artifactory/api/npm/npm-local/:email=myemail@email.com
//localhost:8081/artifactory/api/npm/npm-local/:always-auth=true

$ curl -uadmin:password "http://localhost:8081/artifactory/api/npm/npm-local/auth/jfrog"
@jfrog:registry=http://localhost:8080/artifactory/api/npm/npm-local/
//localhost:8080/artifactory/api/npm/npm-local/:_password=QVA1N05OaHZTMnM5Qk02RkR5RjNBVmF4TVFl
//localhost:8080/artifactory/api/npm/npm-local/:username=admin
//localhost:8080/artifactory/api/npm/npm-local/:email=admin@jfrog.com
//localhost:8080/artifactory/api/npm/npm-local/:always-auth=true

Automatically Rewriting External Dependencies

Packages requested by the Npm client frequently use external dependencies as defined in the packages' package.json file. These dependencies may, in turn, need additional dependencies. Therefore, when downloading an Npm package, you may not have full visibility into the full set of dependencies that your original package needs (whether directly or transitively). As a result, you are at risk of downloading malicious dependencies from unknown external resources. To manage this risk, and maintain the best practice of consuming external packages through Artifactory, you may specify a "safe" whitelist from which dependencies may be downloaded, cached in Artifactory and configure to rewrite the dependencies so that the Npm client accesses dependencies through a virtual repository as follows:

• Check Enable Dependency Rewrite in the Npm virtual repository advanced configuration.
• Specify a whitelist patterns of external resources from which dependencies may be downloaded. 
• Specify the remote repository in which those dependencies should be cached.
  It is preferable to configure a dedicated remote repository for that purpose so it is easier to maintain. 

In the example below the external dependencies will be cached in "npm" remote repository and only package from https://github.com/jfrogdev are allowed to be cached. 

Rewriting Workflow

1. When downloading an Npm package, Artifactory analyzes the list of dependencies needed by the package.

2. If any of the dependencies are hosted on external resources (e.g. on github.com), and those resources are specified in the white list,

   1. Artifactory will download the dependency from the external resource.

   2. Artifactory will cache the dependency in the remote repository configured to cache the external dependency.

   3. Artifactory will then modify the dependency's entry in the package's package.json file indicating its new location in the Artifactory remote repository cache before returning it to the Npm client.

3. Consequently, every time the Npm client needs to access the dependency, it will be provisioned from its new location in the Artifactory remote repository cache.

Viewing Individual Npm Package Information

Artifactory lets you view selected metadata of an npm package directly from the UI.

In the Tree Browser, drill down to select the tgz file you want to inspect. The metadata is displayed in the Npm Info tab.