Skip to main content

​
Before you begin

Critical: Codemods modify source code directly. Always commit your work before running any migration to ensure you can review and revert changes if needed.
Make sure you have:
  • Node.js installed (version 18 or higher recommended)
  • A Node.js project with code you want to migrate
  • Git initialized in your project directory

​
Your first migration

Let’s walk through running a codemod to migrate deprecated util.log() calls to the modern console.log() equivalent.
1

Commit your current work

Before running any codemod, ensure all your changes are committed to git:
git status
git add .
git commit -m "Save work before migration"
This allows you to easily review the changes made by the codemod and revert if necessary.
2

Run the codemod from the registry

Navigate to your project directory and run the migration using the Codemod CLI:
cd /path/to/your-project
npx codemod @nodejs/util-log-to-console-log
The codemod will:
  • Scan your project for JavaScript and TypeScript files
  • Find all util.log() calls
  • Transform them to console.log() with timestamps
  • Remove unused imports
✓ Found 8 files to transform
✓ Analyzing import statements
✓ Transforming util.log() calls
✓ Cleaning up unused imports

Successfully migrated 8 files!

Changes:
  - Modified: src/logger.js
  - Modified: src/utils/debug.js
  - Modified: lib/handlers.js
  ...
3

Review the changes

Use git to see exactly what changed:
git diff
You’ll see transformations like:
const util = require('node:util');

util.log('Application started');
util.log('Processing request');
4

Test your application

Run your tests to ensure everything still works correctly:
npm test
If you have integration or end-to-end tests, run those as well to verify the migration didn’t introduce any issues.
5

Commit the migration

Once you’ve verified the changes work correctly, commit them:
git add .
git commit -m "Migrate util.log() to console.log()"
The codemod automatically handles different import styles, including CommonJS require(), ES module import, destructured imports, and namespace imports.

​
Running other migrations

The process is the same for any migration recipe. Just replace the recipe name: 
npx codemod @nodejs/util-is

​
Interactive mode

By default, the Codemod CLI runs in interactive mode, allowing you to:
  • Preview changes before applying them
  • Select which files to transform
  • Skip certain transformations
To run in non-interactive mode (apply all changes automatically): 
npx codemod @nodejs/<recipe> --no-interactive
Use --no-interactive mode with caution, especially on large codebases. Always review changes after running.

​
Targeting specific files

You can target specific files or directories: 
# Target a specific directory
npx codemod @nodejs/util-is --target=src/

# Target specific files
npx codemod @nodejs/util-is --target=src/logger.js,src/utils/

​
Common migration scenarios

Replace all 15 deprecated util.is*() methods with modern alternatives:
npx codemod @nodejs/util-is
This handles:
  • util.isArray() → Array.isArray()
  • util.isBoolean() → typeof value === 'boolean'
  • util.isBuffer() → Buffer.isBuffer()
  • And 12 more methods
See the util.is* recipe documentation for details.
Convert import assertions (assert syntax) to the standardized import attributes (with syntax):
npx codemod @nodejs/import-assertions-to-attributes

import data from './data.json' assert { type: 'json' };
Node.js dropped support for import assertions in version 22.0.0, but added support for import attributes in 18.20.0.
Replace the popular chalk package with Node.js’s built-in util.styleText():
npx codemod @nodejs/chalk-to-util-styletext
This migration:
  • Converts chalk API calls to util.styleText()
  • Removes chalk from package.json dependencies
  • Handles chained styles and color combinations
Correct import specifiers to comply with Node.js ESM requirements:
npx codemod @nodejs/correct-ts-specifiers

import { helper } from './utils';
import { Config } from './config';
Node.js ESM requires explicit file extensions, even in TypeScript projects.

​
Running from source

For development or testing, you can run codemods from a local clone of the repository:
1

Clone the repository

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

Run from your project

Navigate to your project and run the workflow file directly:
cd /path/to/your-project
npx codemod workflow run -w /path/to/userland-migrations/recipes/<recipe>/workflow.yaml
For example:
npx codemod workflow run -w /path/to/userland-migrations/recipes/util-log-to-console-log/workflow.yaml

​
Troubleshooting

If the codemod reports no files were transformed:
  • Verify your code actually uses the deprecated API
  • Check that your files are in the default search paths (**/*.js, **/*.ts, etc.)
  • Ensure files aren’t in node_modules/ (excluded by default)
  • Try running with --verbose to see detailed output
Codemods may skip certain patterns if:
  • The code is too complex to safely transform
  • The API is used in an uncommon way
  • Manual intervention is required
Review skipped files and update them manually, referring to the recipe documentation for guidance.
If your build or tests fail:
  1. Review the git diff carefully
  2. Check for any edge cases the codemod didn’t handle
  3. Verify that the new API is available in your Node.js version
  4. If needed, revert with git reset --hard HEAD~1 and file an issue

​
Best practices

Run one migration at a time

Don’t run multiple migrations simultaneously. Complete, test, and commit each migration before starting the next.

Review all changes

Always review the git diff before committing. Look for unexpected changes or edge cases.

Test thoroughly

Run your full test suite, including integration tests, after each migration.

Keep backups

Even with git, consider keeping a backup of critical files before large migrations.

​
What’s next?

Installation

Learn about advanced installation options and configuration

Browse Recipes

Explore all available migration recipes

How Codemods Work

Understand the technical details behind codemods

Contributing

Create your own migration recipes

Build docs developers (and LLMs) love

Get started for freeTalk to us