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

# 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](https://go.codemod.com/cli-docs) 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:

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

<Note>
  The first run may take a few seconds while `npx` downloads the Codemod CLI. Subsequent runs are faster.
</Note>

### Global installation (optional)

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

```bash theme={null}
npm install -g codemod
```

Then run codemods without `npx`:

```bash theme={null}
codemod @nodejs/<recipe>
```

### Verifying installation

Check that the Codemod CLI is available:

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

```bash theme={null}
node --version
npm --version
```

### Git

While not strictly required, git is strongly recommended:

```bash theme={null}
git --version
```

Git allows you to:

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

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

## Project setup

### Running in an existing project

To run codemods in your project:

<Steps>
  <Step title="Navigate to your project directory">
    ```bash theme={null}
    cd /path/to/your-project
    ```
  </Step>

  <Step title="Ensure a clean git state">
    ```bash theme={null}
    git status
    ```

    If you have uncommitted changes, commit them:

    ```bash theme={null}
    git add .
    git commit -m "Save work before migration"
    ```
  </Step>

  <Step title="Run the codemod">
    ```bash theme={null}
    npx codemod @nodejs/<recipe>
    ```

    The CLI will scan your project and apply transformations to JavaScript and TypeScript files.
  </Step>
</Steps>

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

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

<Accordion title="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`                                                           |
</Accordion>

### Command-line options

Override configuration with command-line flags:

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

<CodeGroup>
  ```bash Target specific directory theme={null}
  npx codemod @nodejs/util-is --target=src/
  ```

  ```bash Target multiple paths theme={null}
  npx codemod @nodejs/util-is --target=src/,lib/
  ```

  ```bash Non-interactive mode theme={null}
  npx codemod @nodejs/util-is --no-interactive
  ```

  ```bash Dry run theme={null}
  npx codemod @nodejs/util-is --dry-run
  ```
</CodeGroup>

## Development setup

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

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

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```

    This installs dependencies for all recipes (the project uses npm workspaces).
  </Step>

  <Step title="Run tests">
    ```bash theme={null}
    npm test
    ```

    This runs tests for all recipes.
  </Step>

  <Step title="Run a codemod from source">
    Navigate to your project and run a workflow file:

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

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

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

```yaml .github/workflows/migrate.yml theme={null}
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'
```

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

### Running in other CI systems

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

<CodeGroup>
  ```yaml GitLab CI theme={null}
  migrate:
    stage: transform
    image: node:20
    script:
      - npx codemod @nodejs/util-is --no-interactive
    only:
      - schedules
  ```

  ```yaml Azure Pipelines theme={null}
  steps:
    - task: NodeTool@0
      inputs:
        versionSpec: '20.x'
    - script: npx codemod @nodejs/util-is --no-interactive
      displayName: 'Run migration'
  ```

  ```groovy Jenkins theme={null}
  pipeline {
    agent any
    stages {
      stage('Migrate') {
        steps {
          sh 'npx codemod @nodejs/util-is --no-interactive'
        }
      }
    }
  }
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="Permission denied errors">
    On Unix systems, you may need to adjust permissions:

    ```bash theme={null}
    # Fix npm global permissions
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Out of memory errors">
    For large codebases, you may need to increase Node.js memory:

    ```bash theme={null}
    export NODE_OPTIONS="--max-old-space-size=4096"
    npx codemod @nodejs/<recipe>
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Useful resources

<CardGroup cols={2}>
  <Card title="Codemod CLI Reference" icon="terminal" href="https://docs.codemod.com/cli/cli-reference">
    Complete CLI documentation and command reference
  </Card>

  <Card title="Workflow Documentation" icon="diagram-project" href="https://docs.codemod.com/cli/workflows">
    Learn about workflow files and multi-step migrations
  </Card>

  <Card title="Codemod Studio" icon="pencil" href="https://docs.codemod.com/codemod-studio">
    Interactive environment for developing codemods
  </Card>

  <Card title="jssg API Reference" icon="code" href="https://docs.codemod.com/jssg/reference">
    JavaScript AST manipulation API documentation
  </Card>
</CardGroup>

## What's next?

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Run your first migration
  </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
  </Card>

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