updating-npm-package

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Updating an npm Package

更新npm包

Use this skill when the user asks to update, upgrade, or bump a specific npm dependency.

当用户要求更新、升级某个特定的npm依赖包时，可使用本技能。

Steps

步骤

Check the current version — read
```
package.json
```
to find the installed version:
bash
```
npm ls <package-name>
```
Find the latest version on npm — fetch the package info:
bash
```
npm view <package-name> versions --json
npm view <package-name> dist-tags --json
```
This gives you the
```
latest
```
tag and all published versions.
Determine the update type — compare current version to latest:
- Patch (1.2.3 → 1.2.4): bug fixes only
- Minor (1.2.3 → 1.3.0): new features, backwards compatible
- Major (1.2.3 → 2.0.0): breaking changes
For patch or minor updates — just do it:
bash
```
npm install <package-name>@latest
```
Run the build and tests to make sure nothing broke:
bash
```
npm run build && npm test
```
If everything passes, commit and report what changed.

For major updates — do a thorough investigation first:

a. Fetch the changelog and release notes — check the package's GitHub repo for

CHANGELOG.md

MIGRATION.md

, or release notes. Use the web to find the official upgrade guide:

Search: "<package-name> v<major> migration guide" OR "<package-name> v<major> upgrade guide"

b. Read the breaking changes — identify every breaking change between the current and target version. Common things to check:

Removed or renamed APIs
Changed function signatures or return types
Dropped Node.js version support
New peer dependency requirements
Changed default behavior
Config file format changes

c. Scan the codebase for impact — search for every usage of the package:

bash

# Find all imports
grep -r "from ['\"]<package-name>" src/
grep -r "require(['\"]<package-name>" src/

For each usage, check if it's affected by a breaking change.

d. Apply the update:

bash

npm install <package-name>@latest

e. Fix breaking changes — update each affected usage based on the migration guide. Apply changes file by file.

f. Verify — run the full suite:

bash

npm run lint && npx tsc --noEmit && npm test && npm run build

g. Produce a migration report — summarize:

markdown

## Package Update: <package-name> v<old> → v<new> (Major)

### Breaking Changes Applied
- `oldFunction()` renamed to `newFunction()` — updated in 3 files
- Config format changed from `.js` to `.config.ts` — migrated
- Dropped support for Node 16 — verified we're on Node 20

### Files Modified
- src/lib/client.ts — updated import and function call
- src/config/settings.ts — migrated config format
- package.json — bumped version

### Validation
- ✅ Lint passes
- ✅ TypeScript compiles
- ✅ All 47 tests pass
- ✅ Build succeeds

检查当前版本 — 读取
```
package.json
```
来查看已安装的版本：
bash
```
npm ls <package-name>
```
查找npm上的最新版本 — 获取包信息：
bash
```
npm view <package-name> versions --json
npm view <package-name> dist-tags --json
```
这会返回
```
latest
```
标签以及所有已发布的版本。
确定更新类型 — 对比当前版本与最新版本：
- 补丁更新（1.2.3 → 1.2.4）：仅修复Bug
- 小版本更新（1.2.3 → 1.3.0）：新增功能，向后兼容
- 大版本更新（1.2.3 → 2.0.0）：包含破坏性变更
补丁或小版本更新 — 直接执行：
bash
```
npm install <package-name>@latest
```
执行构建和测试，确保没有问题：
bash
```
npm run build && npm test
```
如果所有检查都通过，提交更新并报告变更内容。

大版本更新 — 先进行全面调研：

a. 获取变更日志和发布说明 — 查看包的GitHub仓库中的

CHANGELOG.md

、

MIGRATION.md

或发布说明，通过网络搜索官方升级指南：

搜索："<package-name> v<major> migration guide" OR "<package-name> v<major> upgrade guide"

b. 阅读破坏性变更 — 找出当前版本与目标版本之间的所有破坏性变更，需要检查的常见内容包括：

移除或重命名的API
更改的函数签名或返回类型
不再支持的Node.js版本
新增的peer依赖要求
更改的默认行为
配置文件格式变更

c. 扫描代码库评估影响范围 — 搜索包的所有使用场景：

bash

# 查找所有导入语句
grep -r "from ['\"]<package-name>" src/
grep -r "require(['\"]<package-name>" src/

针对每一处使用，检查是否受到破坏性变更的影响。

d. 执行更新：

bash

npm install <package-name>@latest

e. 修复破坏性变更 — 根据迁移指南更新每一处受影响的代码，逐个文件进行修改。

f. 验证 — 运行完整的检查套件：

bash

npm run lint && npx tsc --noEmit && npm test && npm run build

g. 生成迁移报告 — 总结内容：

markdown

## 包更新：<package-name> v<旧版本> → v<新版本>（大版本）

### 已处理的破坏性变更
- `oldFunction()`重命名为`newFunction()` — 已在3个文件中更新
- 配置格式从`.js`改为`.config.ts` — 已完成迁移
- 不再支持Node 16 — 确认当前使用Node 20

### 修改的文件
- src/lib/client.ts — 更新导入语句和函数调用
- src/config/settings.ts — 迁移配置格式
- package.json — 升级版本号

### 验证结果
- ✅ 代码检查通过
- ✅ TypeScript编译通过
- ✅ 全部47项测试通过
- ✅ 构建成功

Notes

注意事项

Always check peer dependency compatibility before updating —
```
npm install
```
will warn about mismatches.
For monorepos, check if the package is used in multiple workspaces and update them all together.
If the package has a codemod tool (e.g.
```
npx @next/codemod
```
), use it instead of manual migration.
Lock file (
```
package-lock.json
```
) changes are expected — commit them with the update.

更新前务必检查peer依赖的兼容性 —
```
npm install
```
会对不匹配情况发出警告。
对于 monorepo，需检查包是否在多个工作区中使用，并统一更新所有实例。
如果包提供了codemod工具（如
```
npx @next/codemod
```
），优先使用工具而非手动迁移。
锁文件（
```
package-lock.json
```
）的变更是正常现象 — 与更新内容一同提交。