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

1. Clone the repository

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

   npm

   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:

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
• Codemod Workflow Documentation
• Codemod Studio Documentation
• JS ast-grep (jssg) API Reference
• JS ast-grep Testing Utilities
• JS ast-grep Semantic Analysis
• ast-grep Documentation

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