# 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`)](#configuration-jf-npm-config) * [Run npm commands (`jf npm`)](#build-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`](jf-yarn.md). For pnpm-based projects, use [`jf pnpm`](jf-pnpm.md). ## 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 | Flag | Default | Description | | --------------------- | ------- | ----------------------------------------------- | | `--global` | `false` | Apply configuration globally for all projects | | `--server-id-resolve` | — | Artifactory server ID for dependency resolution | | `--server-id-deploy` | — | Artifactory server ID for deployment | | `--repo-resolve` | — | Repository for resolving dependencies | | `--repo-deploy` | — | Repository for deploying packages | ### Configuration Examples #### View Help ```bash jf npm-config --help ``` #### Non-Interactive Configuration Configure npm with non-interactive flags: ```bash jf npm-config --server-id-resolve= --repo-resolve= --server-id-deploy= --repo-deploy= ``` Where: * \: The server ID configured using `jf config add` * \: The name of the repository in Artifactory For example: ```bash 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: ```bash 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 [options] ``` **Aliases:** none ### Arguments | Argument | Required | Description | | --------------- | -------- | ------------------------------------------------------------------- | | `npm-arguments` | Yes | npm command and arguments (for example, `install`, `ci`, `publish`) | ### Subcommands | Subcommand | Description | | -------------------------------- | --------------------------------------------------------------------- | | `install`, `i`, `isntall`, `add` | Install dependencies | | `ci` | Install dependencies from package-lock (CI mode) | | `publish`, `p` | Pack and deploy the package to the designated artifact repository | | `dist-tag`, `dist-tags` | Manage distribution tags (uses the deployer repository configuration) | ### Build Options | Flag | Default | Description | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--build-name` | — | Build name for build information (requires `--build-number`) | | `--build-number` | — | Build number for build information (requires `--build-name`) | | `--project` | — | JFrog Artifactory project key | | `--module` | — | Optional module name for build information | | `--run-native` | `false` | **\[Deprecated]** Use the `JFROG_RUN_NATIVE=true` environment variable instead. When set, uses the native npm client and your existing `.npmrc` configuration file. JFrog CLI doesn't create its own temporary `.npmrc`. All configurations, including authentication, must be handled by your `.npmrc` file. | | `--detailed-summary` | `false` | Include a list of affected files in the command output summary (publish only) | | `--scan` | `false` | Scan all files with Xray before upload; skip upload if vulnerabilities are found (publish only) | | `--format` | `table` | Output format for the `--scan` option. Accepts `table`, `json`, `simple-json`, or `sarif` (publish only) | | `--workspaces` | `false` | Set to `true` to publish all packages defined in npm workspaces. Each workspace package is packed and deployed to Artifactory (publish only). | ### 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 ```bash jf npm install ``` **Expected output (truncated):** ``` npm warn deprecated inflight@1.0.6: This module is not supported... added 145 packages in 3s ``` #### Publish with Build Information ```bash jf npm publish --build-name= --build-number= ``` **Expected output:** ``` npm notice Publishing to https://.jfrog.io/artifactory/api/npm/npm-local/ + my-package@1.0.0 ``` #### Run npm ci ```bash 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: ```bash 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: ```bash jf npm publish --workspaces --build-name=my-monorepo --build-number=1 ``` #### Publish Using Native Mode ```bash 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](native-mode.md). ## CI/CD Example (GitHub Actions) ```yaml # .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 | Symptom | Cause | Fix | | ------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | `no config file was found` | `jf npm-config` was not run | Run `jf npm-config` in the project directory | | 404 on `jf npm install` | Resolution repository does not exist or name is wrong | Verify the repo name matches an existing npm virtual repository in Artifactory | | 401 / 403 on install or publish | Invalid credentials or insufficient permissions | Re-run `jf config add` with a valid access token; check repo permissions | | `jf npm publish` succeeds but package not visible | Published to wrong repository or repository type mismatch | Confirm `--repo-deploy` points to an npm **local** repository | | `prepublish` scripts not executing | Wrapped mode uses `pack`, not `publish` lifecycle | Rename `prepublish`/`postpublish` scripts to `prepack`/`postpack`, or use `--run-native` | | Build-info shows 0 dependencies | `--build-name` and `--build-number` not passed to `jf npm install` | Add both flags to the install/ci command | **Enable debug logging:** `export JFROG_CLI_LOG_LEVEL=DEBUG`
## Related Topics * [Build Tools Overview](/artifactory/docs/build-tool-commands) — Capabilities matrix and tool reference * [Native Mode](/artifactory/docs/native-mode) — Supported packages with Native Mode