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

# Quick Start

> Run your first Node.js migration in minutes with step-by-step instructions

## Before you begin

<Warning>
  **Critical:** Codemods modify source code directly. Always commit your work before running any migration to ensure you can review and revert changes if needed.
</Warning>

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.

<Steps>
  <Step title="Commit your current work">
    Before running any codemod, ensure all your changes are committed to git:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Run the codemod from the registry">
    Navigate to your project directory and run the migration using the Codemod CLI:

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

    <Accordion title="Example output">
      ```
      ✓ 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
        ...
      ```
    </Accordion>
  </Step>

  <Step title="Review the changes">
    Use git to see exactly what changed:

    ```bash theme={null}
    git diff
    ```

    You'll see transformations like:

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

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

      ```javascript After theme={null}
      console.log(new Date().toLocaleString(), 'Application started');
      console.log(new Date().toLocaleString(), 'Processing request');
      ```
    </CodeGroup>
  </Step>

  <Step title="Test your application">
    Run your tests to ensure everything still works correctly:

    ```bash theme={null}
    npm test
    ```

    If you have integration or end-to-end tests, run those as well to verify the migration didn't introduce any issues.
  </Step>

  <Step title="Commit the migration">
    Once you've verified the changes work correctly, commit them:

    ```bash theme={null}
    git add .
    git commit -m "Migrate util.log() to console.log()"
    ```
  </Step>
</Steps>

<Note>
  The codemod automatically handles different import styles, including CommonJS `require()`, ES module `import`, destructured imports, and namespace imports.
</Note>

## Running other migrations

The process is the same for any migration recipe. Just replace the recipe name:

<CodeGroup>
  ```bash Util.is* methods theme={null}
  npx codemod @nodejs/util-is
  ```

  ```bash Buffer APIs theme={null}
  npx codemod @nodejs/buffer-atob-btoa
  ```

  ```bash Import assertions to attributes theme={null}
  npx codemod @nodejs/import-assertions-to-attributes
  ```

  ```bash Crypto FIPS theme={null}
  npx codemod @nodejs/crypto-fips-to-getFips
  ```

  ```bash File system rmdir theme={null}
  npx codemod @nodejs/rmdir
  ```
</CodeGroup>

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

```bash theme={null}
npx codemod @nodejs/<recipe> --no-interactive
```

<Warning>
  Use `--no-interactive` mode with caution, especially on large codebases. Always review changes after running.
</Warning>

## Targeting specific files

You can target specific files or directories:

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

<AccordionGroup>
  <Accordion title="Migrating deprecated util.is* methods">
    Replace all 15 deprecated `util.is*()` methods with modern alternatives:

    ```bash theme={null}
    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](/recipes/util-is) for details.
  </Accordion>

  <Accordion title="Updating import assertions to attributes">
    Convert import assertions (`assert` syntax) to the standardized import attributes (`with` syntax):

    ```bash theme={null}
    npx codemod @nodejs/import-assertions-to-attributes
    ```

    <CodeGroup>
      ```typescript Before theme={null}
      import data from './data.json' assert { type: 'json' };
      ```

      ```typescript After theme={null}
      import data from './data.json' with { type: 'json' };
      ```
    </CodeGroup>

    Node.js dropped support for import assertions in version 22.0.0, but added support for import attributes in 18.20.0.
  </Accordion>

  <Accordion title="Migrating chalk to util.styleText">
    Replace the popular chalk package with Node.js's built-in `util.styleText()`:

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

  <Accordion title="Fixing TypeScript import specifiers">
    Correct import specifiers to comply with Node.js ESM requirements:

    ```bash theme={null}
    npx codemod @nodejs/correct-ts-specifiers
    ```

    <CodeGroup>
      ```typescript Before theme={null}
      import { helper } from './utils';
      import { Config } from './config';
      ```

      ```typescript After theme={null}
      import { helper } from './utils.js';
      import { Config } from './config.js';
      ```
    </CodeGroup>

    Node.js ESM requires explicit file extensions, even in TypeScript projects.
  </Accordion>
</AccordionGroup>

## Running from source

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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/nodejs/userland-migrations.git
    cd userland-migrations
    ```
  </Step>

  <Step title="Run from your project">
    Navigate to your project and run the workflow file directly:

    ```bash theme={null}
    cd /path/to/your-project
    npx codemod workflow run -w /path/to/userland-migrations/recipes/<recipe>/workflow.yaml
    ```

    For example:

    ```bash theme={null}
    npx codemod workflow run -w /path/to/userland-migrations/recipes/util-log-to-console-log/workflow.yaml
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No files were transformed">
    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
  </Accordion>

  <Accordion title="Some transformations were skipped">
    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.
  </Accordion>

  <Accordion title="Build or tests fail after migration">
    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
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup cols={2}>
  <Card title="Run one migration at a time" icon="list-check">
    Don't run multiple migrations simultaneously. Complete, test, and commit each migration before starting the next.
  </Card>

  <Card title="Review all changes" icon="magnifying-glass">
    Always review the git diff before committing. Look for unexpected changes or edge cases.
  </Card>

  <Card title="Test thoroughly" icon="vial">
    Run your full test suite, including integration tests, after each migration.
  </Card>

  <Card title="Keep backups" icon="floppy-disk">
    Even with git, consider keeping a backup of critical files before large migrations.
  </Card>
</CardGroup>

## What's next?

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Learn about advanced installation options and configuration
  </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">
    Understand the technical details behind codemods
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/contributing/overview">
    Create your own migration recipes
  </Card>
</CardGroup>