Use npm with JFrog CLI

Run npm commands with Artifactory integration for dependency resolution and build information collection.

This topic covers the following tasks:

• Configure npm for Artifactory (jf npm-config)
• Run npm commands (jf npm)
• Fail on uncollected dependencies

When to Use

Use jf npm if your JavaScript or TypeScript project uses npm for dependency management and you want packages resolved from and published to JFrog Artifactory. For Yarn-based projects, use jf yarn. For pnpm-based projects, use jf pnpm.

Prerequisites

• npm must be installed (version 5.4.0 or above).
• JFrog Artifactory version 5.5.2 or above is required when the CLI obtains npm credentials from the Artifactory /api/npm/auth API (for example, typical password-based flows, or when the CLI cannot set authentication via access token for your npm version). If you use an access token with a supported npm client, the CLI may build authentication without calling that API, so that version check may not apply to your setup.
• Configure a server with jf config add or jf c add (equivalent to the older jfrog binary: jfrog config add or jfrog c add). The built-in jf npm-config --help text may still refer to jfrog c add. The command is the same.
• Authentication to JFrog Artifactory is required.
• Run jf npm-config in the project directory before the first build.

Configuration: jf npm-config

Generate npm configuration for resolving and deploying packages through JFrog Artifactory. Run this once per project before your first build.

To generate npm configuration for a project:

1. Add a JFrog CLI server with jf config add (or jf c add) if you have not already.
2. Run jf npm-config with --server-id-resolve, --repo-resolve, and optionally --server-id-deploy and --repo-deploy, as shown in Configuration Examples.

Synopsis

jf npm-config [options]

Aliases: npmc

Configuration Options

The following table describes jf npm-config flags.

Configuration Examples

View Help

jf npm-config --help

Non-interactive Configuration

Configure npm with non-interactive flags:

jf npm-config --server-id-resolve=<server_id> --repo-resolve=<repository_key> --server-id-deploy=<server_id> --repo-deploy=<repository_key>

Where:

• <server_id> matches a server from jf config add.
• <repository_key> is the target npm repository key in JFrog Artifactory.

For example:

jf npm-config --server-id-resolve=my-server --repo-resolve=npm-virtual --server-id-deploy=my-server --repo-deploy=npm-local

Note: jf npm-config only writes .jfrog/projects/npm.yaml (or the global equivalent). It does not check that the resolve or deploy repository keys exist in JFrog Artifactory or that they are the correct npm repository type. A typo or wrong repository name still produces npm build config successfully created. You may only see 404, 401, or 403 on the first jf npm install, jf npm ci, or jf npm publish. Confirm repository names in JFrog Artifactory before relying on the config step.

Why Run Config First?

You must run jf npm-config before running jf npm install or jf npm publish. The config command creates a .jfrog/projects/npm.yaml file in your project directory that tells the CLI which JFrog Artifactory repositories to use for resolution and deployment. Without it, jf npm does not know where to fetch or publish packages.

In CI/CD, pass all flags non-interactively so the config step is fully automated and reproducible.

Configuration Notes

• Run once per project. The configuration persists in .jfrog/projects/. Re-run only when changing repository assignments.
• Global compared to project: Use --global to apply to all npm projects on the machine. Without it, configuration is project-specific (recommended).
• Server must exist: The --server-id-resolve and --server-id-deploy values must match a server added via jf config add (or jf c add).
• Native mode (jf npm, not jf npm-config): Native behavior is controlled when you run jf npm install, jf npm ci, or jf npm publish, by setting JFROG_RUN_NATIVE=true or using the deprecated --run-native flag on those commands. In native mode the CLI does not create a temporary .npmrc for those flows. Your existing .npmrc is used. jf npm-config does not define a --run-native option. It only writes project (or global) YAML under projects/npm.yaml.

Expected Output

The CLI logs a line like the following (your logger may add a level prefix such as [Info]):

npm build config successfully created.

Example:

$ jf npm-config --server-id-resolve=my-server --repo-resolve=npm-virtual --server-id-deploy=my-server --repo-deploy=npm-local
npm build config successfully created.

How to Verify

After running without --global, confirm the configuration exists under your project (or a parent directory):

cat .jfrog/projects/npm.yaml

If you used jf npm-config --global, the file is under the JFrog home directory, for example:

cat ~/.jfrog/projects/npm.yaml

JFrog CLI normally uses ~/.jfrog as the home directory. If JFROG_HOME is set, global project config lives under $JFROG_HOME/projects/npm.yaml instead.

Build: jf npm

Run npm commands with JFrog Artifactory integration for dependency resolution and build information collection.

To run an npm command through JFrog CLI:

1. Complete jf npm-config for the project (see Configuration).
2. Run jf npm followed by the npm subcommand and options you need (see Subcommands and Build Options).

Synopsis

jf npm <npm_arguments> [options]

Aliases: none

Arguments

The following table describes jf npm arguments.

Subcommands

The following table lists common jf npm subcommands.

Note: jf npm --help may list only install, ci, publish, and help. dist-tag and dist-tags are still supported. Invoke them the same way as with npm, for example jf npm dist-tag add package@version tag. Do not rely on --help alone for the full list of wrapped npm subcommands.

