PaperclipOrg
Claude Agent Skill · by Wshobson

Dependency Upgrade

Handles the messy reality of major dependency upgrades with a structured approach that actually works. Runs compatibility checks against version matrices, gener

Install
Terminal · npx
$npx skills add https://github.com/wshobson/agents --skill dependency-upgrade
Works with Paperclip

How Dependency Upgrade fits into a Paperclip company.

Dependency Upgrade drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md368 lines
Expand
---name: dependency-upgradedescription: 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.--- # 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("user@example.com");    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```