npm Registry

Repository Layout

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 thenpm packcommand. This creates the .tgz file for your package which you can then upload to any path within your local npm repository.

Remote npm Registry

ARemote Repositorydefined in Artifactory serves as a caching proxy for a registry managed at a remote URL such ashttps://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:

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:

1. Create avirtual repository, set thePackage Typetonpm.
2. Select the underlying local and remote npm registries to include in theBasicsettingstab.
   
3. ClickSave & Finishto create the repository.

Advanced Configuration

The fields underExternal Dependency Rewriteare connected toautomatically rewriting external dependenciesfor npm packages that require 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 ofNode.js.

Please refer toInstalling Node.js via package manageron GitHub or thenpm README page.

Once you have created your npm repository, you can select it in the Tree Browser and clickSet Me Upto 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 callednpm-repo):

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

For scoped packages, use the following command:

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

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 thenpm logincommand
• Using basic authentication.

Using npm login

Authentication usingnpm loginwas introduced in version 5.4.

Run the following command in your npm client. When prompted, provide your Artifactory login credentials:

npm login

Upon running this command, Artifactory creates anon-expirable access tokenwhich the client uses for authentication against Artifactory for subsequent andnpm installnpm publishactions.

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.npmrcfile and enter the following:

• Your Artifactory username and password (formattedusername:password) asBase64encoded strings
• Your email address (npm publishwill not work if your email is not specified in.npmrc)
• Setalways-auth = true

$ curl -uadmin: http://:8081/artifactory/api/npm/auth

_auth = YWRtaW46e0RFU2VkZX1uOFRaaXh1Y0t3bHN4c2RCTVIwNjF3PT0= email = myemail@email.com always-auth = true

If, in addition, you are also working with scoped packages, you also need to run the following command:

curl -uadmin: http://:8081/artifactory/api/npm/npm-repo/auth/

Where is your Artifactory password orAPI Key.

粘贴这个命令的响应~/.npmrcfile on your machine (in Windows,%USERPROFILE%/.npmrc).

Resolving npm Packages

Once the npm command line tool is configured, everynpm installcommand 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 Audit

Artifactory now supportsnpm audit, allowing you to get vulnerabilities on your npm projects’ dependencies tree.

Audit reports contain information about security vulnerabilities of dependencies and can help fix a vulnerability by providing npm commands and recommendations for further troubleshooting.

This functionality will be enabled by default on npm virtual repositories that aggregate at least one remote repository that supports npm audit. For example, a remote repository that points tohttps://registry.npmjs.orgor Artifactory Smart Remote repository.

JFrog Xray users with Artifactory Pro X / Enterprise / Enterprise+ license, will get an enhanced audit report that includes security vulnerabilities from Xray's database. When Xray is configured to work with Artifactory, an audit report can be generated from scratch even without connecting to any remote repository.

Users withRead Permissionon the npm virtual repository can use the following npm commands:

In order to change the source of the npm audit reports, set the "npm.default.audit.provider" system property (default "https://registry.npmjs.org") to your desired audit provider url.

npm Publish (Deploying Packages)

Setting Your Credentials

The npm command line tool requires that sensitive operations, such aspublishare authenticated as described underAuthenticating the npm Clientabove.

Deploying Your Packages

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

• Edit yourpackage.jsonfile and add apublishConfigsection to a local repository:
  "publishConfig":{"registry":"http://localhost:8081/artifactory/api/npm/npm-local/"}


• Provide a local repository to thenpm publishcommand:
  npm publish --registryhttp://localhost:8081/artifactory/api/npm/npm-local/

Specifying the Latest Version

By default, the "latest" version of a package in an npm registry in Artifactory is the one with the highestSemVerversion 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 theAdminmodule underSecurity | General. For details, please refer toAllow Anonymous Access.
If you want to trace how users interact with your repositories you need to disable theAllow Anonymous Accesssetting. This means that users will be required to enter their username and password as described inSetting Your Credentialsabove.

Using OAuth Credentials

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

npm Search

Artifactory supports a variety of ways to search artifacts. For details, please refer toSearching Artifacts.
Artifactory also supportsnpm 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 calculatesthe search index asynchronously.
• Virtual repositories: Since a virtual repository may contain local repositories, a newly published package may not be available immediately for the same reason.

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

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.

我们建议删除npm缓存(包s 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 fromhttps://registry.npmjs.org.

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

npm Scope Packages

Artifactory fully supportsnpm 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

作用域可以关联到一个单独的注册表。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@jfrogwith the registryhttp://localhost:8081/artifactory/api/npm/npm-local/by manually altering your~/.npmrcfile 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:8081/artifactory/api/npm/npm-local/
//localhost:8081/artifactory/api/npm/npm-local/:_password=QVA1N05OaHZTMnM5Qk02RkR5RjNBVmF4TVFl
//localhost:8081/artifactory/api/npm/npm-local/:username=admin
//localhost:8081/artifactory/api/npm/npm-local/:email=admin@www.si-fil.com
//localhost:8081/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.jsonfile. 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:

• Select theEnable Dependency Rewritecheckboxin the npm virtual repositoryadvanced configuration.
• Specify a whitelist pattern 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 following example, the external dependencies are cached in the "npm" remote repository and only the package fromhttps://github.com/jfrogdevis allowed to be cached.

Artifactory supports all possible shorthand resolvers including the following:

git + ssh: / / user@hostname:项目。git# commit-ish git+ssh://user@hostname/project.git#commit-ish git+https://git@github.com//.git

Rewriting Workflow

1. When downloading an npm package, Artifactory analyzes the list of dependencies required by the package.

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

   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'spackage.jsonfile 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.

SemVer Support

From Artifactory 6.17, the external dependency rewrite feature for the npm virtual repository supports additional SemVerexpressions, such assemver:4.x.0.

If you encounter SemVer issues, you can revert the changes using the new feature flag,artifactory.npm.semver4j.enabled, by changing its value to false.

Viewing Individual npm Package Information

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

In theTree Browser,drill down to select the TGZ file you want to inspect. The metadata is displayed in the npm Infotab.

npm Build Information

You may store exhaustive build information in Artifactory by running your npm builds with JFrog CLI.

JFrog CLI collects build-info from your build agents and then publishes it to Artifactory. Once published, the build info can be viewed in theBuild BrowserunderBuilds.

For more details on npm build integration using JFrog CLI, please refer toBuilding npm Packagesin the JFrog CLI User Guide.

Watch the Screencast