jf npm

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)

When to Use

Use jf npm if your JavaScript/TypeScript project uses npm for dependency management and you want packages resolved from and published to 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).
• Artifactory version 5.5.2 or above.
• Configure a server with jf config add or jf c add.
• Authentication to 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 Artifactory. Run this once per project before your first build.

To configure npm for Artifactory:

Synopsis

jf npm-config [options]

Aliases: npmc

Configuration Options

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=<repo-name> --server-id-deploy=<server-id> --repo-deploy=<repo-name>

Where:

• <server-id>: The server ID configured using jf config add
• <repo-name>: The name of the repository in Artifactory

For example:

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

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 Artifactory repositories to use for resolution and deployment. Without it, jf npm does not know where to fetch or publish packages.

Shortcut: 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 vs 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.
• Native Client Configuration (--run-native): When the --run-native flag is used, JFrog CLI bypasses the configuration in the .jfrog directory. Instead, it uses your .npmrc file for all configurations, including authentication tokens and other settings.

Expected Output

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

How to Verify

After running, confirm the configuration exists:

cat .jfrog/projects/npm.yaml

Build: jf npm

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

To run npm with Artifactory integration:

Synopsis

jf npm <npm-arguments> [options]

Aliases: none

Arguments

Subcommands

Build Options

Publishing Scripts: Wrapped vs Native

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

• Default behaviour (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.
• Behaviour with --run-native: The command utilizes 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>

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

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.

Native Mode

npm supports Native Mode, which uses your .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)

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

Enable debug logging: export JFROG_CLI_LOG_LEVEL=DEBUG

Related Topics

• Build Tools Overview — Capabilities matrix and tool reference
• Native Mode — Supported packages with Native Mode