Build Options

The following table describes jf npm options.

Publishing Scripts: Wrapped Compared to Native

When building npm packages, it is important to understand how the jf npm publish command handles publishing scripts:

• Default behavior (without --run-native): JFrog CLI runs the pack command in the background, followed by an upload action not based on the npm client's native publish command. If your npm package includes prepublish or postpublish scripts, you must rename them to prepack and postpack respectively to ensure they are executed.
• Behavior with --run-native: The command uses the native npm client's own publish lifecycle. Standard npm script names such as prepublish, publish, and postpublish are handled directly by npm itself, and no renaming is necessary.

Note: The deployment view and details summary features are not supported by the jf npm install and jf npm ci commands. This limitation applies regardless of whether the --run-native flag is used.

Build Examples

Install Dependencies

jf npm install

Expected output (truncated):

npm warn deprecated [email protected]: This module is not supported...
added 145 packages in 3s

Publish With Build Information

jf npm publish --build-name=<build_name> --build-number=<build_number>

Where:

• <build_name> and <build_number> identify the build-info record.

For example:

jf npm publish --build-name=my-app --build-number=42

Expected output:

npm notice Publishing to https://<server>.jfrog.io/artifactory/api/npm/npm-local/
+ [email protected]

Run npm ci

jf npm ci --build-name=my-app --build-number=1

Fail When Dependencies Cannot Be Collected

Fail the command if any dependency type cannot be collected into build information:

jf npm ci --build-name=my-app --build-number=1 --fail-on-uncollected-deps=all

Fail only for regular and optional dependencies:

jf npm install --build-name=my-app --build-number=1 --fail-on-uncollected-deps=regular,optional

See Fail on Uncollected Dependencies.

Install Using Native Mode

Install dependencies using the native npm client, based on the .npmrc configuration:

export JFROG_RUN_NATIVE=true

jf npm install

jf npm install --build-name=my-native-build --build-number=1

Publish npm Workspaces

Publish all workspace packages in a monorepo:

jf npm publish --workspaces --build-name=my-monorepo --build-number=1

Publish Using Native Mode

export JFROG_RUN_NATIVE=true
jf npm publish

Ensure your package.json and .npmrc are configured for publishing.

Fail on Uncollected Dependencies

By default, jf npm install and jf npm ci still succeed when JFrog CLI cannot collect a dependency's integrity or checksum for build information. The package is usually installed. The CLI omits that dependency from the build-info record and logs a warning or debug message.

Use --fail-on-uncollected-deps when you want the command to fail instead of publishing partial build information. The flag is available on jf npm install and jf npm ci. It is not available on jf npm publish. Requires JFrog CLI 2.125.0 or later.

To fail the build when selected dependency types cannot be collected:

1. Pass --build-name and --build-number (or set JFROG_CLI_BUILD_NAME and JFROG_CLI_BUILD_NUMBER).
2. Pass --fail-on-uncollected-deps with all or a comma-separated list of types.

Flag Values

The following table describes accepted --fail-on-uncollected-deps values.

Combine types with commas, for example peer,optional,bundle. Values are case-sensitive. Spaces around commas are allowed, for example peer , optional. Trailing commas, leading commas, and empty tokens are rejected.

When the Command Fails

The CLI returns an error for each selected type that has uncollected dependencies. Regular and optional errors mention the npm cache and hint to delete node_modules or package-lock.json. Peer and bundle errors mention that npm ls did not return integrity.

Without the flag, regular misses log a warning such as: The following dependencies will not be included in the build-info, because they are missing in the npm cache. Peer and bundle misses stay at debug.

Native Mode

npm supports native mode, which uses the user's .npmrc file instead of JFrog CLI-managed configuration. Unlike other tools, build-info collection still works in npm native mode.

Enable with export JFROG_RUN_NATIVE=true (the --run-native flag is deprecated).

For full setup instructions, per-tool comparison, and when to use each mode, see Native Mode.

CI/CD Example: GitHub Actions

The following workflow snippet shows a typical pattern.

# .github/workflows/build.yml
steps:
  - uses: actions/checkout@v4
  - name: Setup JFrog CLI
    uses: jfrog/setup-jfrog-cli@v4
    env:
      JF_URL: ${{ vars.JF_URL }}
      JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
  - name: Configure npm
    run: jf npm-config --server-id-resolve=setup-jfrog-cli-server --repo-resolve=npm-virtual --server-id-deploy=setup-jfrog-cli-server --repo-deploy=npm-local
  - name: Install dependencies
    run: jf npm ci --build-name=my-app --build-number=${{ github.run_number }}
  - name: Publish build info
    run: jf rt build-publish my-app ${{ github.run_number }}

Troubleshooting

The following table lists common symptoms, causes, and fixes.

Enable debug logging: export JFROG_CLI_LOG_LEVEL=DEBUG

Frequently Asked Questions

This section provides answers to frequently asked questions about using npm with JFrog CLI.

Related Topics

• Build Tools Overview
• Native Mode
• Use JFrog CLI Package Alias
• Supported Package Manager Versions