Fork 说明（@whyjs/taze）

本仓库为 antfu-collective/taze 的个人 fork，npm 包名为 @whyjs/taze，版本格式为 {upstream}-fix.{N}（fix.N 在发布时递增）。

发布包

| npm 包 | CLI 命令 | 说明 | |---|---|---| | @whyjs/taze | taze | 主包，完整功能 | | uploom | uploom | 短包名 wrapper，npx uploom 等价于完整 CLI |

npm i -g @whyjs/taze   # → taze
npm i -g uploom        # → uploom（更短的 npx 入口）

相较上游新增功能

• 可配置请求超时与重试：--request-timeout <ms>（默认 5000）以及 --retry / --retry-*
• npm 镜像管理（兼容 nrm 使用习惯）：
  • 切换镜像通过 npm config set，不直接改写 ~/.npmrc 中的 token
  • 自定义镜像列表保存在 ~/.taze/registries.yaml（YAML 格式）
  • 首次运行可自动从 ~/.nrmrc 迁移
• 双包发布：CI 使用 pnpm -r publish 同时发布 @whyjs/taze 与 uploom
• 清理垃圾目录（移植自 npkill 0.12.2）：taze clean，全屏 TUI，见下文

镜像管理命令

registry 可缩写为 reg（taze reg = taze registry，uploom reg 同理）。

taze reg ls                   # 列出镜像
taze reg current              # 当前镜像
taze reg use taobao           # 切换镜像
taze reg add <name> <url> [home]
taze reg del <name>
taze reg test [name]          # 测速

# 短包名同样可用（reg 缩写同样有效）
npx uploom reg use taobao
npx uploom minor -w

清理命令（taze clean）

移植自 npkill：扫描目录，找出 node_modules、构建产物、缓存等目录，计算大小和项目最近修改时间，在全屏 TUI 中删除。

taze clean                    # 扫描当前目录（默认 node profile）
taze clean ~/projects         # 扫描指定目录（也可用 -d）
taze clean -f                 # 从 HOME 开始扫描
taze clean -p                 # 列出所有 profile
taze clean -p node,python     # 组合 profile
taze clean -t node_modules    # 自定义目标目录名（覆盖 profile）
taze clean -E vendor,tmp      # 排除路径
taze clean -x                 # 排除敏感目录（应用内部、HOME 下隐藏目录等）
taze clean --older-than 90    # 只显示 90 天未改动的项目
taze clean -s size            # 排序：none | size | path | age
taze clean -D                 # 找到即删（会先警告，-y 跳过）
taze clean --dry-run          # 只模拟删除
taze clean --json             # 输出 JSON（--json-stream 逐行输出）
taze clean --no-size --no-age # 跳过大小 / 年龄计算（--no-stats 两者都跳过）

TUI 按键：↑↓/jk 移动，PgUp/PgDn 翻页，Home/End 首尾，空格/Del 删除，t 多选模式（空格 勾选、v 区间、a 全选、回车 删除所选），/ 正则搜索，s 切换排序，o 打开所在目录，←→ 切换 帮助 / 选项 / 结果 / 详情 面板，e 错误列表，q 退出。敏感目录需按两次空格确认。

配置文件兼容 npkill 的 .npkillrc（JSON，优先级：--config > ./.npkillrc > ~/.npkillrc），支持 rootDir、exclude、sortBy、sizeUnit、excludeSensitiveResults、dryRun、defaultProfiles 和自定义 profiles。

非终端环境（管道、CI）下输出纯文本列表；--delete-all 需配合 -y。Unix 上大小用 du -sk 计算，删除用 rm -rf；Windows 上使用 Node 原生实现。

Features

• Built-in support for monorepos
• No installation required — npx taze
• Safe by default — updates in the version range you are allowed
• Interactive mode to select which packages to update
• Respects package.json's engines field and your package manager's config
• Updates GitHub Actions in your workflows, with optional SHA pinning
• Updates the Node.js version pinned in .node-version and .nvmrc
• Agents compatible JSON output

Usage

By default, taze will only bump versions in the ranges you specified in package.json (which is safe and the default behavior of npm install)

To ignore the ranges, explicitly set the maximum allowed version change.

For example taze major will check all changes and bump to the latest stable changes including majors (breaking changes), or taze minor that bump to latest minor changes within the same major version.

Monorepo

taze has the built-in first-class monorepo support. Simply adding -r will scan the subdirectories that contain package.json and update them together. It will handle local private packages automatically.

To diagnose missing packages in a complex workspace, enable the workspace-only debug output. It reports discovered and excluded manifests, the final workspace list, and each workspace's dependency names, current versions, fields, and registry types. Registry requests and version-selection decisions are not included.

uploom -r --debug
# Equivalent namespace-only form:
DEBUG=taze:workspace uploom -r

