Back to Details

dependency-upgrade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dependency Upgrade Skill

依赖项升级技能

Uses pnpm with catalog for centralized dependency management.
使用pnpm with catalog进行集中式依赖管理。

Check for Updates

检查更新

bash
pnpm outdated                      # Check all outdated
pnpm -r outdated                   # Across workspace
pnpm -F @sgcarstrends/api outdated # Specific package
pnpm dlx taze --interactive        # Interactive upgrade
bash
pnpm outdated                      # Check all outdated
pnpm -r outdated                   # Across workspace
pnpm -F @sgcarstrends/api outdated # Specific package
pnpm dlx taze --interactive        # Interactive upgrade

Upgrade Process

升级流程

1. Update Catalog

1. 更新Catalog

yaml
undefined
yaml
undefined

pnpm-workspace.yaml

pnpm-workspace.yaml

catalog: next: ^16.0.0 # Upgraded from ^15.0.0 react: ^19.0.0

Packages reference with `"package": "catalog:"` in package.json.
catalog: next: ^16.0.0 # Upgraded from ^15.0.0 react: ^19.0.0

在package.json中使用`"package": "catalog:"`来引用包。

2. Install and Test

2. 安装与测试

bash
pnpm install
pnpm tsc --noEmit  # Type check
pnpm test          # Unit tests
pnpm biome check . # Lint
pnpm build         # Build
pnpm dev           # Manual testing
bash
pnpm install
pnpm tsc --noEmit  # Type check
pnpm test          # Unit tests
pnpm biome check . # Lint
pnpm build         # Build
pnpm dev           # Manual testing

3. Fix Breaking Changes

3. 修复破坏性变更

typescript
// Example: Next.js 16 async params
// Before
export default function Page({ params }: { params: { id: string } }) {
  return <div>{params.id}</div>;
}

// After
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  return <div>{id}</div>;
}
typescript
// Example: Next.js 16 async params
// Before
export default function Page({ params }: { params: { id: string } }) {
  return <div>{params.id}</div>;
}

// After
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  return <div>{id}</div>;
}

4. Commit

4. 提交代码

bash
git commit -m "chore(deps): upgrade Next.js to v16

- Upgrade Next.js 15 → 16
- Upgrade React 18 → 19
- Fix async params migration

BREAKING CHANGE: Requires Node.js 20+"
bash
git commit -m "chore(deps): upgrade Next.js to v16

- Upgrade Next.js 15 → 16
- Upgrade React 18 → 19
- Fix async params migration

BREAKING CHANGE: Requires Node.js 20+"

Major Version Upgrades

主版本升级

Next.js

Next.js

bash
pnpm dlx @next/codemod@latest upgrade latest  # Run codemod
bash
pnpm dlx @next/codemod@latest upgrade latest  # Run codemod

Update catalog: next: ^16.0.0, react: ^19.0.0

Update catalog: next: ^16.0.0, react: ^19.0.0

pnpm install
pnpm install

Fix: async params, async cookies/headers

Fix: async params, async cookies/headers

undefined
undefined

TypeScript

TypeScript

bash
undefined
bash
undefined

Update catalog: typescript: ^5.3.3

Update catalog: typescript: ^5.3.3

pnpm install pnpm tsc --noEmit # Fix type errors
undefined
pnpm install pnpm tsc --noEmit # Fix type errors
undefined

Drizzle ORM

Drizzle ORM

bash
undefined
bash
undefined

Update catalog: drizzle-orm: ^0.30.0, drizzle-kit: ^0.20.0

Update catalog: drizzle-orm: ^0.30.0, drizzle-kit: ^0.20.0

pnpm install pnpm -F @sgcarstrends/database db:generate # If schema changed
undefined
pnpm install pnpm -F @sgcarstrends/database db:generate # If schema changed
undefined

Security Updates

安全更新

bash
pnpm audit                 # Check vulnerabilities
pnpm audit --fix           # Auto-fix
bash
pnpm audit                 # Check vulnerabilities
pnpm audit --fix           # Auto-fix

Or manually update vulnerable package in catalog

Or manually update vulnerable package in catalog

undefined
undefined

Dependency Conflicts

依赖冲突解决

bash
pnpm why package-name      # Check dependency chain
pnpm dedupe                # Deduplicate
Use overrides as last resort:
json
{ "pnpm": { "overrides": { "react": "^19.0.0" } } }
bash
pnpm why package-name      # Check dependency chain
pnpm dedupe                # Deduplicate
将覆盖配置作为最后手段：
json
{ "pnpm": { "overrides": { "react": "^19.0.0" } } }

Rollback

回滚

bash
git reset --hard HEAD
bash
git reset --hard HEAD

Or revert lockfile:

Or revert lockfile:

git checkout main -- pnpm-lock.yaml pnpm install
undefined
git checkout main -- pnpm-lock.yaml pnpm install
undefined

Troubleshooting

故障排除

bash
undefined
bash
undefined

Lockfile conflicts

Lockfile conflicts

rm pnpm-lock.yaml && pnpm install
rm pnpm-lock.yaml && pnpm install

Build failures after upgrade

Build failures after upgrade

rm -rf node_modules .turbo dist .next && pnpm install && pnpm build
undefined
rm -rf node_modules .turbo dist .next && pnpm install && pnpm build
undefined

Best Practices

最佳实践

  1. Use Catalog: Centralize versions in pnpm-workspace.yaml
  2. Test Thoroughly: Run all tests after upgrades
  3. Read Changelogs: Review breaking changes before upgrading
  4. Upgrade Incrementally: Don't update everything at once
  5. Commit Separately: Separate dependency upgrades from features
  6. Automate Security: Use Dependabot for security patches
  1. 使用Catalog：在pnpm-workspace.yaml中集中管理版本
  2. 全面测试：升级后运行所有测试
  3. 阅读变更日志：升级前查看破坏性变更
  4. 增量升级：不要一次性更新所有依赖
  5. 单独提交：将依赖升级与功能开发的提交分开
  6. 自动化安全更新：使用Dependabot处理安全补丁

References

参考资料