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 從公開儲存庫中收錄這些內容。

檢舉或申請下架