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.2. 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 [email protected]

# pnpm
pnpm dlx [email protected]

# npm
npm exec --yes [email protected] -- depfresh

# Yarn
yarn dlx [email protected]

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 [email protected]
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 package files while preserving their formatting. It does not run an install or lifecycle scripts. Use the reviewed plan/apply workflow when lockfile, install, or verification phases are required.

For eligible local CLI table runs, Visual+ defaults to the five-region hybrid review: context, overview, risk focus, a complete update ledger, and a receipt. The ledger shows every selected update exactly once without internal IDs. --long remains the exhaustive audit of operations, owners, shared dependencies, occurrences, physical targets, lifecycle, and exact receipts. A successful compact result has no durable lifecycle rail; a capable terminal clears its one live line before writing the final review. Every non-success target and recovery path remains visible.

The former bounded-preview projection is the historical compact semantic contract completed by Plan 037. Plan 038 owns the completed and locally proven visual-composition successor. The 2.1.1 local candidate is preserved as historical evidence.

Eligibility requires the CLI progress route, non-silent output, non-interactive and non-global operation, and no direct or addon beforePackageWrite hook. --write --interactive keeps the interactive selection surface. After discovery, Visual+ prints observed repository, workspace, and package-manager evidence. Wide, medium, and narrow layouts preserve the same five regions; plain, pipes, CI, and TERM=dumb use deterministic styling without cursor control. NO_COLOR changes styling only. --group, --sort, --timediff, and --nodecompat remain meaningful in the ledger. For example, a fully observed write ends with:

Complete · 76 updates applied across 14 files
All 14 files observed at the requested values · recovery not needed · 2.4s
Exit 0

A clean command-level preflight block ends with Safety block · no files were changed, one safe Next: action, and Exit 2. After replacement starts, a failure renders Recovered, Recovery incomplete, or Recovery unknown first and names applied, restored, and unrecovered paths. Each file replacement is atomic, but the repository is not one atomic transaction and recovery is best effort. See the table output journey reference for capable/plain examples and count definitions. Interactive selection, JSON output, and global writes use their existing separate surfaces. Library check() calls and veto-capable hook routes retain the compatibility table surface.

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