update-npm-deps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update NPM Dependencies

升级NPM依赖项

Upgrade npm dependencies intelligently, researching breaking changes for major version updates.

Optional filter:

$ARGUMENTS

(e.g.,

react

react axios lodash

)

智能升级npm依赖项，针对大版本更新开展破坏性变更研究。

可选过滤器：

$ARGUMENTS

（例如：

react

、

react axios lodash

）

Phase 1: Monorepo Detection

阶段1：单仓库（Monorepo）检测

Search for

package.json

files in the project (excluding

node_modules

bash

find . -name "package.json" -not -path "*/node_modules/*" -not -path "*/.git/*"

If one found: proceed with that location
If multiple found: use AskUserQuestion to let user choose which to update (multiSelect allowed)
If none found: inform user and exit

在项目中搜索

package.json

文件（排除

node_modules

目录）：

bash

find . -name "package.json" -not -path "*/node_modules/*" -not -path "*/.git/*"

如果找到1个：使用该位置继续操作
如果找到多个：使用AskUserQuestion让用户选择要更新的仓库（允许多选）
如果未找到：告知用户并退出流程

Phase 2: Discovery

阶段2：发现更新

For each selected package.json location:

Change to the directory containing package.json
Run npm-check-updates to discover available updates:

bash

ncu --format group

If a filter was provided via

$ARGUMENTS

bash

ncu --format group --filter "$ARGUMENTS"

Parse the output to categorize updates:
- Major (breaking changes) - requires migration research
- Minor (new features, backward compatible)
- Patch (bug fixes)
Create TodoWrite tasks for each major update package

If no updates are available, inform the user and exit.

对于每个选中的package.json所在位置：

切换到包含package.json的目录
运行npm-check-updates工具发现可用更新：

bash

ncu --format group

如果通过

$ARGUMENTS

提供了过滤器：

bash

ncu --format group --filter "$ARGUMENTS"

解析输出结果，对更新进行分类：
- 大版本（Major）（含破坏性变更）- 需要迁移研究
- 小版本（Minor）（新增功能，向后兼容）
- 补丁版本（Patch）（bug修复）
为每个大版本更新的包创建TodoWrite任务

如果没有可用更新，告知用户并退出流程。

Phase 3: User Strategy Selection

阶段3：用户选择升级策略

Present a summary showing:

Count and list of major updates (with current → target versions)
Count of minor updates
Count of patch updates

Use AskUserQuestion to ask upgrade strategy:

Header: "Strategy" Options:

Cautious - Upgrade minor/patch first, then major one-by-one with research
All at once - Research all major changes, then upgrade everything together
Skip major - Only upgrade minor and patch versions
Interactive - Ask for each major update individually

展示更新摘要：

大版本更新的数量和列表（包含当前版本 → 目标版本）
小版本更新的数量
补丁版本更新的数量

使用AskUserQuestion询问升级策略：

标题：“策略选择” 选项：

谨慎模式 - 先升级小版本/补丁版本，再逐个升级大版本并开展研究
一次性升级 - 先研究所有大版本变更，再一次性升级所有依赖
跳过大版本 - 仅升级小版本和补丁版本
交互式 - 针对每个大版本更新单独询问用户

Phase 4: Research Breaking Changes

阶段4：研究破坏性变更

For each package with a major version update:

针对每个大版本更新的包：

Step 1: Calculate Version Gap

步骤1：计算版本差距

Identify all major versions between current and target. For example:

```
react: 17.0.2 → 19.0.0
```
→ research v18 AND v19 breaking changes
```
jest: 27.5.1 → 29.7.0
```
→ research v28 AND v29 breaking changes

确定当前版本和目标版本之间的所有大版本。例如：

```
react: 17.0.2 → 19.0.0
```
→ 需要研究v18和v19的破坏性变更
```
jest: 27.5.1 → 29.7.0
```
→ 需要研究v28和v29的破坏性变更

Step 2: Research Each Major Version

步骤2：研究每个大版本

For each major version in the gap, search for migration documentation:

WebSearch: "[package-name] v[X] migration guide"
WebSearch: "[package-name] v[X] breaking changes"

Common sources:

GitHub releases:

https://github.com/[org]/[repo]/releases

Official docs migration guides
Changelog files

针对版本差距中的每个大版本，搜索迁移文档：

WebSearch: "[package-name] v[X] migration guide"
WebSearch: "[package-name] v[X] breaking changes"

常见信息来源：

GitHub发布页：

https://github.com/[org]/[repo]/releases

官方文档中的迁移指南
变更日志文件

Step 3: Extract Key Breaking Changes

步骤3：提取关键破坏性变更

From the migration docs, identify:

API changes (renamed/removed functions)
Configuration changes
Peer dependency requirements
Behavioral changes
Deprecated features now removed

从迁移文档中识别：

API变更（重命名/移除的函数）
配置变更
对等依赖要求
行为变更
已移除的废弃特性

Step 4: Search Codebase for Affected Code

步骤4：搜索代码库中受影响的代码

Use Grep to find usage of deprecated or changed APIs:

Grep: "[deprecated-function-name]"
Grep: "[changed-import-pattern]"

Document which files are affected and what changes are needed.

使用Grep查找已废弃或变更的API的使用情况：

Grep: "[deprecated-function-name]"
Grep: "[changed-import-pattern]"

记录受影响的文件以及需要进行的变更。

Phase 5: User Confirmation

阶段5：用户确认

For each major update, present:

Package name and version transition
Breaking changes found (summarized)
Files potentially affected (count and list)

Use AskUserQuestion to confirm:

Header: "Confirm" Options:

Proceed - Continue with upgrades and migrations
Show details - Display detailed breaking changes for review
Skip package - Exclude a specific package from upgrade
Abort - Cancel the upgrade process

If "Show details" selected, display full migration research, then ask again.

针对每个大版本更新，展示：

包名称和版本过渡信息
已发现的破坏性变更（摘要）
可能受影响的文件（数量和列表）

使用AskUserQuestion确认：

标题：“确认操作” 选项：

继续 - 继续执行升级和迁移
查看详情 - 展示完整的破坏性变更研究内容供审核
跳过该包 - 将特定包排除在升级范围外
终止 - 取消整个升级流程

如果选择“查看详情”，展示完整的迁移研究内容，然后再次询问确认。

Phase 6: Execute Upgrades

阶段6：执行升级

For Cautious Strategy

谨慎模式策略

First, upgrade minor and patch only:

bash

ncu -u --target minor
npm install

Run tests to verify:

bash

npm test

If tests fail, stop and inform user before proceeding with major upgrades.

首先，仅升级小版本和补丁版本：

bash

ncu -u --target minor
npm install

运行测试验证：

bash

npm test

如果测试失败，在继续大版本升级前停止并告知用户。

Upgrade Major Versions

升级大版本

For each major version upgrade (or all at once based on strategy):

Single package:

bash

ncu -u --filter [package-name]
npm install

All packages:

bash

ncu -u
npm install

针对每个大版本升级（或根据策略一次性升级所有）：

单个包升级：

bash

ncu -u --filter [package-name]
npm install

所有包升级：

bash

ncu -u
npm install

Phase 7: Apply Migrations

阶段7：应用迁移

For each major update with identified code changes:

针对每个已识别代码变更的大版本更新：

Step 1: Run Codemods (if Available)

步骤1：运行代码转换工具（如果可用）

Some packages provide automated migration tools:

React:
```
npx react-codemod [transform-name]
```
Jest:
```
npx jest-codemods
```
Next.js:
```
npx @next/codemod [transform-name]
```

部分包提供自动化迁移工具：

React:
```
npx react-codemod [transform-name]
```
Jest:
```
npx jest-codemods
```
Next.js:
```
npx @next/codemod [transform-name]
```

Step 2: Manual Code Changes

步骤2：手动代码变更

For changes requiring manual intervention:

Read the affected file
Apply the necessary transformation using Edit
Show the user what changed

对于需要手动干预的变更：

读取受影响的文件
使用Edit功能应用必要的转换
向用户展示变更内容

Step 3: Update Configuration Files

步骤3：更新配置文件

If configuration format changed:

Read current config
Transform to new format
Write updated config

如果配置格式发生变更：

读取当前配置
转换为新格式
写入更新后的配置

Phase 8: Verification

阶段8：验证

Run available verification commands:

bash

npm test

If build script exists:

bash

npm run build

If lint script exists:

bash

npm run lint

运行可用的验证命令：

bash

npm test

如果存在构建脚本：

bash

npm run build

如果存在代码检查脚本：

bash

npm run lint

Report Results

报告结果

Summarize:

Packages upgraded (count)
Breaking changes addressed (count)
Files modified (count)
Test results: pass/fail
Remaining manual tasks (if any)

总结内容：

已升级的包数量
已处理的破坏性变更数量
已修改的文件数量
测试结果：通过/失败
剩余的手动任务（如果有）

Recommend Next Steps

建议后续步骤

If any migrations could not be automated:

List specific changes the user needs to review
Highlight deprecated patterns that need attention
Note any runtime behavior changes to watch for

如果有无法自动化的迁移：

列出用户需要审核的具体变更
突出需要关注的废弃模式
记录需要注意的运行时行为变更

Error Handling

错误处理

ncu Not Available

ncu工具不可用

ncu

is not found, suggest:

bash

npm install -g npm-check-updates

如果未找到

ncu

，建议：

bash

npm install -g npm-check-updates

Network Errors During Research

研究过程中出现网络错误

If WebSearch/WebFetch fails:

Retry with alternative search terms
Provide manual research links
Proceed with caution, warning user that migration research may be incomplete

如果WebSearch/WebFetch失败：

使用替代搜索词重试
提供手动研究链接
谨慎继续，警告用户迁移研究可能不完整

Test Failures After Upgrade

升级后测试失败

Stop the upgrade process

Suggest rollback:

git checkout package.json package-lock.json && npm install

Identify which package likely caused the failure

停止升级流程

建议回滚：

git checkout package.json package-lock.json && npm install

识别可能导致失败的包

Migration Research Incomplete

迁移研究不完整

If official migration docs are not found:

Check npm package page for links
Search GitHub issues for migration discussions
Note as "migration research incomplete - proceed with caution"

如果未找到官方迁移文档：

检查npm包页面的链接
搜索GitHub问题中的迁移讨论
标记为“迁移研究不完整 - 请谨慎继续”