Page tree
Skip to end of metadata
Go to start of metadata

Overview

From version 3.2, Artifactory fully supports npm repositories on top of Artifactory's existing support for advanced artifact management.

Artifactory support for npm provides:

  1. The ability to provision npm packages from Artifactory to the npm command line tool from all repository types
  2. Calculation of Metadata for npm packages hosted in Artifactory's local repositories
  3. Access to remote npm registries (such as https://registry.npmjs.org) through Remote Repositories which provide the usual proxy and caching functionality
  4. The ability to access multiple npm registries from a single URL by aggregating them under a Virtual Repository. This overcomes the limitation of the npm client which can only access a single registry at a time.
  5. Compatibility with the npm command line tool to deploy and remove packages and more.
  6. Support for flexible npm repository layouts that allow you to organize your npm packages and assign access privileges according to projects or development teams.

Support Matrix

Artifactory version

Npm version
3.4.2+2.0+
< 3.4.2All versions from 1.4.3 and below v2.0

 

 

Page Contents


Configuration

Local Repositories

To enable calculation of npm package metadata in local repositories,  in the Edit Local Repository dialog, select the Packages tab and check Enable Npm Support:

Repository Layout

Artifactory allows you to define any layout for your npm repositories. 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.

Using previous versions of Artifactory

Prior to version 3.4.2, Artifactory stored npm packages in a unique layout (which corresponds to the URLs of http://registry.npmjs.org) among other important metadata describing your packages.

Therefore, if you are using an earlier version of Artifactory (below 3.4.2) we strongly recommend that you use npm publish when deploying packages into local repositories. Failing to do so may result in the npm client omitting metadata (e.g contributors).

Deploying npm Packages with Artifactory version below 3.4.2

If you are using a version of Artifactory that is below 3.4.2, please note:

If you choose to deploy npm packages manually (using the Web UI or Artifactory's REST API) you should deploy the tgz file using the following structure so Artifactory will be able to extract metadata from it:

http://localhost:8081/artifactory/npm-local/<packageName>/-/<packageName>-<packageVersion>.tgz

For example:

http://localhost:8081/artifactory/npm-local/express/-/express-3.4.8.tgz

When selecting an npm repository in the Tree Browser, Artifactory displays a corresponding code snippet that you can use to change your npm registry URL.

Remote Repositories

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 repository. 

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

  1. In the Admin tab under Configuration | Repositories  go to the Remote Repositories section and select "New" 
  2. Set the Repository Key value, and specify the URL to the remote registry in the URL field as displayed below
     
  3. In the Packages tab of the New Remote Repository dialog, set Enable Npm Support and click "Create"

Virtual Repositories

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 repository, create or edit a virtual repository, select the underlying local and remote npm repositories to include in the Basic Settings tab, and check Enable Npm Support in the Packages tab.



Using the Npm Command Line

Npm repositories must be prefixed with api/npm in the path

When accessing an npm repository through Artiafctory, the repository URL must be prefixed with api/npm in the path. This applies to all npm commands including npm install and npm publish.

For example, if you are using Artifactory standalone or as a local service, you would access your npm repositories using the following URL:

http://localhost:8081/artifactory/api/npm/<repository key>

Or, if you are using Artifactory Online the URL would be:

https://<server name>.artifactoryonline.com/<server name>/api/npm/<repository key>

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 npm is installed, 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):

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

We recommend referencing a Virtual Repository URL as a registry. This gives you the flexibility to reconfigure and aggregate other external sources and local repositories of npm packages you deployed. 

Note that If you do this, you need to use the --registry parameter to specify the local repository into which you are publishing your package when using the npm publish command.

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

Getting .npmrc entries directly from Artifactory

You can use the following command to get these strings directly from Artifactory:

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

.npmrc file location

Windows: %userprofile%\.npmrc

Linux: ~/.npmrc

Currently not supported

Artifactory does not support the npm adduser command, therefore to publish packages you need to ensure that you have previously created a user on Artifactory.

Note also that the -tag option for npm publish is not currently supported.

Deploying Your Packages

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


Working with Artifactory without Anonymous Access

By default, Artifactory allows anonymous access to npm repositories. This is defined under Security | General Configuration. 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.


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.

Artifactory annotates each deployed or cached npm package with two properties: npm.name and npm.version

You can use Property Search to search for npm packages according to their name or version. 


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 http://registry.npmjs.org.

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


Npm Scope Packages

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

Npm 'slash' character encoding

By default, the npm client encodes slash characters ('/') to their ASCII representation ("%2f") before communicating with the npm registry. If you are running Tomcat as your HTTP container (the default for Artifactory), this generates an "HTTP 400" error since Tomcat does not allow encoded slashes by default. To avoid this error when using npm scope packages, you can override this default behavior by defining the following System Property:

org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

Configuring the npm Client for a Scope Registry

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

Getting .npmrc entries directly from Artifactory

From Artifactory 3.5.3, you can use the following command to get these strings directly from Artifactory:

$ 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

User email is required

When using scope authentication, npm expects a valid email address. Please make sure you have included your email address in your Artifactory user profile.

The password is just a base64 encoding of your Artifactory password, the same way used by the old authentication configuration.

Recommend npm command line tool version 2.1.9 and later.

While npm scope packages have been available since version 2.0 of the npm command line tool, we highly recommend using npm scope packages with Artifactory only from version 2.1.9 of the npm command line tool.


Viewing Individual Npm Package Information

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

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

 

 

 

 

 

 

 

 

 

 

 

  • No labels