Skip to main content
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

1

Clone the repository

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

Install dependencies

npm install
3

Run tests

Verify your setup by running the test suite:
npm test

​
Available Scripts

The project provides several npm scripts for development:
ScriptCommandDescription
lintnpm run lintCheck code for linting issues
lint:fixnpm run lint:fixFix linting issues automatically
type-checknpm run type-checkRun TypeScript type checking
testnpm testRun all tests across workspaces
pre-commitnpm run pre-commitRun 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

​
Next Steps

Creating Recipes

Learn how to create new migration recipes

Testing

Understand testing requirements and best practices

Development Workflow

Follow our development and PR process

Build docs developers (and LLMs) love

Get started for freeTalk to us