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 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:

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

List every published version of a scoped package:

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

Search the registry with pagination:

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

Read the current dist-tags for a package:

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

Point a dist-tag at a newly published version:

{
  "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.