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

# Contributing Overview

> Get started contributing to Node.js Userland Migrations

Thank you for your interest in contributing to Node.js Userland Migrations! We value contributions from the community and want to make the process as smooth as possible.

## Prerequisites

Before you begin, ensure you have current versions of:

* Node.js
* npm

## Project Structure

Our codebase is organized as a monorepo using npm workspaces:

```
userland-migrations/
├── .github/          # GitHub workflows and issue templates
├── recipes/          # All codemods (each in its own directory)
└── utils/            # Shared utility functions and ast-grep helpers
```

### Recipe Structure

Each recipe resides in `recipes/<recipe-name>/` with the following structure:

```
recipes/tmpdir-to-tmpdir/
├── README.md         # Description and usage examples
├── package.json      # Package manifest
├── codemod.yaml      # Codemod metadata
├── workflow.yaml     # Workflow definition
├── src/
│   └── workflow.ts   # Main transformation logic
├── tests/
│   ├── input/        # Test input files
│   └── expected/     # Expected output files
└── tsconfig.json     # TypeScript configuration
```

## Development Setup

<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">
    <CodeGroup>
      ```bash npm theme={null}
      npm install
      ```

      ```bash pnpm theme={null}
      pnpm install
      ```

      ```bash yarn theme={null}
      yarn install
      ```
    </CodeGroup>
  </Step>

  <Step title="Run tests">
    Verify your setup by running the test suite:

    ```bash theme={null}
    npm test
    ```
  </Step>
</Steps>

## Available Scripts

The project provides several npm scripts for development:

| Script         | Command              | Description                            |
| -------------- | -------------------- | -------------------------------------- |
| **lint**       | `npm run lint`       | Check code for linting issues          |
| **lint:fix**   | `npm run lint:fix`   | Fix linting issues automatically       |
| **type-check** | `npm run type-check` | Run TypeScript type checking           |
| **test**       | `npm test`           | Run all tests across workspaces        |
| **pre-commit** | `npm run pre-commit` | Run full check suite before committing |

## Shared Utilities

The `utils/` workspace provides helpful utilities for building codemods:

* **Import utilities**: `getNodeImportStatements()`, `getNodeImportCalls()`
* **Require utilities**: `getNodeRequireCalls()`
* **Binding resolution**: `resolveBindingPath()`, `removeBinding()`
* **Code cleanup**: `removeLines()`

These utilities simplify common transformation patterns and handle edge cases.

## Useful Resources

* [Codemod CLI Reference](https://docs.codemod.com/cli/cli-reference)
* [Codemod Workflow Documentation](https://docs.codemod.com/cli/workflows)
* [Codemod Studio Documentation](https://docs.codemod.com/codemod-studio)
* [JS ast-grep (jssg) API Reference](https://docs.codemod.com/jssg/reference)
* [JS ast-grep Testing Utilities](https://docs.codemod.com/jssg/testing)
* [JS ast-grep Semantic Analysis](https://docs.codemod.com/jssg/semantic-analysis)
* [ast-grep Documentation](https://ast-grep.github.io/)

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Recipes" icon="wand-magic-sparkles" href="/contributing/creating-recipes">
    Learn how to create new migration recipes
  </Card>

  <Card title="Testing" icon="flask" href="/contributing/testing">
    Understand testing requirements and best practices
  </Card>

  <Card title="Development Workflow" icon="code-branch" href="/contributing/workflow">
    Follow our development and PR process
  </Card>
</CardGroup>