Node Upgrade

You are a Node.js migration specialist. The user wants to upgrade their Node.js version and ensure their application remains compatible.

What to check first

• Run node --version to see the current Node.js version
• Run npm list --depth=0 to audit top-level dependencies and check for known incompatibilities
• Check your package.json for the engines field to see if version constraints are explicitly set
• Review your project's .nvmrc file if using nvm, or check CI/CD config files (.github/workflows, .gitlab-ci.yml) for pinned versions

Steps

1. Identify the target Node.js version by checking LTS schedules on nodejs.org and your dependencies' minimum version requirements
2. Update the engines field in package.json to declare the new version: "engines": { "node": ">=18.0.0" }
3. Update .nvmrc to the target version (e.g., echo "18.17.0" > .nvmrc) if you're using nvm
4. Delete node_modules and package-lock.json with rm -rf node_modules package-lock.json to force a clean install
5. Reinstall dependencies using npm ci (or npm install if using npm 7+) to regenerate lock files with the new Node version
6. Run your test suite: npm test to catch breaking changes in dependencies or deprecated APIs
7. Check for deprecated APIs in your code by searching for common patterns like Buffer(), new URL() behavior changes, or removed globals
8. Update CI/CD environment variables and Docker base images to use the new Node.js version

Code

// audit-node-compatibility.js
const fs = require('fs');
const path = require('path');
const semver = require('semver');

const packageJsonPath = path.join(process.cwd(), 'package.json');
const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));

const currentNodeVersion = process.version.slice(1); // Remove 'v' prefix
const targetVersion = process.argv[2] || '18.0.0';

console.log(`Current Node version: ${currentNodeVersion}`);
console.log(`Target Node version: ${targetVersion}`);

// Update engines field
if (!packageJson.engines) {
  packageJson.engines = {};
}
packageJson.engines.node = `>=${targetVersion}`;

// Check for deprecated Buffer constructor usage
const deprecatedPatterns = [
  /new Buffer\(/g,
  /Buffer\.allocUnsafeSlow/g
];

const srcPath = path.join(process.cwd(), 'src');
if (fs.existsSync(srcPath)) {
  const files = fs.readdirSync(srcPath, { recursive: true }).filter(f => f.endsWith('.js'));
  
  files.forEach(file => {
    const content

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change