Dependency Upgrade Skill

This skill helps you safely upgrade dependencies across the monorepo using pnpm catalog and proper testing procedures.

When to Use This Skill

• Upgrading npm packages
• Applying security patches
• Updating to latest versions
• Upgrading major versions
• Resolving dependency conflicts
• Modernizing tech stack
• Following breaking change guides

Dependency Management

The project uses pnpm with catalog for centralized dependency management:

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

catalog:
  # Shared versions across workspace
  next: ^16.0.0
  react: ^19.0.0
  react-dom: ^19.0.0
  typescript: ^5.3.3
  drizzle-orm: ^0.30.0
  # ... more dependencies

Checking for Updates

List Outdated Packages

# Check all outdated packages
pnpm outdated

# Check recursively across workspace
pnpm -r outdated

# Check specific package
pnpm -F @sgcarstrends/api outdated

# Output:
# Package        Current  Latest  Wanted
# next           15.0.0   16.0.0  16.0.0
# react          18.2.0   19.0.0  19.0.0
# drizzle-orm    0.28.0   0.30.0  0.30.0

Interactive Update

# Interactive upgrade tool
pnpm dlx npm-check-updates --interactive

# Or use taze (modern alternative)
pnpm dlx taze --interactive

Upgrading Dependencies

Update Catalog Versions

# pnpm-workspace.yaml
catalog:
  # Before
  next: ^15.0.0

  # After
  next: ^16.0.0

Update Package.json

// package.json uses catalog:
{
  "dependencies": {
    "next": "catalog:",  // Automatically uses catalog version
    "react": "catalog:"
  }
}

Install Updates

# Update all packages to catalog versions
pnpm install

# Update specific workspace
pnpm -F @sgcarstrends/web install

# Update recursively
pnpm -r install

Safe Upgrade Process

1. Check Current Versions

# List current versions
pnpm list | grep package-name

# Check specific package
pnpm list next

2. Review Changelog

# Check package changelog
pnpm view next versions
pnpm view next --json | jq '.versions[-5:]'

# Visit GitHub releases
open https://github.com/vercel/next.js/releases

3. Check Breaking Changes

# Read upgrade guide
# Next.js example:
open https://nextjs.org/docs/app/building-your-application/upgrading/version-16

# Check migration codemods
pnpm dlx @next/codemod upgrade latest

4. Create Branch

# Create upgrade branch
git checkout -b upgrade/next-16

# Or for security patches
git checkout -b security/fix-vulnerabilities

5. Update Catalog

# pnpm-workspace.yaml
catalog:
  next: ^16.0.0  # Upgraded from ^15.0.0
  react: ^19.0.0  # Upgraded from ^18.2.0

6. Install and Test

# Install updates
pnpm install

# Run tests
pnpm test

# Type check
pnpm tsc --noEmit

# Lint
pnpm biome check .

# Build
pnpm build

# Start development
pnpm dev

7. Fix Breaking Changes

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

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

8. Commit Changes

# Add changes
git add pnpm-workspace.yaml pnpm-lock.yaml

# Commit with conventional commit
git commit -m "chore(deps): upgrade Next.js to v16

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

BREAKING CHANGE: Requires Node.js 20+"

Major Version Upgrades

Next.js Upgrade

# Step 1: Check current version
pnpm list next

# Step 2: Review upgrade guide
open https://nextjs.org/docs/app/building-your-application/upgrading

# Step 3: Run codemod
pnpm dlx @next/codemod@latest upgrade latest

# Step 4: Update catalog
vim pnpm-workspace.yaml

# Step 5: Install
pnpm install

# Step 6: Fix breaking changes
# - Async params
# - Async cookies/headers
# - Cache Components (if enabled)

# Step 7: Test
pnpm -F @sgcarstrends/web build
pnpm -F @sgcarstrends/web test

React Upgrade

# Upgrade React 18 → 19
# Update catalog
catalog:
  react: ^19.0.0
  react-dom: ^19.0.0

# Install
pnpm install

# Check for breaking changes
# - Server Components (stable)
# - useTransition changes
# - Suspense improvements

# Test thoroughly
pnpm test

TypeScript Upgrade

# Upgrade TypeScript 5.2 → 5.3
catalog:
  typescript: ^5.3.3

pnpm install

# Check for type errors
pnpm tsc --noEmit

# Fix any new strict checks

Security Updates

Check Vulnerabilities

# Audit dependencies
pnpm audit

# Output:
# High: Prototype pollution in lodash
# Package: lodash
# Patched in: >=4.17.21
# Path: lodash

Apply Security Patches

# Update vulnerable package
# In catalog:
catalog:
  lodash: ^4.17.21  # Patched version

