Node.js 22 LTS: What's New and How to Migrate

Node.js 22 LTS: What’s New and How to Migrate

Node.js 22 recently transitioned to Long-Term Support (LTS) status, marking a significant milestone for production deployments. This release brings native WebSocket support, enhanced diagnostics tools, and performance improvements that make it worth upgrading for most teams. If you’re still on Node 20 or earlier, understanding what’s changed will help you plan a smooth migration.

In this guide, we’ll cover the major features, breaking changes, and practical migration steps for developers and DevOps engineers.

What’s New in Node.js 22

Native WebSocket Support

One of the most anticipated features is the addition of native WebSocket support via the WebSocket global. Previously, developers had to rely on third-party libraries like ws or socket.io. Node.js 22 ships with a built-in, standards-compliant WebSocket implementation.

// Before (Node < 22): Require third-party library
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

// Node.js 22: Use global WebSocket
const server = new WebSocketServer({ port: 8080 });

server.on('connection', (socket) => {
  console.log('Client connected');
  
  socket.on('message', (data) => {
    console.log('Received:', data);
    socket.send(`Echo: ${data}`);
  });
  
  socket.on('close', () => {
    console.log('Client disconnected');
  });
});

This native implementation reduces dependencies and improves startup performance, which is critical for serverless deployments and container-based architectures.

Enhanced Diagnostics and Observability

Node.js 22 introduces improvements to the diagnostics subsystem, including better support for async hooks and enhanced tracing capabilities. The new --trace-env-vars flag allows you to trace environment variable reads, useful for debugging configuration issues.

# Trace environment variable access
node --trace-env-vars app.js

# Enable diagnostic tracing with custom categories
node --trace-events-enabled --trace-event-categories v8,node.fs app.js

These diagnostics generate detailed trace files that you can analyze with Chrome DevTools or the Node.js trace processor:

// Enable async resource tracking
const { AsyncLocalStorage } = require('async_hooks');
const asyncLocalStorage = new AsyncLocalStorage();

// Use in request handlers for better debugging
asyncLocalStorage.run({ requestId: '123' }, () => {
  // Your handler code here
});

Performance Improvements

Node.js 22 includes updates to the V8 JavaScript engine and optimizations to the event loop. The most notable improvements:

• Faster module loading: CommonJS and ES modules load 10-15% faster
• Optimized string operations: Improvements to string handling in the engine
• Better memory management: Reduced memory footprint for long-running processes

Breaking Changes and Deprecations

Deprecated APIs Being Removed

Several APIs deprecated in earlier versions are now removed or moved to legacy status:

// REMOVED: crypto.createCipher() — use crypto.createCipheriv()
const crypto = require('crypto');

// ❌ This will throw an error in Node 22
// const cipher = crypto.createCipher('aes192', 'password');

// ✅ Use this instead
const key = crypto.scryptSync('password', 'salt', 32);
const iv = crypto.randomBytes(16);
const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);

Module Loading Behavior Changes

ES modules and CommonJS interoperability has been refined:

• package.json exports field is now strictly enforced
• Conditional exports (e.g., "development" vs "production") work more consistently
• Dual package hazard warnings are clearer

{
  "name": "my-package",
  "version": "1.0.0",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  }
}

Step-by-Step Migration Guide

1. Audit Your Dependencies

Before upgrading, check if your dependencies support Node 22:

# Check npm for Node 22 compatibility
npm view npm engines.node
npm outdated

# Use npm ci with --legacy-peer-deps if needed
npm ci --legacy-peer-deps

You can also use a dedicated service to check compatibility across your entire dependency tree. Review your package-lock.json and test locally with Node 22.

2. Update Your Development Environment

Use a version manager like nvm, fnm, or asdf to test Node 22 safely:

# Using nvm
nvm install 22
nvm use 22
node --version  # v22.x.x

# Using fnm
fnm use 22
fnm default 22

Update your CI/CD pipelines to test against Node 22:

# GitHub Actions example
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20.x, 22.x]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test
      - run: npm run lint

3. Test Your Application

Run your full test suite against Node 22:

# Run tests
npm test

# Run linting
npm run lint

# Build your application
npm run build

# Test in production-like environment
docker build --build-arg NODE_VERSION=22 .

Pay special attention to:

• Native addons (compiled modules)
• Security-sensitive code (crypto, authentication)
• Long-running processes (potential memory leaks)

4. Update Docker Images

If you use Docker, update your base image:

# Old
FROM node:20-alpine

# New
FROM node:22-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .

EXPOSE 3000
CMD ["node", "server.js"]

5. Deploy Gradually

For production systems, use a canary or blue-green deployment:

# Deploy to 10% of traffic first
kubectl set image deployment/app app=myapp:node22 --record
kubectl rollout status deployment/app

# Monitor metrics
kubectl logs -f deployment/app
kubectl top pods

Common Pitfalls

Native Module Incompatibility

If your app uses native modules (modules with .node binaries), they may need recompilation:

# Rebuild all native modules
npm rebuild

# Or for specific modules
npm rebuild bcrypt sqlite3

Older Dependency Versions

Some older libraries haven’t been updated to support Node 22. If you encounter issues:

# Check if there's a newer version
npm view package-name versions

# Force installation (use cautiously)
npm install package-name@latest --save

Environment Variable Access

Changes to how environment variables are accessed may affect startup scripts:

// Be explicit about .env file loading
require('dotenv').config();

const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) {
  throw new Error('DATABASE_URL environment variable not set');
}

Why Node.js 22 LTS Matters

Long-Term Support Guarantee

LTS releases receive security updates and bug fixes for 18 months, then an additional 12 months of maintenance support. This gives you stability for production systems.

Cost Savings

The performance improvements (10-15% faster module loading, optimized string handling) translate to:

• Reduced Lambda execution time and costs
• Lower CPU usage in container deployments
• Faster startup for serverless workloads

Reduced Dependencies

Native WebSocket support means you can remove the ws or socket.io packages from new projects, reducing your attack surface and maintenance burden.

Testing Your API Integrations

If you’re building APIs with Node.js 22, use Kloubot’s API Request Builder to test your endpoints after migration. This helps verify that your authentication tokens and request payloads still work correctly.

For JWT-based authentication, the JWT Decoder tool is helpful for debugging token issues that might arise from timing or encoding changes.

Monitoring and Validation

After migration, monitor these metrics:

// Simple health check endpoint
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    uptime: process.uptime(),
    memory: process.memoryUsage(),
    nodeVersion: process.version
  });
});

Use Kloubot’s Webhook Tester to capture and inspect the actual requests your application sends, especially useful when debugging integration issues post-migration.

Conclusion

Node.js 22 LTS is a solid upgrade path with meaningful performance improvements and reduced dependency overhead. The migration process is straightforward for most applications:

1. Update your local environment and CI/CD
2. Run your full test suite
3. Deploy gradually to production
4. Monitor and collect metrics

The native WebSocket support and enhanced diagnostics make it worth prioritizing in your roadmap, particularly for new projects or services nearing major releases.

Start testing with Node 22 today, and plan your migration timeline based on your dependency status and release cycle.