Dependency Upgrade

作者 wshobson46891e7e60da无许可证收录于 2026年10月8日更新于 2026年10月8日

Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing breaking changes in libraries.

AI 生成的概览

指导重大依赖版本升级,涵盖兼容性分析、分阶段发布、测试与回滚规划。

功能
该技能提供规划和执行重大依赖版本升级的说明。内容涵盖语义化版本审查、依赖审计与依赖树分析、兼容性矩阵、分阶段增量升级、借助 codemod 处理破坏性变更,以及单元、集成、视觉回归和端到端测试策略。它还记录了 Renovate 与 Dependabot 的自动更新配置、锁文件管理、对等依赖解析、工作区升级和回滚流程。
适用场景
适用于升级框架主版本、更新存在安全漏洞或陈旧的依赖、解决依赖冲突,或规划增量升级路径。也适合建立兼容性测试和自动化依赖更新流程。
运行要求
不附带脚本,仅为说明文档。按示例操作需具备使用 npm 或 yarn 的 JavaScript/TypeScript 项目,并可选使用 npm-check-updates、madge、jscodeshift 和测试运行器等工具。部分示例需要网络访问以获取变更日志或 codemod 转换脚本。

Dependency Upgrade

Master major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing approaches.

When to Use This Skill

  • Upgrading major framework versions
  • Updating security-vulnerable dependencies
  • Modernizing legacy dependencies
  • Resolving dependency conflicts
  • Planning incremental upgrade paths
  • Testing compatibility matrices
  • Automating dependency updates

Semantic Versioning Review

MAJOR.MINOR.PATCH (e.g., 2.3.1)
MAJOR: Breaking changesMINOR: New features, backward compatiblePATCH: Bug fixes, backward compatible
^2.3.1 = >=2.3.1 <3.0.0 (minor updates)~2.3.1 = >=2.3.1 <2.4.0 (patch updates)2.3.1 = exact version

Dependency Analysis

Audit Dependencies

bash
# npmnpm outdatednpm auditnpm audit fix
# yarnyarn outdatedyarn audit
# Check for major updatesnpx npm-check-updatesnpx npm-check-updates -u  # Update package.json

Analyze Dependency Tree

bash
# See why a package is installednpm ls package-nameyarn why package-name
# Find duplicate packagesnpm dedupeyarn dedupe
# Visualize dependenciesnpx madge --image graph.png src/

Compatibility Matrix

javascript
// compatibility-matrix.jsconst compatibilityMatrix = {  react: {    "16.x": {      "react-dom": "^16.0.0",      "react-router-dom": "^5.0.0",      "@testing-library/react": "^11.0.0",    },    "17.x": {      "react-dom": "^17.0.0",      "react-router-dom": "^5.0.0 || ^6.0.0",      "@testing-library/react": "^12.0.0",    },    "18.x": {      "react-dom": "^18.0.0",      "react-router-dom": "^6.0.0",      "@testing-library/react": "^13.0.0",    },  },};
function checkCompatibility(packages) {  // Validate package versions against matrix}

Staged Upgrade Strategy

Phase 1: Planning

bash
# 1. Identify current versionsnpm list --depth=0
# 2. Check for breaking changes# Read CHANGELOG.md and MIGRATION.md
# 3. Create upgrade planecho "Upgrade order:1. TypeScript2. React3. React Router4. Testing libraries5. Build tools" > UPGRADE_PLAN.md

Phase 2: Incremental Updates

bash
# Don't upgrade everything at once!
# Step 1: Update TypeScriptnpm install typescript@latest
# Testnpm run testnpm run build
# Step 2: Update React (one major version at a time)npm install react@17 react-dom@17
# Test againnpm run test
# Step 3: Continue with other packagesnpm install react-router-dom@6
# And so on...

Phase 3: Validation

javascript
// tests/compatibility.test.jsdescribe("Dependency Compatibility", () => {  it("should have compatible React versions", () => {    const reactVersion = require("react/package.json").version;    const reactDomVersion = require("react-dom/package.json").version;
    expect(reactVersion).toBe(reactDomVersion);  });
  it("should not have peer dependency warnings", () => {    // Run npm ls and check for warnings  });});

Breaking Change Handling

Identifying Breaking Changes

bash
# Check the changelog directlycurl https://raw.githubusercontent.com/facebook/react/master/CHANGELOG.md

Codemod for Automated Fixes

bash
# Run jscodeshift with transform URLnpx jscodeshift -t <transform-url> <path>
# Example: Rename unsafe lifecycle methodsnpx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js src/
# For TypeScript filesnpx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --parser=tsx src/
# Dry run to preview changesnpx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --dry src/

Custom Migration Script

javascript
// migration-script.jsconst fs = require("fs");const glob = require("glob");
glob("src/**/*.tsx", (err, files) => {  files.forEach((file) => {    let content = fs.readFileSync(file, "utf8");
    // Replace old API with new API    content = content.replace(      /componentWillMount/g,      "UNSAFE_componentWillMount",    );
    // Update imports    content = content.replace(      /import { Component } from 'react'/g,      "import React, { Component } from 'react'",    );
    fs.writeFileSync(file, content);  });});

Testing Strategy

Unit Tests

javascript
// Ensure tests pass before and after upgradenpm run test
// Update test utilities if needednpm install @testing-library/react@latest

Integration Tests

javascript
// tests/integration/app.test.jsdescribe("App Integration", () => {  it("should render without crashing", () => {    render(<App />);  });
  it("should handle navigation", () => {    const { getByText } = render(<App />);    fireEvent.click(getByText("Navigate"));    expect(screen.getByText("New Page")).toBeInTheDocument();  });});

