Skip to main content

​
What is Node.js Userland Migrations?

Node.js Userland Migrations is an official collection of automated code transformation tools (codemods) designed to help you maintain your Node.js codebase as the platform evolves. These codemods facilitate:
  • Adopting new Node.js features - Automatically update your code to use modern Node.js APIs
  • Handling breaking changes - Migrate deprecated APIs to their current equivalents
  • Maintaining code quality - Ensure your codebase stays up-to-date with Node.js best practices
This repository contains codemods for “userland” code - the application code you write, not Node.js core itself.

​
What are codemods?

Codemods are automated scripts that transform source code programmatically. Unlike simple find-and-replace operations, codemods understand the structure of your code using Abstract Syntax Trees (AST).

​
How codemods work

1

Parse your code

The codemod reads your JavaScript or TypeScript files and parses them into an Abstract Syntax Tree (AST), which represents the structure of your code.
2

Find patterns

The codemod searches for specific patterns in the AST - for example, calls to a deprecated API like util.log().
3

Transform code

When a pattern is found, the codemod applies transformations - replacing old code with new, equivalent code that uses modern APIs.
4

Generate output

The modified AST is converted back to source code and written to your files, preserving formatting and comments where possible.

​
AST-based transformations

Node.js Userland Migrations uses ast-grep and the jssg API to ensure accurate, safe transformations: 
// Before migration
const util = require('node:util');
util.log('Application started');

// After migration - codemod understands the structure
console.log(new Date().toLocaleString(), 'Application started');
The codemod correctly:
  • Identifies the util.log() call
  • Replaces it with the modern equivalent
  • Removes the unused import if util is no longer needed
  • Preserves your code style and formatting

​
Why use codemods?

Save time

Automatically transform hundreds of files in seconds instead of manually updating each one.

Reduce errors

AST-based transformations are more accurate than manual find-and-replace operations.

Handle complexity

Codemods understand different import styles, variable naming, and code patterns automatically.

Stay current

Keep your codebase updated with the latest Node.js APIs and best practices.

​
Available migrations

Node.js Userland Migrations includes 28 migration recipes covering:
  • Buffer APIs - Migrate buffer.atob(), buffer.btoa(), and SlowBuffer deprecations
  • Crypto APIs - Update crypto.fips, crypto.createCredentials(), and RSA-PSS parameters
  • File System - Migrate fs.rmdir(), fs.truncate(), and access mode constants
  • Utilities - Replace deprecated util.is*(), util.log(), util.print(), and util.extend() methods
  • Process APIs - Update process.mainModule and process.assert usages
  • Timers - Migrate deprecated timer functions like enroll(), unenroll(), and active()
  • HTTP/REPL - Fix class instantiation and update deprecated APIs
  • Import syntax - Convert import assertions to import attributes
  • TypeScript - Correct import specifiers for Node.js ESM compliance
  • And more - URL parsing, zlib, dirent, and other Node.js APIs
You can find all official Node.js codemods in the Codemod Registry.

​
Real-world example

Consider migrating deprecated util.is*() methods across your codebase: 
const util = require('node:util');

if (util.isArray(someValue)) {
  console.log('someValue is an array');
}
if (util.isBoolean(someValue)) {
  console.log('someValue is a boolean');
}
if (util.isBuffer(someValue)) {
  console.log('someValue is a buffer');
}
Running the codemod: 
npx codemod @nodejs/util-is
Transforms all deprecated util.is*() calls across your entire project in seconds.

​
Module system support

All codemods support both CommonJS and ES modules: 
const util = require('node:util');
const { log } = require('node:util');
The codemods automatically detect your import style and apply the appropriate transformations.

​
When to use codemods

When upgrading to a new Node.js version that deprecates APIs you’re using, codemods can automatically migrate your code to the new APIs.
When Node.js introduces new built-in APIs that replace third-party packages (like util.styleText replacing chalk), codemods can handle the migration.
If your application logs deprecation warnings, codemods can eliminate them by updating to the current APIs.
When you need to update patterns across dozens or hundreds of files, codemods are much faster and more reliable than manual changes.
Always commit your work before running codemods. These scripts modify source code directly, and while they’re designed to be safe, having a clean git state lets you easily review and revert changes if needed.

​
What’s next?

Quick Start

Run your first migration in minutes

Installation

Set up the Codemod CLI and learn advanced options

Browse Recipes

Explore all available migration recipes

How Codemods Work

Deep dive into the technical details

Build docs developers (and LLMs) love

Get started for freeTalk to us