Skip to main content
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:
  • 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:
Comprehensive workflow with all 5 step types: jssg, ai, yaml, registry, shell
version: "1"
nodes:
  - id: migrate-analytics
    name: Migrate legacy analytics to analytics.track({ event, properties })
    type: automatic
    steps:
      # 1) Codemod Registry: do the broad, well-defined baseline migration first
      - name: "Run registry codemod: legacy analytics -> analytics.track"
        codemod:
          source: "@codemod/migrate-analytics-v2"
          args:
            - "legacy-analytics"
            - "analytics-v2"

      # 2) JS ast-grep (jssg): handle higher-signal project-specific patterns
      - name: "Project-specific TS codemod (wrappers + key normalization)"
        js-ast-grep:
          js_file: "scripts/codemods/migrate-analytics-wrappers.ts"
          language: "typescript"
          include:
            - "src/**/*.{ts,tsx}"
          exclude:
            - "**/*.test.ts"

      # 3) AI step: transform the hard cases the rules miss
      - name: "AI fixups: dynamic calls + edge cases -> analytics.track object form"
        ai:
          prompt: |
            You are performing a code migration. Modify files directly.

            Goal:
            Convert any remaining legacy analytics calls into:
              analytics.track({ event: <string>, properties: <object> })

            Handle these hard cases:
            1) Dynamic event names: trackEvent(getName(), props)
              - Preserve semantics. event should become getName().
            2) Non-object props: trackEvent("X", foo)
              - Convert to properties: foo if foo is object-like, otherwise { value: foo }.

            Constraints:
            - Keep formatting roughly intact (prettier will run later).
            - If you are unsure about a transformation, add a TODO comment right above it explaining why.

      # 4) YAML ast-grep: clean up simple leftovers consistently (fast + deterministic)
      - name: "Apply cleanup rules (YAML ast-grep)"
        ast-grep:
          config_file: "rules/analytics_cleanup.yml"
          include:
            - "src/**/*.{ts,tsx,js,jsx}"
          exclude:
            - "**/*.test.*"

      # 5) Shell command: format after all transformations
      - name: "Format code"
        run: npx prettier --write "src/**/*.{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.