Debug lines are written to stderr, so they can be captured separately:

uploom -r --debug 2> uploom-workspaces.log

--loglevel debug enables the same workspace-only diagnostics. If a nested workspace is intentionally being pruned because it has its own .git, pnpm-workspace.yaml, .yarnrc.yml, or Bun lockfile, the output includes that reason. Use --no-ignore-other-workspaces to include those nested workspaces.

Configuration

See taze --help for more details

Filters

You can filter out packages you want to check for upgrades by --include or --exclude; they accept string and regex, separated by commas (,).

taze --include lodash,webpack
taze --include /react/ --exclude react-dom # regex is also supported

--exclude (and --include) also accepts a name@range selector to exclude only a specific version range of a package, instead of the whole package. This is useful to block a specific major version while still allowing other updates (including in interactive mode):

# skip typescript's major v7 (and later), but still offer v6 minor/patch updates
taze --exclude typescript@7
taze --exclude "typescript@^7||^8" # multiple ranges can be combined with ||

Dependencies listed in pnpm's update.ignoreDeps in pnpm-workspace.yaml are automatically excluded, so packages you tell pnpm never to update are also skipped by taze.

Locked Versions

Locked (fixed version without ^ or ~) packages are skipped by default, use taze --include-locked or taze -l to show them.

Peer Dependencies

Bumping version in peerDependencies is not enabled by default. Pass --peer option to include them in the update process.

taze --peer

Maturity Period

By default the most recent version of a dependency is used. You may choose to filter to versions that have been out longer by passing --maturity-period.

taze --maturity-period

The filter when using the maturity-period flag is 7 days. You may also want to pass a day value to have a longer or shorter number of days.

taze --maturity-period 14

You can exclude packages from the maturity filter. This is also inferred from package manager config when available, such as minimumReleaseAgeExclude in pnpm-workspace.yaml and npmPreapprovedPackages in .yarnrc.yml.

taze --maturity-period-exclude react,webpack

If you want stable releases only while still honoring the maturity period, use stable mode.

taze stable --maturity-period 14

[!NOTE] This kind of filtering is sometimes called cooldown or minimumReleaseAge by other tools.

JSON Output

Pass --json to output the resolved update info as JSON to stdout instead of the rendered table. This is handy for scripting and CI.

taze --json

When --json is used, --interactive is ignored and no progress bars, tables, or tips are printed. By default only dependencies with an available update are included; combine it with --all to include up-to-date dependencies too. It can still be combined with -w to write the changes back to package.json.

GitHub Actions

taze also checks the GitHub Actions used in your workflows. When a .github/workflows directory exists, it scans .github/workflows/*.{yml,yaml}, composite actions (.github/actions/**/action.{yml,yaml} and a repo-root action.{yml,yaml}), and reusable workflow calls, then reports newer versions alongside your npm dependencies. It works with every mode (major, minor, ...), --interactive, --json, and -w.

taze major -w      # also updates outdated actions, e.g. actions/checkout@v3 -> @v4
taze --no-github-actions   # opt out

