depfresh

Fast dependency updates for JavaScript projects, with safe writes, monorepo catalogs, and a reviewable plan/apply workflow when you need stronger guarantees.

Try it

These commands pin depfresh 2.1.4. Source text alone does not establish publication; npm and GitHub external records are authoritative. The tag workflow creates the hosted release only after the aggregate suite, exact npm 12 artifact verification, and exact public-integrity gates succeed. Recursive workspace discovery is on by default, so -r is not needed.

# Bun
bunx depfresh@2.1.4

# pnpm
pnpm dlx depfresh@2.1.4

# npm
npm exec --yes --package=depfresh@2.1.4 -- depfresh

# Yarn
yarn dlx depfresh@2.1.4

Node.js 24.15.0 or newer is required.

For a team or CI, pin depfresh in the project instead:

pnpm add -D --save-exact depfresh@2.1.4
pnpm exec depfresh

Everyday commands

depfresh                 # show available updates
depfresh minor           # allow minor and patch updates
depfresh major           # include major updates
depfresh -w              # write selected targets safely
depfresh --write --interactive # choose updates interactively
depfresh --long          # show the complete Visual+ audit
depfresh --output json   # structured compatibility output
depfresh --no-recursive  # inspect only the root package

depfresh -w updates selected dependency entries in your current working files. Existing local edits, including staged changes, do not require a commit or stash. Formatting, unrelated content, and the Git index are preserved. Merge conflicts and files changed during the operation still block replacement. The command does not run an install or lifecycle scripts. Ordinary writes use the shared file writer directly; only saved plans require the full plan contract.

When there are no updates, the default local view prints one short result. Unresolved dependencies are reported as an incomplete check.

The default output shows available updates, major-version changes, concrete compatibility warnings, and a short write result. A major version is a reason to review migration notes, not proof that your application will break. Missing compatibility information is reported as unknown; it does not prevent ordinary updates.

Ordinary checks use compact registry metadata and fetch detailed metadata only for the current and selected target versions of updates. Publication-history modes such as newest and cooldown retain their date-based behavior. Use --timediff to opt in to release ages; it fetches publication history on a best-effort basis and is off by default. Unavailable release ages do not discard resolved updates. --long retains detailed owners, occurrences, and write diagnostics.

Use --output json for structured results or -w -I to select updates interactively. See table output for display controls and troubleshooting for actionable failure explanations.

Safe plan and apply

depfresh inspect --json > depfresh-inspect.json
depfresh plan --json > depfresh-plan.json

# Review depfresh-plan.json, then grant file-write authority for that exact plan.
depfresh apply --json --write --plan-file depfresh-plan.json

• inspect reads repository evidence without registry access, commands, config execution, or writes.
• plan may read the registry and declarative JSON config, but uses memory-only cache state and never writes.
• apply rejects stale, dirty, escaped, or changed targets. Configuration can select updates but can never grant write, install, process, network, or verification authority.
• Unknown or incomplete evidence is kept as unknown; it is never converted into success.

Machine commands return 0 for a complete result without findings, 1 for a schema-valid result with findings or a non-success apply state, and 2 for a fatal contract or runtime error. Their JSON output is still valid on exit 1.

See automation and machine workflows for schemas, lockfile phases, artifact verification, and CI examples.

Exclude an exact workspace or catalog

Use repeatable exact-literal flags when one workspace or physical catalog should stay unchanged for one invocation:

depfresh -r --exclude-workspace apps/admin
depfresh -r -w \
  --exclude-workspace apps/admin \
  --exclude-workspace packages/legacy \
  --exclude-catalog payments
depfresh plan --json --exclude-catalog default

--exclude-workspace excludes declarations owned by that workspace plus its explanatory catalog consumers. It never excludes a physical catalog owner, even for the root workspace .. Use --exclude-catalog separately to exclude every proven physical catalog with that exact name and its linked consumers. Commas and punctuation are literal, so --exclude-catalog=mobile,v2 is one catalog name. Missing or unprovable targets fail before registry or write work.

Choose the narrowest control that matches your intent:

• --exclude filters dependency names.
• --ignore-paths changes repository discovery and therefore removes evidence.
• --exclude-workspace selects one proven repository-relative package path.
• --exclude-catalog selects all proven physical owners of one exact catalog name.

For persistent patterns, use declarative policy rules. For example, a native/Expo lane can still use .depfreshrc.json:

{
  "ignorePaths": ["**/.worktrees/**", "tmp/**"],
  "policyRules": [
    {
      "id": "skip-native-catalog",
      "selectors": { "catalogName": "^native$" },
      "action": "exclude"
    },
    {
      "id": "skip-native-direct",
      "selectors": {
        "workspacePath": "^apps/native$",
        "catalogRole": "direct"
      },
      "action": "exclude"
    }
  ]
}

The first rule freezes the physical native catalog and all of its consumers. The second freezes dependencies declared directly in apps/native. Dependencies in the default catalog stay eligible, even when a native app consumes them. Put native-only packages in the named native catalog or add an exact rule for their physical catalog owner.

Path ignores control repository discovery; they are not dependency policy. inspect deliberately does not load project config, so pass repository-specific discovery additions explicitly when needed:

depfresh inspect --json --ignore-paths '**/.worktrees/**,tmp/**'

CLI ignore additions retain the built-in safety exclusions for node_modules, dist, coverage, and .git.

What depfresh handles

• npm, pnpm, Yarn, and Bun workspaces; pnpm, Yarn, and Bun catalogs
• npm, JSR, GitHub, alias, workspace, override, and resolution declarations
• seven update modes: default, major, minor, patch, latest, newest, and next
• private registries and scoped .npmrc configuration for normal dependency resolution
• formatting-preserving, stale-safe manifest and catalog writes
• deterministic inspect, plan, apply, and global-operation JSON contracts
• SQLite registry cache with an automatic in-memory fallback
• runtime, peer, cohort, release, deprecation, and evidence-completeness signals
• optional exact public-npm artifact verification with npm >=11.12.0 <12.0.0 || >=12.0.0 <12.1.0

Deliberate limits are documented rather than hidden: manager execution on Linux and macOS supports npm >=10.0.0 <13.0.0, pnpm >=10.0.0 <12.0.0, and Bun >=1.2.0 <2.0.0. Yarn manager execution, Windows manager execution, and legacy bun.lockb are unsupported. File replacement is atomic per file, not across an entire repository. Exact artifact verification is limited to the public npm registry and does not inherit project npm configuration.

Documentation

• CLI reference
• Configuration and policy
• Workspace and catalog behavior
• Programmatic API
• Output contracts
• GitHub Action and integrations
• Troubleshooting
• 2.1.4 release notes
• 2.1.3 release notes
• 2.1.2 release notes
• 2.1.1 release notes
• 2.1.0 release notes
• 2.0.2 release notes
• 2.0.1 release notes
• 2.0.0 release notes

From taze

depfresh is a from-scratch successor inspired by taze and the work of its contributors. The migration guide explains the practical differences: coming from taze.

License

MIT - Vibe Code