Installation & Setup

Codemod CLI

Node.js Userland Migrations uses the Codemod CLI to run migration recipes. You don’t need to install anything globally - the CLI can be run directly with npx.

Running with npx (recommended)

The simplest way to run codemods is using npx, which downloads and executes the CLI automatically:

npx codemod @nodejs/<recipe>

This approach:

Requires no installation
Always uses the latest version of the CLI
Works in CI/CD environments
Doesn’t pollute your global npm packages

The first run may take a few seconds while npx downloads the Codemod CLI. Subsequent runs are faster.

Global installation (optional)

If you run codemods frequently, you can install the CLI globally:

npm install -g codemod

Then run codemods without npx:

codemod @nodejs/<recipe>

Verifying installation

Check that the Codemod CLI is available:

npx codemod --version

You should see the version number:

codemod version 1.x.x

Prerequisites

Node.js version

Node.js Userland Migrations requires:

Node.js 18.0.0 or higher (recommended: latest LTS version)
npm 8.0.0 or higher

Check your versions:

node --version
npm --version

Git

While not strictly required, git is strongly recommended:

git --version

Git allows you to:

Review changes with git diff
Revert migrations with git reset
Track migration history in your repository

Always ensure you have a clean git state (all changes committed) before running codemods.

Project setup

Running in an existing project

To run codemods in your project:

Navigate to your project directory

cd /path/to/your-project

Ensure a clean git state

git status

If you have uncommitted changes, commit them:

git add .
git commit -m "Save work before migration"

Run the codemod

npx codemod @nodejs/<recipe>

The CLI will scan your project and apply transformations to JavaScript and TypeScript files.

File types supported

Codemods automatically process these file types:

**/*.js - JavaScript files
**/*.jsx - React JSX files
**/*.ts - TypeScript files
**/*.tsx - TypeScript React files
**/*.mjs - ES module files
**/*.cjs - CommonJS module files
**/*.mts - TypeScript ES module files
**/*.cts - TypeScript CommonJS files

Files excluded by default

The following directories are automatically excluded:

**/node_modules/** - Dependencies
**/dist/** - Build output
**/build/** - Build output
**/.git/** - Git repository data
**/coverage/** - Test coverage reports

Configuration

Codemod CLI configuration

You can configure the Codemod CLI behavior with a .codemodrc.json file in your project root:

{
  "include": ["src/**/*.ts", "lib/**/*.js"],
  "exclude": ["src/legacy/**"],
  "extensions": [".ts", ".js"],
  "interactive": true
}

Configuration options

Option	Description	Default
`include`	Glob patterns for files to process	`*/.{js,jsx,ts,tsx,mjs,cjs,mts,cts}`
`exclude`	Glob patterns for files to skip	`/node_modules/`
`extensions`	File extensions to process	`[".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"]`
`interactive`	Enable interactive mode	`true`

Command-line options

Override configuration with command-line flags:

# Target specific files or directories
npx codemod @nodejs/<recipe> --target=src/

# Non-interactive mode (apply all changes)
npx codemod @nodejs/<recipe> --no-interactive

# Dry run (preview changes without applying)
npx codemod @nodejs/<recipe> --dry-run

# Verbose output
npx codemod @nodejs/<recipe> --verbose

npx codemod @nodejs/util-is --target=src/

Development setup

If you want to contribute to Node.js Userland Migrations or run codemods from source:

Clone the repository

git clone https://github.com/nodejs/userland-migrations.git
cd userland-migrations

Install dependencies

npm install

This installs dependencies for all recipes (the project uses npm workspaces).

Run tests

npm test

This runs tests for all recipes.

Run a codemod from source

Navigate to your project and run a workflow file:

cd /path/to/your-project
npx codemod workflow run -w /path/to/userland-migrations/recipes/<recipe>/workflow.yaml

Project structure

The repository is organized as follows:

userland-migrations/
├── recipes/              # All migration recipes
│   ├── util-is/         # Example recipe
│   │   ├── README.md
│   │   ├── package.json
│   │   ├── workflow.yaml
│   │   ├── codemod.yml
│   │   ├── src/
│   │   │   └── workflow.ts
│   │   └── tests/
│   ├── buffer-atob-btoa/
│   ├── import-assertions-to-attributes/
│   └── ...
├── utils/               # Shared utilities
│   └── codemod-utils/   # AST manipulation helpers
└── package.json         # Workspace root

