Introduction to Pastoralist

Pastoralist is the audit trail for package manager overrides.

If your project uses overrides, pnpm.overrides, or resolutions, Pastoralist records why each entry exists, which packages still need it, and when it can be removed. It can also connect security fixes, patch files, workspace packages, and CI checks to the same record.

Why This Matters

Overrides usually start with a good reason:

{
  "overrides": {
    "lodash": "4.17.21"
  }
}

Months later, the context is gone. Was it a security fix? A transitive bug? Who still needs it? Is it safe to remove? The override should stay as the package manager instruction; the appendix carries the review detail:

{
  "overrides": {
    "lodash": "4.17.21"
  },
  "pastoralist": {
    "appendix": {
      "[email protected]": {
        "dependents": {
          "web-app": "lodash@^4.17.20",
          "admin-ui": "lodash@^4.17.19"
        },
        "ledger": {
          "addedDate": "2026-05-06T00:00:00.000Z",
          "reason": "Pin lodash to a patched version while workspace packages finish upgrades.",
          "source": "manual",
          "securityChecked": true,
          "securityProvider": "osv",
          "cves": ["CVE-2021-23337"],
          "cveDetails": [
            {
              "cve": "CVE-2021-23337",
              "severity": "high",
              "patchedVersion": "4.17.21"
            }
          ],
          "severity": "high",
          "vulnerableRange": "<4.17.21",
          "patchedVersion": "4.17.21",
          "keep": {
            "reason": "Keep until each workspace requests lodash 4.17.21 or newer.",
            "untilVersion": "4.17.21"
          }
        }
      }
    }
  }
}

The override controls the installed version. The appendix explains why that control exists, who still depends on it, what scanner or reviewer justified it, and what condition makes it removable.

What Pastoralist Handles

• Tracks npm and Bun overrides, pnpm pnpm.overrides, and Yarn resolutions
• Shows which direct or workspace packages still depend on each override
• Removes stale overrides with --remove-unused
• Links patch-package files to the overrides they support
• Checks security advisories with OSV, GitHub Dependabot alerts, npm audit, Snyk, Socket, or Spektion
• Supports monorepos through workspaces, depPaths, overridePaths, and resolutionPaths
• Provides CI-friendly output with --dry-run, --quiet, --summary, and --outputFormat json

At A Glance

When To Use It

Use Pastoralist when your project has overrides that need a durable reason, a regular cleanup path, or a security audit trail.

It is designed to sit beside tools such as npm audit, Dependabot, Renovate, patch-package, syncpack, and depcheck. Those tools find or apply dependency changes. Pastoralist keeps the resulting overrides from becoming invisible technical debt.

Start Here

npm install pastoralist --save-dev
npx pastoralist init

Then add it to postinstall:

{
  "scripts": {
    "postinstall": "pastoralist"
  }
}

Continue with the setup guide, or try a sandbox: