<!-- BusyBot node reference — https://busybot.net/tools/npm/ -->

> Node: Npm (`npm`) · Action · v1
> Category: Development · Credentials: Npm API (`npmApi`)
> Updated: 2026-08-16

# Npm

> Search packages, get metadata/versions, and manage dist-tags on npm registries.

## Overview

NPM (Node Package Manager) is the default package manager for Node.js. This tool interacts with npm-compatible registries (npmjs.org, GitHub Packages, Verdaccio, Artifactory, etc.) via their HTTP API. It supports two resources: Package (get metadata at a specific version, get all versions, search packages) and Distribution Tag (get all dist-tags, update a dist-tag). Authentication is optional — only required for write operations (dist-tag update) or private registry access. The credential provides an access token and a configurable registry URL (defaults to https://registry.npmjs.org).

**Category:** Development  
**Tool Name:** `npm`  
**Version:** 1

**Appearance:** Icon: `si-npm` | Color: `#CB3837`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Npm API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/npm-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Package | `package` |
| Distribution Tag | `distTag` |

### Operations

**Package**

| Operation | Value | Description |
|-----------|-------|-------------|
| Get Metadata | `getMetadata` | Returns all the metadata for a package at a specific version |
| Get Versions | `getVersions` | Returns all the versions for a package |
| Search | `search` | Search for packages |

**Distribution Tag**

| Operation | Value | Description |
|-----------|-------|-------------|
| Get All | `getMany` | Returns all the dist-tags for a package |
| Update | `update` | Update a dist-tag for a package |

### Parameters

#### Package: Get Metadata

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Package Name | `string` | Yes | — | The name of the npm package. Supports scoped packages (e.g., @scope/package). Supports expressions like {{ $json.packageName }}. |
| Package Version | `string` | Yes | `latest` | The version of the package to retrieve metadata for. Can be a semver version (e.g., 1.2.3) or a dist-tag (e.g., latest, next). Supports expressions. |

#### Package: Get Versions

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Package Name | `string` | Yes | — | The name of the npm package. Supports scoped packages (e.g., @scope/package). Supports expressions like {{ $json.packageName }}. |

#### Package: Search

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Query | `string` | Yes | — | The query text used to search for packages. Supports expressions. |
| Limit | `number` | No | `10` | Max number of results to return. Supports expressions. |
| Offset | `number` | No | `0` | Offset to return results from (for pagination). Supports expressions. |

#### Distribution Tag: Get All

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Package Name | `string` | Yes | — | The name of the npm package. Supports scoped packages (e.g., @scope/package). Supports expressions like {{ $json.packageName }}. |

#### Distribution Tag: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Package Name | `string` | Yes | — | The name of the npm package. Supports scoped packages (e.g., @scope/package). Supports expressions like {{ $json.packageName }}. |
| Package Version | `string` | Yes | — | The version string to point the distribution tag to (e.g., 1.2.3). Supports expressions. |
| Distribution Tag Name | `string` | Yes | `latest` | The name of the distribution tag to update (e.g., latest, next, beta). Supports expressions. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

The registry response is **merged onto the input item JSON** — the fields already on the item pass through and the result is written on top of them. Binary data is forwarded unchanged.

| Operation | Output items per input item |
|-----------|-----------------------------|
| `package` / `getMetadata` | One item carrying the full registry metadata document for that version |
| `package` / `getVersions` | **Fans out** — one item per published version, each `{ version, published_at }`, newest first |
| `package` / `search` | **Fans out** — one item per match, each `{ name, version, description }` |
| `distTag` / `getMany` | One item whose properties are the dist-tag names mapped to versions |
| `distTag` / `update` | One item carrying the registry's response to the tag update |

`getVersions` and `search` return a trimmed shape rather than the raw registry payload: version listings are filtered to valid semver entries and sorted by publish date, and search results are reduced to name, version and description. If an operation produces no results at all, the input item still passes through as a single output item with nothing added.

Reference the result downstream by expression, e.g. `{{ $json.version }}`.

## Usage Examples

- Get metadata for an npm package at a specific version
- List all published versions of an npm package
- Search the npm registry for packages matching a query
- Get all distribution tags for an npm package
- Update a distribution tag to point to a new version

## Example Configuration

Fetch the metadata document for a package at a given version:

```json
{
  "type": "npm",
  "parameters": {
    "resource": "package",
    "operation": "getMetadata",
    "packageName": "{{ $json.packageName }}",
    "packageVersion": "latest"
  }
}
```

List every published version of a scoped package:

```json
{
  "type": "npm",
  "parameters": {
    "resource": "package",
    "operation": "getVersions",
    "packageName": "@typescript-eslint/parser"
  }
}
```

Search the registry with pagination:

```json
{
  "type": "npm",
  "parameters": {
    "resource": "package",
    "operation": "search",
    "query": "workflow automation",
    "limit": 50,
    "offset": 0
  }
}
```

Read the current dist-tags for a package:

```json
{
  "type": "npm",
  "parameters": {
    "resource": "distTag",
    "operation": "getMany",
    "packageName": "express"
  }
}
```

Point a dist-tag at a newly published version:

```json
{
  "type": "npm",
  "parameters": {
    "resource": "distTag",
    "operation": "update",
    "packageName": "{{ $json.packageName }}",
    "distTagName": "beta",
    "packageVersion": "{{ $json.newVersion }}"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Query npm registries to search packages, get metadata/versions, and manage distribution tags.