> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nodejs/userland-migrations/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Learn about Node.js Userland Migrations and how codemods can automate your code transformations

## 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

<Note>
  This repository contains codemods for "userland" code - the application code you write, not Node.js core itself.
</Note>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Find patterns">
    The codemod searches for specific patterns in the AST - for example, calls to a deprecated API like `util.log()`.
  </Step>

  <Step title="Transform code">
    When a pattern is found, the codemod applies transformations - replacing old code with new, equivalent code that uses modern APIs.
  </Step>

  <Step title="Generate output">
    The modified AST is converted back to source code and written to your files, preserving formatting and comments where possible.
  </Step>
</Steps>

### AST-based transformations

Node.js Userland Migrations uses [ast-grep](https://ast-grep.github.io/) and the jssg API to ensure accurate, safe transformations:

```javascript theme={null}
// 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?

<CardGroup cols={2}>
  <Card title="Save time" icon="clock">
    Automatically transform hundreds of files in seconds instead of manually updating each one.
  </Card>

  <Card title="Reduce errors" icon="shield-check">
    AST-based transformations are more accurate than manual find-and-replace operations.
  </Card>

  <Card title="Handle complexity" icon="diagram-project">
    Codemods understand different import styles, variable naming, and code patterns automatically.
  </Card>

  <Card title="Stay current" icon="arrow-trend-up">
    Keep your codebase updated with the latest Node.js APIs and best practices.
  </Card>
</CardGroup>

## 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](https://codemod.link/nodejs-official).

## Real-world example

Consider migrating deprecated `util.is*()` methods across your codebase:

<CodeGroup>
  ```javascript Before theme={null}
  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');
  }
  ```

  ```javascript After theme={null}
  if (Array.isArray(someValue)) {
    console.log('someValue is an array');
  }
  if (typeof someValue === 'boolean') {
    console.log('someValue is a boolean');
  }
  if (Buffer.isBuffer(someValue)) {
    console.log('someValue is a buffer');
  }
  ```
</CodeGroup>

Running the codemod:

```bash theme={null}
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:

<CodeGroup>
  ```javascript CommonJS theme={null}
  const util = require('node:util');
  const { log } = require('node:util');
  ```

  ```javascript ES Modules theme={null}
  import util from 'node:util';
  import { log } from 'node:util';
  ```
</CodeGroup>

The codemods automatically detect your import style and apply the appropriate transformations.

## When to use codemods

<AccordionGroup>
  <Accordion title="Upgrading Node.js versions">
    When upgrading to a new Node.js version that deprecates APIs you're using, codemods can automatically migrate your code to the new APIs.
  </Accordion>

  <Accordion title="Adopting new features">
    When Node.js introduces new built-in APIs that replace third-party packages (like util.styleText replacing chalk), codemods can handle the migration.
  </Accordion>

  <Accordion title="Cleaning up deprecation warnings">
    If your application logs deprecation warnings, codemods can eliminate them by updating to the current APIs.
  </Accordion>

  <Accordion title="Large-scale refactoring">
    When you need to update patterns across dozens or hundreds of files, codemods are much faster and more reliable than manual changes.
  </Accordion>
</AccordionGroup>

<Warning>
  **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.
</Warning>

## What's next?

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Run your first migration in minutes
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Set up the Codemod CLI and learn advanced options
  </Card>

  <Card title="Browse Recipes" icon="book" href="/recipes/overview">
    Explore all available migration recipes
  </Card>

  <Card title="How Codemods Work" icon="gears" href="/concepts/how-codemods-work">
    Deep dive into the technical details
  </Card>
</CardGroup>