References are updated in place while preserving the granularity you wrote (@v4 → @v5, @v4.1.1 → @v4.2.0). By default the existing style of each action is kept: tag references stay tags, while SHA-pinned references stay pinned (with a refreshed # vX.Y.Z comment). Choose a style explicitly with --github-actions-style <auto|tag|sha>:

With --github-actions-style sha, tag references are pinned to a commit SHA even when no version bump is available, so a repo can be fully SHA-pinned in one pass (actions/checkout@v4 → actions/checkout@<sha> # v4). These pin-only changes are reported with a pin diff.

# style: sha — pin to an immutable commit for supply-chain safety
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
# style: tag
- uses: actions/checkout@v5

Only v-prefixed version tags are considered; branch refs (@main), non-v tags, docker:// and local (./) actions are left untouched. Filtering (--include/--exclude/packageMode), the maturity-period cool-down, and mode all apply, matched by the action's owner/repo name.

Versions are fetched from the GitHub REST API. Set a GITHUB_TOKEN (or GH_TOKEN) to raise the rate limit from 60 to 5000 requests/hour:

GITHUB_TOKEN=xxxx taze major

If neither is set, taze falls back to a token from the GitHub CLI (gh auth token) when you're logged in, so an authenticated gh needs no extra configuration.

JSR

taze checks JSR dependencies alongside your npm ones. Both ways of declaring a JSR package are supported:

{
  "dependencies": {
    // native jsr: protocol (pnpm / deno) — versions come from jsr.io
    "@std/cli": "jsr:^1.0.0",
    // npm-compat form written by `npx/bunx jsr add` — needs `@jsr:registry=https://npm.jsr.io` in .npmrc
    "@std/encoding": "npm:@jsr/std__encoding@^1.0.0"
  }
}

jsr: specifiers are resolved against the JSR registry (yanked versions are skipped) and written back in place preserving the jsr: prefix. All modes, filtering, and -w apply as usual.

Node.js version

taze also keeps the Node.js version pinned in .node-version, .nvmrc, and a package.json devEngines.runtime entry fresh. It checks these files in the current directory, and with -r it discovers nested ones too (honoring ignorePaths); a neighboring package.json is not required for the .node-version / .nvmrc files.

taze                    # stay on the current Node.js major
taze patch              # stay on the current major and minor
taze major -w           # allow a newer major and write the file
taze --no-node-version  # opt out

In .node-version / .nvmrc only stable numeric references with an optional v prefix are recognized (22, 22.14, v22.14.0); aliases (lts/*, node), ranges, and prereleases are left untouched. The written reference keeps the shape you had — a major-only 22 stays major-only, and the v prefix, surrounding whitespace, and any comments/blank lines are preserved.

A devEngines.runtime pin whose name is node is instead treated as a semver range and rewritten in place, preserving the range operator (>=20 → >=26.7.0, ^20.0.0 → ^20.20.2); runtime may be a single object or an array (only the node entry is touched).

Releases and their dates come from the official Node.js distribution index, so maturityPeriod and version-specific exclusions apply here too. Filtering uses the dependency name node (--include node, --exclude node, packageMode.node), and --no-node-version / nodeVersion: false opts out of all of the above. Writing the files does not install or switch the active Node.js runtime.

Config file

With taze.config.js file, you can configure the same options the command has.

import { defineConfig } from '@whyjs/taze'

export default defineConfig({
  // ignore packages from bumping
  exclude: [
    'webpack'
  ],
  // fetch latest package info from registry without cache
  force: true,
  // use a custom fast-npm-meta compatible API endpoint
  fastNpmMetaApiEndpoint: 'https://npm.example.com/',
  // retry behavior when fetching package metadata fails:
  // a number for retry count, `false` to disable, or an object for fine-grained
  // control, e.g. { retries: 4, factor: 2, minTimeout: 1000, maxTimeout: 30_000, randomize: false }
  retry: 4,
  // write to package.json
  write: true,
  // run `npm install` or `yarn install` right after bumping
  install: true,
  // ignore paths for looking for package.json in monorepo
  ignorePaths: [
    '**/node_modules/**',
    '**/test/**',
  ],
  // ignore package.json that in other workspaces (with their own .git,pnpm-workspace.yaml,etc.)
  ignoreOtherWorkspaces: true,
  // override with different bumping mode for each package
  packageMode: {
    'typescript': 'major',
    'unocss': 'ignore',
    // regex starts and ends with '/'
    '/vue/': 'latest'
  },
  // exclude packages from the maturity period filter
  maturityPeriodExclude: [
    'react',
    '@myorg/*',
  ],
  // disable checking for "overrides" package.json field
  depFields: {
    overrides: false
  },
  // GitHub Actions updates: `true` (default) | `false` to opt out | options object
  githubActions: {
    // 'auto' (preserve existing style) | 'tag' | 'sha'
    style: 'auto'
  },
  // `.node-version` / `.nvmrc` updates are enabled by default; `false` to opt out
  nodeVersion: true
})

Custom Manifests

taze discovers, reads and writes each kind of dependency file through a Manifest (package.json, package.yaml, pnpm/bun/yarn catalogs, GitHub workflows). You can register your own to support extra file types, via the manifests option in your config or programmatically. Custom manifests are merged ahead of the built-ins, so they can also override how an existing file type is handled.

import type { Manifest } from '@whyjs/taze'
import { defineConfig } from '@whyjs/taze'

const myManifest: Manifest = {
  name: 'my-manifest',
  type: 'my-manifest',
  // glob/find the files this manifest owns
  discover: async () => ['my-deps.json'],
  // claim a discovered file (receives the absolute path)
  match: filepath => filepath.endsWith('my-deps.json'),
  // parse it into one or more packages of dependencies
  async load(relative, options, shouldUpdate) {
    return [/* PackageMeta[] */]
  },
  // write the resolved updates back
  async write(pkg, options) {},
}

export default defineConfig({
  manifests: [myManifest],
})

Only available from a JS/TS config file or programmatically, not from .tazerc.json.

Alternatives

taze is inspired by the following tools.

• npm-check-updates
• npm-check

They work well but have different focuses and feature sets, try them out as well :)

Thanks

Great thanks to @sinoon who helped a lot with idea brainstorming and feedback discussion.

The GitHub Actions updating feature is inspired by and credits actions-up by Azat S., which pioneered the interactive SHA-pinning workflow this builds upon.

License

MIT License © 2020 Anthony Fu