Dependency Upgrade

1---
2name: dependency-upgrade
3description: 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.
4---
5 
6# Dependency Upgrade
7 
8Master major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing approaches.
9 
10## Do not use this skill when
11 
12- The task is unrelated to dependency upgrade
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- Upgrading major framework versions
25- Updating security-vulnerable dependencies
26- Modernizing legacy dependencies
27- Resolving dependency conflicts
28- Planning incremental upgrade paths
29- Testing compatibility matrices
30- Automating dependency updates
31 
32## Semantic Versioning Review
33 
34```
35MAJOR.MINOR.PATCH (e.g., 2.3.1)
36 
37MAJOR: Breaking changes
38MINOR: New features, backward compatible
39PATCH: Bug fixes, backward compatible
40 
41^2.3.1 = >=2.3.1 <3.0.0 (minor updates)
42~2.3.1 = >=2.3.1 <2.4.0 (patch updates)
432.3.1 = exact version
44```
45 
46## Dependency Analysis
47 
48### Audit Dependencies
49```bash
50# npm
51npm outdated
52npm audit
53npm audit fix
54 
55# yarn
56yarn outdated
57yarn audit
58 
59# Check for major updates
60npx npm-check-updates
61npx npm-check-updates -u  # Update package.json
62```
63 
64### Analyze Dependency Tree
65```bash
66# See why a package is installed
67npm ls package-name
68yarn why package-name
69 
70# Find duplicate packages
71npm dedupe
72yarn dedupe
73 
74# Visualize dependencies
75npx madge --image graph.png src/
76```
77 
78## Compatibility Matrix
79 
80```javascript
81// compatibility-matrix.js
82const compatibilityMatrix = {
83  'react': {
84    '16.x': {
85      'react-dom': '^16.0.0',
86      'react-router-dom': '^5.0.0',
87      '@testing-library/react': '^11.0.0'
88    },
89    '17.x': {
90      'react-dom': '^17.0.0',
91      'react-router-dom': '^5.0.0 || ^6.0.0',
92      '@testing-library/react': '^12.0.0'
93    },
94    '18.x': {
95      'react-dom': '^18.0.0',
96      'react-router-dom': '^6.0.0',
97      '@testing-library/react': '^13.0.0'
98    }
99  }
100};
101 
102function checkCompatibility(packages) {
103  // Validate package versions against matrix
104}
105```
106 
107## Staged Upgrade Strategy
108 
109### Phase 1: Planning
110```bash
111# 1. Identify current versions
112npm list --depth=0
113 
114# 2. Check for breaking changes
115# Read CHANGELOG.md and MIGRATION.md
116 
117# 3. Create upgrade plan
118echo "Upgrade order:
1191. TypeScript
1202. React
1213. React Router
1224. Testing libraries
1235. Build tools" > UPGRADE_PLAN.md
124```
125 
126### Phase 2: Incremental Updates
127```bash
128# Don't upgrade everything at once!
129 
130# Step 1: Update TypeScript
131npm install typescript@latest
132 
133# Test
134npm run test
135npm run build
136 
137# Step 2: Update React (one major version at a time)
138npm install react@17 react-dom@17
139 
140# Test again
141npm run test
142 
143# Step 3: Continue with other packages
144npm install react-router-dom@6
145 
146# And so on...
147```
148 
149### Phase 3: Validation
150```javascript
151// tests/compatibility.test.js
152describe('Dependency Compatibility', () => {
153  it('should have compatible React versions', () => {
154    const reactVersion = require('react/package.json').version;
155    const reactDomVersion = require('react-dom/package.json').version;
156 
157    expect(reactVersion).toBe(reactDomVersion);
158  });
159 
160  it('should not have peer dependency warnings', () => {
161    // Run npm ls and check for warnings
162  });
163});
164```
165 
166## Breaking Change Handling
167 
168### Identifying Breaking Changes
169```bash
170# Use changelog parsers
171npx changelog-parser react 16.0.0 17.0.0
172 
173# Or manually check
174curl https://raw.githubusercontent.com/facebook/react/main/CHANGELOG.md
175```
176 
177### Codemod for Automated Fixes
178```bash
179# React upgrade codemods
180npx react-codeshift <transform> <path>
181 
182# Example: Update lifecycle methods
183npx react-codeshift \
184  --parser tsx \
185  --transform react-codeshift/transforms/rename-unsafe-lifecycles.js \
186  src/
187```
188 
189### Custom Migration Script
190```javascript
191// migration-script.js
192const fs = require('fs');
193const glob = require('glob');
194 
195glob('src/**/*.tsx', (err, files) => {
196  files.forEach(file => {
197    let content = fs.readFileSync(file, 'utf8');
198 
199    // Replace old API with new API
200    content = content.replace(
201      /componentWillMount/g,
202      'UNSAFE_componentWillMount'
203    );
204 
205    // Update imports
206    content = content.replace(
207      /import { Component } from 'react'/g,
208      "import React, { Component } from 'react'"
209    );
210 
211    fs.writeFileSync(file, content);
212  });
213});
214```
215 
216## Testing Strategy
217 
218### Unit Tests
219```javascript
220// Ensure tests pass before and after upgrade
221npm run test
222 
223// Update test utilities if needed
224npm install @testing-library/react@latest
225```
226 
227### Integration Tests
228```javascript
229// tests/integration/app.test.js
230describe('App Integration', () => {
231  it('should render without crashing', () => {
232    render(<App />);
233  });
234 
235  it('should handle navigation', () => {
236    const { getByText } = render(<App />);
237    fireEvent.click(getByText('Navigate'));
238    expect(screen.getByText('New Page')).toBeInTheDocument();
239  });
240});
241```
242 
243### Visual Regression Tests
244```javascript
245// visual-regression.test.js
246describe('Visual Regression', () => {
247  it('should match snapshot', () => {
248    const { container } = render(<App />);
249    expect(container.firstChild).toMatchSnapshot();
250  });
251});
252```
253 
254### E2E Tests
255```javascript
256// cypress/e2e/app.cy.js
257describe('E2E Tests', () => {
258  it('should complete user flow', () => {
259    cy.visit('/');
260    cy.get('[data-testid="login"]').click();
261    cy.get('input[name="email"]').type('user@example.com');
262    cy.get('button[type="submit"]').click();
263    cy.url().should('include', '/dashboard');
264  });
265});
266```
267 
268## Automated Dependency Updates
269 
270### Renovate Configuration
271```json
272// renovate.json
273{
274  "extends": ["config:base"],
275  "packageRules": [
276    {
277      "matchUpdateTypes": ["minor", "patch"],
278      "automerge": true
279    },
280    {
281      "matchUpdateTypes": ["major"],
282      "automerge": false,
283      "labels": ["major-update"]
284    }
285  ],
286  "schedule": ["before 3am on Monday"],
287  "timezone": "America/New_York"
288}
289```
290 
291### Dependabot Configuration
292```yaml
293# .github/dependabot.yml
294version: 2
295updates:
296  - package-ecosystem: "npm"
297    directory: "/"
298    schedule:
299      interval: "weekly"
300    open-pull-requests-limit: 5
301    reviewers:
302      - "team-leads"
303    commit-message:
304      prefix: "chore"
305      include: "scope"
306```
307 
308## Rollback Plan
309 
310```javascript
311// rollback.sh
312#!/bin/bash
313 
314# Save current state
315git stash
316git checkout -b upgrade-branch
317 
318# Attempt upgrade
319npm install package@latest
320 
321# Run tests
322if npm run test; then
323  echo "Upgrade successful"
324  git add package.json package-lock.json
325  git commit -m "chore: upgrade package"
326else
327  echo "Upgrade failed, rolling back"
328  git checkout main
329  git branch -D upgrade-branch
330  npm install  # Restore from package-lock.json
331fi
332```
333 
334## Common Upgrade Patterns
335 
336### Lock File Management
337```bash
338# npm
339npm install --package-lock-only  # Update lock file only
340npm ci  # Clean install from lock file
341 
342# yarn
343yarn install --frozen-lockfile  # CI mode
344yarn upgrade-interactive  # Interactive upgrades
345```
346 
347### Peer Dependency Resolution
348```bash
349# npm 7+: strict peer dependencies
350npm install --legacy-peer-deps  # Ignore peer deps
351 
352# npm 8+: override peer dependencies
353npm install --force
354```
355 
356### Workspace Upgrades
357```bash
358# Update all workspace packages
359npm install --workspaces
360 
361# Update specific workspace
362npm install package@latest --workspace=packages/app
363```
364 
365## Resources
366 
367- **references/semver.md**: Semantic versioning guide
368- **references/compatibility-matrix.md**: Common compatibility issues
369- **references/staged-upgrades.md**: Incremental upgrade strategies
370- **references/testing-strategy.md**: Comprehensive testing approaches
371- **assets/upgrade-checklist.md**: Step-by-step checklist
372- **assets/compatibility-matrix.csv**: Version compatibility table
373- **scripts/audit-dependencies.sh**: Dependency audit script
374 
375## Best Practices
376 
3771. **Read Changelogs**: Understand what changed
3782. **Upgrade Incrementally**: One major version at a time
3793. **Test Thoroughly**: Unit, integration, E2E tests
3804. **Check Peer Dependencies**: Resolve conflicts early
3815. **Use Lock Files**: Ensure reproducible installs
3826. **Automate Updates**: Use Renovate or Dependabot
3837. **Monitor**: Watch for runtime errors post-upgrade
3848. **Document**: Keep upgrade notes
385 
386## Upgrade Checklist
387 
388```markdown
389Pre-Upgrade:
390- [ ] Review current dependency versions
391- [ ] Read changelogs for breaking changes
392- [ ] Create feature branch
393- [ ] Backup current state (git tag)
394- [ ] Run full test suite (baseline)
395 
396During Upgrade:
397- [ ] Upgrade one dependency at a time
398- [ ] Update peer dependencies
399- [ ] Fix TypeScript errors
400- [ ] Update tests if needed
401- [ ] Run test suite after each upgrade
402- [ ] Check bundle size impact
403 
404Post-Upgrade:
405- [ ] Full regression testing
406- [ ] Performance testing
407- [ ] Update documentation
408- [ ] Deploy to staging
409- [ ] Monitor for errors
410- [ ] Deploy to production
411```
412 
413## Common Pitfalls
414 
415- Upgrading all dependencies at once
416- Not testing after each upgrade
417- Ignoring peer dependency warnings
418- Forgetting to update lock file
419- Not reading breaking change notes
420- Skipping major versions
421- Not having rollback plan
422