Quickstart

Create your first Codemod package and run it locally.

A Codemod package is a set of files that define an automated code transformation. Codemod Packages let you create, test, and distribute reusable transformations that update source code across entire codebases.

Packages range from quick, single-file refactors to advanced, multi-step migrations. They’re fully portable—run them locally, in CI, or share with your team.

1. Create a new Codemod package

   Scaffold a new Codemod package:

   npx codemod init
   

   Each package includes your transformation logic (written in JavaScript, TypeScript, or YAML), a project manifest, and workflow specification.

   When creating a new codemod project, you’ll be prompted for:

   • Project directory
   • Codemod type:
     • JavaScript ast-grep (jssg) codemod
     • Multi-step workflow (shell command, YAML & jssg)
   • Target language
   • Project name
   • Description
   • Author
   • License type
   • If your codemod is private

   This creates a new folder with the required files and structure.

2. Explore the generated project

   An example Codemod package:

   example-codemod/
   ├── .gitignore
   ├── README.md
   ├── codemod.yaml        #  manifest and metadata
   ├── workflow.yaml       # Workflow definition for running the codemod
   ├── scripts/            # JS/TS codemods and shell scripts
   │   └── codemod.ts      # JS ast-grep codemod entry point
   └── rules/              # YAML ast-grep rule definitions
       └── config.yml
   

   You can combine different codemod types in a single package. The scripts/ and rules/ folders are conventional, not required—use any paths you prefer as long as you reference them correctly from workflow.yaml.

   Check out the Codemod package structure for more details.

3. Understand an example workflow

   The generated workflow.yaml will differ depending on the codemod type you select:

   Combined (jssg + yaml + shell + ai)

   version: "1"
   nodes:
     - id: run-all
       name: Combined Example
       type: automatic
       steps:
         # 1) JS ast-grep (jssg)
         - name: "JS ast-grep codemod"
           js-ast-grep:
             js_file: "scripts/codemod.ts"
             base_path: "."
             language: "typescript"
             include:
               - "**/*.ts"
               - "**/*.tsx"
   
         # 2) YAML ast-grep
         - name: "Apply YAML ast-grep rules"
           ast-grep:
             config_file: "rules/config.yml"
             base_path: "./src"
             include:
               - "**/*.ts"
             exclude:
               - "**/*.test.ts"
   
         # 3) AI step
         - name: "AI review"
           ai:
             prompt: |
               Summarize risky changes and suggest tests.
         
         # 4) Shell command
         - name: "Format code"
           run: npx prettier --write "**/*.{ts,tsx,js,jsx}"
   
   

   Learn more about building workflows here.

4. Validate & run your Codemod package

   npx codemod workflow validate -w workflow.yaml
   npx codemod workflow run -w workflow.yaml
   

   This will check your workflow for errors and then run it locally.

   The workflow validate command checks syntax and schema compliance, but not logical correctness. Always test with real data to ensure expected behavior.