node-24-migration.md

name	description
node-24-migration	Assist users in migrating their Node.js projects to version 24.x LTS. Use when users ask to migrate Node.js versions and current version is 20.x or 22.x.

Node.js 20.x to 24.x Migration Assistant

This skill helps you migrate Node.js projects from version 20.x to 24.x LTS by identifying breaking changes, running codemods, and ensuring compatibility.

Migration Overview

The migration from Node.js 20 to 24 involves two major version jumps:

• Node.js 20 → 22: Import assertions syntax change
• Node.js 22 → 24: OpenSSL 3.5, platform support changes, crypto API updates

Breaking Changes Checklist

OpenSSL 3.5 (Node.js 24)

• Security Level 2 is now default
• ❌ RSA, DSA, DH keys < 2048 bits prohibited
• ❌ ECC keys < 224 bits prohibited
• ❌ RC4 cipher suites prohibited
• Action: Check and Test workloads with Node.js 24

Step-by-Step Migration Process

Examples use npm but can be adapted for pnpm or other package managers.

1. Pre-Migration Assessment

# Check current Node.js version
node --version

# Review package.json engines field
cat package.json | grep -A2 '"engines"'

# Check for deprecated APIs
npm audit

# Run existing tests
npm test

2. Run Codemods (Automated Fixes)

v20 → v22: Import Assertions

# Fix import assert → import with
npx codemod run @nodejs/import-assertions-to-attributes

What it fixes:

// Before
import data from "./data.json" assert { type: "json" };

// After
import data from "./data.json" with { type: "json" };

v22 → v24: Crypto RSA-PSS Updates

# Fix deprecated crypto.generateKeyPair options
npx codemod run @nodejs/crypto-rsa-pss-update

What it fixes (DEP0154):

// Before
crypto.generateKeyPair(
  "rsa-pss",
  {
    modulusLength: 2048,
    hash: "sha256",
    mgf1Hash: "sha1",
    saltLength: 32,
  },
  callback,
);

// After
crypto.generateKeyPair(
  "rsa-pss",
  {
    modulusLength: 2048,
    hashAlgorithm: "sha256",
    mgf1HashAlgorithm: "sha1",
    saltLength: 32,
  },
  callback,
);

v22 → v24: File System Updates

# Fix dirent.path → dirent.parentPath (DEP0178)
npx codemod run @nodejs/dirent-path-to-parent-path

# Fix fs.F_OK → fs.constants.F_OK (DEP0176)
npx codemod run @nodejs/fs-access-mode-constants

# Fix fs.truncate with fd → fs.ftruncate (DEP0081)
npx codemod run @nodejs/fs-truncate-fd-deprecation

Examples:

// dirent.path → dirent.parentPath
// Before
for (const dirent of dirents) {
  console.log(dirent.path);
}

// After
for (const dirent of dirents) {
  console.log(dirent.parentPath);
}

// fs access mode constants
// Before
fs.access("/path", fs.F_OK, callback);

// After
fs.access("/path", fs.constants.F_OK, callback);

// fs.truncate with file descriptor
// Before
fs.truncate(fd, 10, callback);

// After
fs.ftruncate(fd, 10, callback);

v22 → v24: Process Assert Updates

# Fix process.assert → node:assert (DEP0100)
npx codemod run @nodejs/process-assert-to-node-assert

What it fixes:

// Before
process.assert(condition, "Assertion failed");

// After
import assert from "node:assert";
assert(condition, "Assertion failed");

3. Manual Review Required

Crypto Module Changes

Check for:

• Key lengths < 2048 bits (RSA/DSA/DH)
• ECC keys < 224 bits
• RC4 cipher usage
• Custom OpenSSL security level configurations

# Search for potential crypto issues
grep -r "generateKeyPair\|createPrivateKey\|createPublicKey" --include="*.js" --include="*.ts"
grep -r "cipher\|RC4" --include="*.js" --include="*.ts"

Fetch API Compliance

