Introduction to Pastoralist
Pastoralist keeps dependency overrides explainable, current, and removable
Pastoralist tracks your dependency overrides: why they're there, which packages need them, and when you can remove them.
It works with npm and Bun overrides, pnpm pnpm.overrides or
pnpm-workspace.yaml (pnpm 11+), and Yarn resolutions.
Override Tracking
Running Pastoralist adds an appendix entry to an existing override:
npx pastoralistTrack the existing qs override. Scroll to see the generated record.
This output was generated from a fixture with an express → qs dependency.
Your dependents and dates reflect your project. Add a ledger reason when
you want to record a decision that the dependency tree cannot explain.
What Pastoralist Handles
- Shows which direct or workspace packages still depend on each override
- Removes stale overrides with
--remove-unused - Links
patch-packagefiles 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, andresolutionPaths - Provides CI-friendly output with
--dry-run,--quiet,--summary, and--outputFormat json
Requirements
Use Node.js 20.19 or newer. Security scanning is optional; OSV is the default provider when scanning is enabled and requires no token.
Start Here
npm install pastoralist --save-dev
npx pastoralist initThen add it to postinstall:
package.json
{
"scripts": {
"postinstall": "pastoralist"
}
}Continue with the setup guide, or try a sandbox:
{
"name": "shepherd-cli",
"dependencies": {
"express": "4.18.2"
},
"overrides": {
"qs": "6.11.2"
},
"pastoralist": {
"appendix": {
"[email protected]": {
"dependents": {
"shepherd-cli": "qs (required by express)"
},
"ledger": {
"addedDate": "2026-10-16"
}
}
}
}
}