Running recipe tests

Test a specific recipe:

# Test one recipe
npm test --workspace=recipes/util-is

# Run all tests
npm test

# Type check
npm run type-check

# Lint
npm run lint

CI/CD integration

Running in GitHub Actions

You can run codemods in CI to validate migrations or apply them automatically:

.github/workflows/migrate.yml

name: Apply Node.js Migrations

on:
  workflow_dispatch:

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run migration
        run: npx codemod @nodejs/util-is --no-interactive

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        with:
          commit-message: 'chore: migrate util.is* methods'
          title: 'Automated migration: util.is* methods'
          body: 'This PR applies the @nodejs/util-is codemod to update deprecated util methods.'
          branch: 'migrate/util-is'

Always test migrations locally before running them in CI. Use --dry-run mode first to verify expected changes.

Running in other CI systems

The same approach works in any CI system that supports Node.js:

migrate:
  stage: transform
  image: node:20
  script:
    - npx codemod @nodejs/util-is --no-interactive
  only:
    - schedules

Troubleshooting

Command not found: codemod

If you get a “command not found” error:

Ensure you’re using npx codemod not just codemod
If using global installation, reinstall: npm install -g codemod
Check your PATH includes npm global binaries: npm config get prefix

Permission denied errors

On Unix systems, you may need to adjust permissions:

# Fix npm global permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Out of memory errors

For large codebases, you may need to increase Node.js memory:

export NODE_OPTIONS="--max-old-space-size=4096"
npx codemod @nodejs/<recipe>

npx is slow

The first npx run downloads the CLI. To speed up subsequent runs:

Install globally: npm install -g codemod
Or use npm cache: npx will cache the package after first use

Useful resources

Codemod CLI Reference

Complete CLI documentation and command reference

Workflow Documentation

Learn about workflow files and multi-step migrations

Codemod Studio

Interactive environment for developing codemods

jssg API Reference

JavaScript AST manipulation API documentation

What’s next?

Quick Start

Run your first migration

Browse Recipes

Explore all available migration recipes

How Codemods Work

Understand the technical details

Contributing

Create your own migration recipes

Get Started

Migration Recipes

Core Concepts

Codemod CLI

Running with npx (recommended)

Global installation (optional)

Verifying installation

Prerequisites

Node.js version

Git

Project setup

Running in an existing project

File types supported

Files excluded by default

Configuration

Codemod CLI configuration

Command-line options

Development setup

Project structure

Running recipe tests

CI/CD integration

Running in GitHub Actions

Running in other CI systems

Troubleshooting

Useful resources

Codemod CLI Reference

Workflow Documentation

Codemod Studio

jssg API Reference

What’s next?

Quick Start

Browse Recipes

How Codemods Work

Contributing

Build docs developers (and LLMs) love

Get Started

Migration Recipes

Core Concepts

​Codemod CLI

​Running with npx (recommended)

​Global installation (optional)

​Verifying installation

​Prerequisites

​Node.js version

​Git

​Project setup

​Running in an existing project

​File types supported

​Files excluded by default

​Configuration

​Codemod CLI configuration

​Command-line options

​Development setup

​Project structure

​Running recipe tests

​CI/CD integration

​Running in GitHub Actions

​Running in other CI systems

​Troubleshooting

​Useful resources

Codemod CLI Reference

Workflow Documentation

Codemod Studio

jssg API Reference

​What’s next?

Quick Start

Browse Recipes

How Codemods Work

Contributing

Build docs developers (and LLMs) love

Codemod CLI

Running with npx (recommended)

Global installation (optional)

Verifying installation

Prerequisites

Node.js version

Git

Project setup

Running in an existing project

File types supported

Files excluded by default

Configuration

Codemod CLI configuration

Command-line options

Development setup

Project structure

Running recipe tests

CI/CD integration

Running in GitHub Actions

Running in other CI systems

Troubleshooting

Useful resources

What’s next?