Artifactory provides full support for managing npm packages and ensures optimal and reliable access to npmjs.org. Aggregating multiple npm registries under a virtual repository Artifactory provides access to all your npm packages through a single URL for both upload and download.
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.
Artifactory allows you to define any layout for your npm registries. In order to upload packages according to your custom layout, you need to package your npm files using the npm pack command. 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:
In the Admin module, under Repositories | Remote, click New.
In the New Remote Repository dialog: a. Set the Package Type to npm andthe Repository Key value. b. Specify the URL to the remote registry in the URL field.
Click Save & FInish.
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:
When selected, external dependencies are rewritten.
Remote Repository For Cache
The remote repository aggregated by this virtual repository in which the external dependency will be cached.
A whitelist of Ant-style path expressions that specify where external dependencies may be downloaded from. By default, this is set to ** which means that dependencies may be downloaded from any external source.
For example, if you wish to limit external dependencies to only be downloaded from github.com, you should add **github.com** (and remove the default ** expression).
Using the Npm Command Line
Npm repositories must be prefixed with api/npm in the path
When accessing an npm repository through Artifactory, 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:
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.
Setting the Default Registry
For your npm command line client to work with Artifactory, you first need to set the default npm registry with an Artifactory npm repository using the following command (the example below uses a repository called npm-repo):
Replacing the default registry
npm config set registry http://<ARTIFACTORY_SERVER_DOMAIN>:8081/artifactory/api/npm/npm-repo/
For scoped packages, use the following command:
npm config set @<SCOPE>:registry http://<ARTIFACTORY_SERVER_DOMAIN>: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.
Authenticating the Npm Client
Once you have set the default registry, you need to authenticate the npm client to Artifactory in one of two ways:
Running the npm login command
Using basic authentication.
Using Npm login
Authentication using npm login was introduced in version 5.4.
Run the following command in your npm client. When prompted, provide your Artifactory login credentials:
Upon running this command, Artifactory creates a non-expirable access token which the client uses for authentication against Artifactory for subsequent and npm installnpm publish actions.
If the token is removed from Artifactory, the client will have to log in again to receive a new token.
Using Basic Authentication
To support basic authentication, edit your .npmrc file and enter the following:
By default, the "latest" version of a package in an NPM registry in Artifactory is the one with the highest
SemVer version number. You can override this so that the most recently uploaded package is returned by Artifactory as the "latest" version. To do so, in Artifactory's system.properties file, add or set:
artifactory.npm.tag.tagLatestByPublish = true
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 trace how users interact with your repositories you need to disable 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 the npm login command.
Artifactory supports a variety of ways to search artifacts. For details, please refer to Searching Artifacts. Artifactory also supports npm search [search terms ...]. However, these packages may not be available immediately after being published for the following reasons:
Local Repositories: 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.
Virtual repositories: Since a virtual repository may contain local repositories, a newly published package may not be available immediately for the same reason.
To modify the indexing "quiet period", (time since the package was published), configure the following system properties (in $ARTIFACTORY_HOME/etc/artifactory.system.properties).
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 the Property Search to search for npm packages according to their name or version.
Cleaning Up the Local Npm Cache
The npm client saves cached 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.
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. In order to work with npm scoped packages, you can override this default behavior by defining the following property in the catalina.properties file of your Tomcat:
You can also add -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true to the $ARTIFACTORY_HOME/etc/default for service installations or $ARTIFACTORY_HOME/bin/artifactory.default file. Note that since Artifactory version 4.4.3, the bundled Tomcat is configured by default to enable encoded slashes. If you are using a previous version you will need to adjust the Tomcat property above.
URL decoding and reverse proxy
If Artifactory is running behind a reverse proxy, make sure to disable URL decoding on the proxy itself in order to work with npm scope packages.
For Apache, add the "AllowEncodedSlashes NoDecode" directive inside the <VirtualHost *:xxx> block.
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.
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.
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: