NPM Package Upgrade Automation

A comprehensive tool for automating NPM package upgrades with smart codemods and validation. This tool systematically upgrades npm packages across multiple projects while ensuring compatibility, running tests, and applying framework-specific codemods automatically.

📋 Table of Contents

• Features
• Installation
• Quick Start
• CLI Usage
• Supported Frameworks
• Configuration
• License

✨ Features

• Smart Detection: Uses npm-check-updates to find outdated packages with version preview
• Official Codemods: Automatically runs React 19, Tailwind v4, Next.js, ESLint 9, Redux, React Router v7, TypeScript, Angular, and Vite migrations
• Multi-Project Support: Upgrade multiple projects sequentially or in parallel
• Validation: Runs tests, builds, and linting automatically after upgrades
• Auto-Rollback: Automatically reverts on test failure with backup verification
• Security Scanning: npm audit integration with severity filtering
• Git Integration: Creates branches and commits changes safely
• Detailed Reporting: JSON reports with full audit trail
• Codemod Registry: Searches community codemods for additional suggestions

🚀 Installation

Prerequisites

• Node.js 14.0.0 or higher
• npm 7.0.0 or higher
• Git (optional, for branch creation)

Global Installation (Recommended)

npm install -g @devsarc/dep-upgrade

Now you can use the CLI from anywhere:

dep-upgrade --help

Local Installation

npm install --save-dev @devsarc/dep-upgrade

Use via npx or package scripts:

npx dep-upgrade --help

⚡ Quick Start

Upgrade Current Project

# Navigate to your project
cd /path/to/your/project

# Run the upgrade
dep-upgrade

Upgrade Multiple Projects

dep-upgrade ./project1 ./project2 ./project3

Interactive Mode

dep-upgrade --interactive

You'll be asked to confirm before each upgrade.

With Configuration File

Create .upgraderc.json in your project:

{
  "upgradeStrategy": {
    "target": "latest",
    "runTests": true,
    "runBuild": true,
    "parallel": false
  },
  "codemods": {
    "react": true,
    "nextjs": true,
    "tailwind": true
  }
}

Then run:

dep-upgrade --config .upgraderc.json

🖥️ CLI Usage

Commands

dep-upgrade [OPTIONS] [PROJECTS...]

Options

| Option | Description | |--------|-------------| | -h, --help | Show help message | | -v, --version | Show version number | | -i, --interactive | Ask before each upgrade | | -p, --project <path> | Specify project path (can be used multiple times) | | --config <file> | Load configuration from file | | --target <version> | Upgrade target: latest, major, minor, patch (default: latest) | | --parallel | Run upgrades in parallel | | --max-parallel <num> | Maximum parallel workers (default: 3) | | --no-git | Skip creating git branch | | --no-tests | Skip running tests | | --no-build | Skip running build | | --verbose | Show detailed output |

Examples

# Upgrade current project
dep-upgrade

# Upgrade specific project
dep-upgrade --project ./my-app

# Upgrade multiple projects
dep-upgrade ./app1 ./app2 ./app3

# Interactive mode
dep-upgrade --interactive

# Upgrade to specific version target
dep-upgrade --target major

# Parallel upgrade with custom config
dep-upgrade --parallel --config .upgraderc.json

# Quick upgrade without tests/build
dep-upgrade --no-tests --no-build

# Upgrade only patch versions (safest)
dep-upgrade --target patch

# Verbose mode for debugging
dep-upgrade --verbose

🎯 Supported Frameworks

The tool automatically detects and applies framework-specific migrations using official codemods. Here's what's currently supported:

| Framework | Migration Details | |-----------|-------------------| | React 19 | Official migration recipe (ReactDOM render, string refs, hooks) | | Next.js 15 | Automatic codemods for latest version | | Nuxt 4 | File structure, reactivity, watch paths migration | | Tailwind CSS v4 | Smart upgrade with framework detection (Vite/Next.js/PostCSS), CSS migration, breaking change warnings | | ESLint 9 | Flat config migration from legacy .eslintrc | | Vue 3 | Component API, global API, directives migration | | Angular 18+ | Automatic migration with ng update and schematics | | Zod 4 | API syntax updates (nonstrict, or/and, describe) | | MSW v2 | Mock Service Worker v1 to v2 migration |

Tailwind CSS v4 - Framework-Aware Upgrade

The Tailwind upgrade is particularly smart:

• Automatically detects your framework (Vite, Next.js, or PostCSS)
• Configures optimal Tailwind integration:
  • Vite projects: Installs and configures @tailwindcss/vite plugin
  • Next.js projects: Sets up @tailwindcss/postcss with modern ESM config
  • Other projects: Configures PostCSS integration
• Migrates CSS files: @tailwind directives → @import "tailwindcss"
• Warns about critical breaking changes (borders, rings, shadows, opacity utilities)
• Supports all package managers (npm, yarn, pnpm, bun)

⚙️ Configuration

Configuration File

{
  upgradeStrategy: {
    target: 'latest',          // 'latest', 'major', 'minor', 'patch'
    runTests: true,            // Run npm test after upgrade
    runBuild: true,            // Run npm run build after upgrade
    runLint: true,             // Run lint --fix
    interactive: false,        // Ask before each upgrade
    createGitBranch: true,     // Create upgrade branch
    parallel: false,           // Process multiple projects simultaneously
    maxParallel: 3,            // Max parallel workers
    backup: true,              // Backup package.json
    autoRollback: true,        // Rollback on test failure
  },
  codemods: {
    tailwind: true,            // Run Tailwind codemod
    nextjs: true,              // Run Next.js codemod
    angular: true,             // Run Angular update
    react: true,               // Check React deprecations
    typescript: true,          // Update TypeScript
  },
  security: {
    enabled: true,             // Run security scans
    failOnVulnerabilities: false,
    severity: 'high',          // 'low', 'moderate', 'high', 'critical'
  },
}

Output

After running upgrades, you'll get a detailed JSON report showing what happened:

{
  "timestamp": "2025-12-17T10:30:00.000Z",
  "reports": [
    {
      "projectPath": "./projects/website",
      "status": "success",
      "duration": 45300,
      "steps": [
        { "name": "analyze", "status": "completed", "outdatedCount": 15 },
        { "name": "upgrade", "status": "completed" },
        { "name": "install", "status": "completed" },
        { "name": "codemods", "status": "completed" },
        { "name": "security", "status": "completed", "vulnerabilities": 0 },
        { "name": "validation", "status": "completed" }
      ]
    }
  ]
}

📄 License

MIT License - Feel free to modify and use in your projects.