NPM pin dependencies

npm-pin-dependencies pins your package.json dependency ranges to the exact versions resolved by the lockfile.

This package ships a native Rust core via NAPI-RS as part of the riri-node-tools monorepo.

Table of Contents

• Prerequisites
• Installation
• Usage
  • CLI
  • Node API
• Options
• Debug

Prerequisites

• Node.js version ^22.22.2 || ^24.15.0 || >=26.0.0

Supported platforms:

| OS | Arch | | ------- | ------------------------------------ | | Linux | x64 (glibc/musl), arm64 (glibc/musl) | | macOS | x64, arm64 | | Windows | x64 |

Installation

Install globally:

npm install -g @smarlhens/npm-pin-dependencies

Or run with npx:

npx @smarlhens/npm-pin-dependencies

Usage

CLI

Show which package.json dependency ranges would be pinned to lockfile-resolved versions:

npd

Sample output (against fixtures/npd-npm-v3-unpinned-deps):

    bar  ~18.2.0   →  18.2.0
    foo  ^4.17.21  →  4.17.21
    baz  ^1.0.0    →  1.6.0

  Run npd -u to upgrade package.json.

Apply the pins to package.json:

npd -u

Emit machine-readable JSON:

npd --json

Supports package-lock.json, yarn.lock, and pnpm-lock.yaml (auto-detected).

Node API

import { pinDependencies } from '@smarlhens/npm-pin-dependencies';

const packageJson = '...'; // stringified package.json
const lockfileContent = '...'; // stringified lockfile

const { pins } = pinDependencies({
  packageJson,
  lockfileContent,
  lockfileType: 'npm', // optional: 'npm' | 'yarn' | 'pnpm' — auto-detected when omitted
});

for (const { name, kind, from, to } of pins) {
  console.log(`${kind} ${name}: "${from}" → "${to}"`);
}

runCli(argv) is also exported to run the npd CLI in-process; argv[0] must be the program name. Returns exit code.

Options

Pin range-based dependency specifiers to the exact versions resolved by the lockfile

Usage: npd [OPTIONS]

Options:
  -q, --quiet              Silent mode — no output
  -v, --verbose            Verbose output
  -d, --debug              Debug mode — detailed logging
  -u, --update             Update package.json with pinned versions
      --json               Output results as JSON
      --sort               Sort package.json keys (sort-package-json conventions); writes the file even without --update or pending pins
      --enable-save-exact  Create or update .npmrc with save-exact=true
      --pin-catalog        Resolve and report pnpm catalog entries from `pnpm-workspace.yaml`. On `-u`, rewrites the catalog entries in place. Requires a pnpm project
  -h, --help               Print help
  -V, --version            Print version

Workspace mode

When run from the root of an npm, pnpm, or yarn workspace, npd auto-detects the workspace and pins each member's package.json against the shared root lockfile. Output is grouped per member. --pin-catalog continues to operate on the root pnpm-workspace.yaml.

Debug

npd -d

The -d/--debug flag enables detailed logging to stderr. No environment variable is required.

  ▸ Detecting lockfile......
  ✓ Detected package-lock.json
  ▸ Reading package.json......
  ✓ Read package.json
  ▸ Parsing lockfile......
  ✓ Parsed lockfile
  ▸ Computing dependency pins......
    Pin ~18.2.0 → 18.2.0 bucket="dependencies" package=bar
    Pin ^4.17.21 → 4.17.21 bucket="dependencies" package=foo
    Pin ^1.0.0 → 1.6.0 bucket="devDependencies" package=baz
  ✓ Computed dependency pins
    bar  ~18.2.0   →  18.2.0
    foo  ^4.17.21  →  4.17.21
    baz  ^1.0.0    →  1.6.0

  Run npd -d -u to upgrade package.json.