Visual Regression Tests

javascript
// visual-regression.test.jsdescribe("Visual Regression", () => {  it("should match snapshot", () => {    const { container } = render(<App />);    expect(container.firstChild).toMatchSnapshot();  });});

E2E Tests

javascript
// cypress/e2e/app.cy.jsdescribe("E2E Tests", () => {  it("should complete user flow", () => {    cy.visit("/");    cy.get('[data-testid="login"]').click();    cy.get('input[name="email"]').type("[email protected]");    cy.get('button[type="submit"]').click();    cy.url().should("include", "/dashboard");  });});

Automated Dependency Updates

Renovate Configuration

json
// renovate.json{  "extends": ["config:base"],  "packageRules": [    {      "matchUpdateTypes": ["minor", "patch"],      "automerge": true    },    {      "matchUpdateTypes": ["major"],      "automerge": false,      "labels": ["major-update"]    }  ],  "schedule": ["before 3am on Monday"],  "timezone": "America/New_York"}

Dependabot Configuration

yaml
# .github/dependabot.ymlversion: 2updates:  - package-ecosystem: "npm"    directory: "/"    schedule:      interval: "weekly"    open-pull-requests-limit: 5    reviewers:      - "team-leads"    commit-message:      prefix: "chore"      include: "scope"

Rollback Plan

javascript
// rollback.sh#!/bin/bash
# Save current stategit stashgit checkout -b upgrade-branch
# Attempt upgradenpm install package@latest
# Run testsif npm run test; then  echo "Upgrade successful"  git add package.json package-lock.json  git commit -m "chore: upgrade package"else  echo "Upgrade failed, rolling back"  git checkout main  git branch -D upgrade-branch  npm install  # Restore from package-lock.jsonfi

Common Upgrade Patterns

Lock File Management

bash
# npmnpm install --package-lock-only  # Update lock file onlynpm ci  # Clean install from lock file
# yarnyarn install --frozen-lockfile  # CI modeyarn upgrade-interactive  # Interactive upgrades

Peer Dependency Resolution

bash
# npm 7+: strict peer dependenciesnpm install --legacy-peer-deps  # Ignore peer deps
# npm 8+: override peer dependenciesnpm install --force

Workspace Upgrades

bash
# Update all workspace packagesnpm install --workspaces
# Update specific workspacenpm install package@latest --workspace=packages/app

来源与署名

来源:wshobson/agents位于plugins/framework-migration/skills/dependency-upgrade提交46891e7

许可证: 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架