pnpm install

# Verify fix
pnpm audit

# Or use audit fix
pnpm audit --fix

Automated Security PRs

Enable Dependabot:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    groups:
      security:
        patterns:
          - "*"
        update-types:
          - "patch"
          - "minor"

Dependency Conflicts

Resolve Conflicts

# Issue: Peer dependency conflict
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from [email protected]

# Solution 1: Update catalog to compatible version
catalog:
  react: ^19.0.0
  some-package: ^2.0.0  # Version compatible with React 19

# Solution 2: Use overrides (last resort)
{
  "pnpm": {
    "overrides": {
      "react": "^19.0.0"
    }
  }
}

Deduplicate Dependencies

# Check for duplicates
pnpm list --depth=0 | grep package-name

# Deduplicate
pnpm dedupe

# Verify
pnpm install

Testing Upgrades

Test Checklist

# 1. Type check
pnpm tsc --noEmit

# 2. Lint
pnpm biome check .

# 3. Unit tests
pnpm test

# 4. E2E tests
pnpm test:e2e

# 5. Build
pnpm build

# 6. Manual testing
pnpm dev
# Test critical flows manually

# 7. Check bundle size
pnpm -F @sgcarstrends/web build
# Review .next/analyze (if enabled)

Rollback if Needed

# If upgrade causes issues
git reset --hard HEAD

# Or revert commit
git revert <commit-hash>

# Restore pnpm-lock.yaml
git checkout main -- pnpm-lock.yaml
pnpm install

Automated Upgrades

Renovate Bot

// renovate.json
{
  "extends": ["config:base"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchPackagePatterns": ["^@types/"],
      "automerge": true
    }
  ],
  "schedule": ["before 3am on Monday"],
  "timezone": "Asia/Singapore"
}

Best Practices

1. Update Gradually

# ❌ Update everything at once
pnpm dlx npm-check-updates -u
pnpm install

# ✅ Update incrementally
# Week 1: Update minor versions
# Week 2: Update React/Next.js
# Week 3: Update build tools

2. Read Changelogs

# ❌ Blindly upgrade
pnpm install next@latest

# ✅ Review changes first
pnpm view next --json | jq .versions
open https://github.com/vercel/next.js/releases
# Read breaking changes
# Update code accordingly

3. Test Thoroughly

# ❌ Only run unit tests
pnpm test

# ✅ Comprehensive testing
pnpm tsc --noEmit  # Type check
pnpm test          # Unit tests
pnpm test:e2e      # E2E tests
pnpm build         # Build check
# Manual testing

4. Commit Separately

# ❌ Mix feature and upgrades
git commit -m "feat: add feature X and upgrade deps"

# ✅ Separate commits
git commit -m "chore(deps): upgrade Next.js to v16"
git commit -m "feat: add feature X"

Common Upgrades

Next.js 15 → 16

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

# Update catalog
catalog:
  next: ^16.0.0
  react: ^19.0.0
  react-dom: ^19.0.0

# Install
pnpm install

# Fix breaking changes
# - Async params/searchParams
# - Async cookies/headers
# - Cache Components patterns

Drizzle ORM

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

pnpm install

# Generate new migrations if schema changed
pnpm -F @sgcarstrends/database db:generate

Biome (replacing ESLint)

# Remove ESLint
pnpm remove -r eslint @typescript-eslint/*

# Add Biome
catalog:
  "@biomejs/biome": ^1.9.4

pnpm install

# Migrate config
pnpm dlx @biomejs/biome migrate eslint --write

Troubleshooting

Lockfile Conflicts

# Issue: pnpm-lock.yaml conflicts
# Solution: Regenerate lockfile

rm pnpm-lock.yaml
pnpm install

Peer Dependency Warnings

# Issue: Peer dependency warning
# Solution: Update to compatible versions

# Check peer dependencies
pnpm why package-name

# Update catalog
catalog:
  package-name: ^2.0.0

Build Failures After Upgrade

# Issue: Build fails after upgrade
# Solution: Clear caches

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

References

• pnpm Catalog: https://pnpm.io/catalogs
• npm-check-updates: https://github.com/raineorshine/npm-check-updates
• Next.js Codemods: https://nextjs.org/docs/app/building-your-application/upgrading/codemods
• Renovate: https://docs.renovatebot.com
• Related files:
  • pnpm-workspace.yaml - Catalog configuration
  • package.json - Package dependencies
  • Root CLAUDE.md - Dependency guidelines

Best Practices Summary

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 or Renovate for patches
7. Check Compatibility: Verify peer dependencies
8. Document Changes: Note breaking changes in commit message