Installation & Setup

Install the Codemod CLI and configure your environment for running Node.js migrations

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:

1. Navigate to your project directory

   cd /path/to/your-project
   
2. Ensure a clean git state

   git status
   

   If you have uncommitted changes, commit them:

   git add .
   git commit -m "Save work before migration"
   
3. 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

Target specific directory

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

Development setup

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

1. Clone the repository

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

   npm install
   

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

3. Run tests

   npm test
   

   This runs tests for all recipes.

4. 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:

GitLab CI

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