Dependency Upgrade Skill

Uses pnpm with catalog for centralized dependency management.

Check for Updates

pnpm outdated                      # Check all outdated
pnpm -r outdated                   # Across workspace
pnpm -F /api outdated # Specific package
pnpm dlx taze --interactive        # Interactive upgrade

Upgrade Process

1. Update Catalog

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

Packages reference with "package": "catalog:" in package.json.

2. Install and Test

pnpm install
pnpm tsc --noEmit  # Type check
pnpm test          # Unit tests
pnpm biome check . # Lint
pnpm build         # Build
pnpm dev           # Manual testing

3. Fix Breaking Changes

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

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

4. Commit

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

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

BREAKING CHANGE: Requires Node.js 20+"

Major Version Upgrades

Next.js

pnpm dlx @next/codemod@latest upgrade latest  # Run codemod
# Update catalog: next: ^16.0.0, react: ^19.0.0
pnpm install
# Fix: async params, async cookies/headers

TypeScript

# Update catalog: typescript: ^5.3.3
pnpm install
pnpm tsc --noEmit  # Fix type errors

Drizzle ORM

# Update catalog: drizzle-orm: ^0.30.0, drizzle-kit: ^0.20.0
pnpm install
pnpm -F /database db:generate  # If schema changed

Security Updates

pnpm audit                 # Check vulnerabilities
pnpm audit --fix           # Auto-fix
# Or manually update vulnerable package in catalog

Dependency Conflicts

pnpm why package-name      # Check dependency chain
pnpm dedupe                # Deduplicate

Use overrides as last resort:

{ "pnpm": { "overrides": { "react": "^19.0.0" } } }

Rollback

git reset --hard HEAD
# Or revert lockfile:
git checkout main -- pnpm-lock.yaml
pnpm install

Troubleshooting

# Lockfile conflicts
rm pnpm-lock.yaml && pnpm install

# Build failures after upgrade
rm -rf node_modules .turbo dist .next && pnpm install && pnpm build

Best Practices

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 for security patches

References

• pnpm Catalog: https://pnpm.io/catalogs
• Next.js Codemods: https://nextjs.org/docs/app/building-your-application/upgrading/codemods
• See security skill for vulnerability scanning