• Stricter fetch() compliance with WHATWG standards
• AbortSignal validation changes

# Find fetch usage
grep -r "fetch(" --include="*.js" --include="*.ts"

Stream/Pipe Error Handling

• Stream errors now throw instead of emitting
• Review error handling in pipe operations

# Find stream/pipe usage
grep -r "\.pipe(\|createReadStream\|createWriteStream" --include="*.js" --include="*.ts"

Buffer Behavior Changes

• Review Buffer usage for behavioral changes

# Find Buffer operations
grep -r "Buffer\." --include="*.js" --include="*.ts"

Windows Path Handling

• Path handling fixes on Windows may affect behavior

Test Runner Defaults

• Default behavior changes in built-in test runner

4. Update Dependencies

# Update all dependencies to latest compatible versions
npm outdated
npm update

# For major version updates
npx npm-check-updates -u
npm install

5. Testing Strategy

# Install Node.js 24
nodenv local 24

# Verify version
node --version  # Should show v24.x.x

# Test in production-like environment
npm run build

# Run type checking (if using TypeScript)
npm run code-review

6. Update Configuration Files

Update package.json:

{
  "engines": {
    "node": ">=24.0.0"
  }
}

Update CI/CD pipelines (GitHub Actions example):

- uses: actions/setup-node@v4
  with:
    node-version: "24"

Update Docker files:

FROM node:24-alpine

7. Update Typescript NodeJS types

Upgrade @types/node@ to 24.x and any subsequent errors until it works.

Run npm typecheck until it succeed.

Common Issues and Solutions

Issue: Crypto Key Length Errors

Error: error:1C80006B:Provider routines::wrong final block length

Solution: Upgrade RSA/DSA keys to 2048+ bits

// Generate new key with proper length
crypto.generateKeyPair(
  "rsa",
  {
    modulusLength: 2048, // Changed from 1024
    // ...
  },
  callback,
);

Issue: Import Assertions Not Working

Error: SyntaxError: Unexpected identifier 'assert'

Solution: Run the import-assertions-to-attributes codemod

npx codemod run @nodejs/import-assertions-to-attributes

Issue: Platform Binary Not Available

Error: No pre-built binary for your platform

Solution: Either upgrade platform or build from source with appropriate compiler

Rollback Plan

If issues arise:

# Revert to Node.js 20
nodenv install 20
nodenv local 20

# Or install specific version
nodenv install 20.18.1
nodenv local 20.18.1

# Revert package.json changes
git checkout package.json package-lock.json

# Restore dependencies
npm ci

Migration Commands Quick Reference

# All codemods for v20 → v24 migration
npx codemod run @nodejs/import-assertions-to-attributes
npx codemod run @nodejs/crypto-rsa-pss-update
npx codemod run @nodejs/dirent-path-to-parent-path
npx codemod run @nodejs/fs-access-mode-constants
npx codemod run @nodejs/fs-truncate-fd-deprecation
npx codemod run @nodejs/process-assert-to-node-assert
npx codemod run @nodejs/util-is

Resources

• Node.js 22 to 24 Migration Guide
• Node.js 20 to 22 Migration Guide
• Node.js Deprecations
• Codemod Registry
• Node.js Userland Migrations

Usage Instructions for This Skill

When helping users migrate:

1. Start with assessment: Ask about current Node version, project size, and critical dependencies
2. Run codemods first: Automate as much as possible before manual changes
3. Identify breaking changes: Focus on crypto, fs, import syntax
4. Test incrementally: Encourage testing after each major change
5. Check for platform compatibility: Verify target deployment platforms are supported
6. Review dependencies: Check if all npm packages support Node.js 24
7. Provide rollback guidance: Always have a plan B

Key Questions to Ask Users

• What Node.js version are you currently running?
• Are you using crypto APIs (especially key generation)?
• Do you import JSON modules using import statements?
• Are you building from source or using pre-built binaries?
• What platforms do you need to support?
• Do you have C/C++ native addons?
• What is your test coverage like?