/dependency-upgrade

Dependency Compatibility Matrix

Common version compatibility requirements for major frameworks and libraries.

React Ecosystem

React 18 → 19 Migration

bun add react@19 react-dom@19
bun add -D @testing-library/react@16 @types/react@19 @types/react-dom@19

Key breaking changes:

• Ref as prop (no more forwardRef needed)
• useDeferredValue initial value support
• Improved hydration mismatch reporting
• ref cleanup functions return value is ignored

React Router 6 → 7

bun add react-router@7 react-router-dom@7

React Router v7 is the successor to Remix and React Router v6. Key changes:

• Framework mode (Remix-like) vs library mode
• New createRootRoute, createRouter API
• Data loading via loader and action

Next.js

Next.js 14 → 15 Migration

bun add next@15

Key breaking changes:

• Turbopack as default dev bundler
• Improved caching defaults (fetch requests no longer cached by default)
• next/image changes
• Node.js >=20.9 required

TypeScript

TypeScript Upgrade

bun add -D typescript@latest

TypeScript upgrades are typically backward compatible. Run type-check after upgrade:

bunx tsc --noEmit

Tailwind CSS

Tailwind 3 → 4 Migration

bun add -D tailwindcss@4 @tailwindcss/vite

Key changes:

• CSS-first configuration (@theme instead of tailwind.config.js)
• Required primary entrypoint: @import "tailwindcss"
• PostCSS plugin via @tailwindcss/postcss package (must install and configure)
• Lightning CSS can replace PostCSS in some setups per official Tailwind recommendations
• New @source inline("class-name") pattern for safelisting utilities

Node.js Version Compatibility

See Node.js Release Schedule for LTS dates.

Checking Compatibility

# Check peer dependency warnings
npm ls 2>&1 | grep -i "peer dep"

# Check for outdated with compatibility info
npm outdated

# Use npm-check-updates for safe upgrade analysis
bunx npm-check-updates --interactive

# Check for known vulnerabilities
npm audit
bun audit