Skip to main content
This guide walks you through creating, testing, and publishing a codemod from scratch. You’ll scaffold a project, build a multi-step workflow using Codemod MCP in your IDE, and publish it to the registry.

​
1. Scaffold your project

Run the interactive scaffolder to create a new codemod package: 
npx codemod@latest init
You’ll be prompted for a codemod type (JSSG or multi-step workflow), target language, project name, and other details.
codemod init can also set up a monorepo to host multiple codemods with shared GitHub Actions for automated publishing. See CLI reference for all available options.

​
2. Install Codemod MCP

Codemod MCP gives your AI assistant tools for AST analysis, codemod creation, and testing, directly in your IDE. Add the following to your IDE’s MCP configuration: 
{
  "mcpServers": {
    "codemod": {
      "command": "npx",
      "args": ["codemod@latest", "mcp"]
    }
  }
}

​
3. Build your codemod

With MCP installed, ask your AI assistant to create a codemod. Be specific about the transformation you need:

Extract React components from inside other components to module scope to prevent re-creation on render.

CursorOpen in Cursor

Prompting tips

Tips for writing effective prompts and getting the most out of MCP.
 The AI will use MCP tools to analyze your code, generate the transform script, and set up the package. You’ll get a complete Codemod package:
my-codemod
codemod.yaml
workflow.yaml
scripts
codemod.ts
tests
fixtures
input.tsx
expected.tsx
schema_version: "1.0"

name: "extract-inner-components"
version: "0.1.0"
description: "Move React components defined inside other components to module scope"
author: "Your Name <you@example.com>"
license: "MIT"
workflow: "workflow.yaml"

targets:
  languages: ["tsx"]

keywords: ["react", "performance", "components"]

registry:
  access: "public"
  visibility: "public"

capabilities: []

​
4. Validate and test

Validate the workflow schema: 
npx codemod@latest workflow validate -w workflow.yaml
Run tests against your input/expected fixtures: 
npx codemod jssg test ./scripts/codemod.ts --language tsx
Tests use input/expected file pairs in the tests/ directory. If MCP generated test fixtures, they will run automatically. For test structure, CI integration, and debugging strategies, see Testing.

​
5. Run your codemod

Run your codemod on a target codebase: 
npx codemod workflow run -w ./my-codemod/ -t /path/to/your/project
AI-powered steps: If your workflow includes an AI step gated by a parameter, enable it at runtime:
LLM_API_KEY=your-key npx codemod workflow run -w ./my-codemod/ -t /path/to/project --param run_ai_step=true
Set LLM_API_KEY as an environment variable for your chosen provider. See Workflow Reference — AI steps for provider configuration.
For all CLI options, see CLI reference.

​
6. Publish

Share your codemod with your team or the community: 
npx codemod login
npx codemod publish
Your codemod is now in the Codemod Registry and runnable by anyone via npx codemod @your-scope/codemod-name. For CI/CD automation, trusted publishers, and API keys, see the Publishing guide.

​
Next steps

​
Scale your migrations

Your migration experience does not stop here. When you’re managing migrations across large codebases or multiple teams, the same codemod package can power Campaigns for automated multi-repo rollouts and Insights for tracking adoption progress. See the Platform quickstart for the full enterprise workflow.

​
Getting help

Join the community

Ask questions, get help, and connect with other codemod users on Slack.

Book a call

Schedule a demo or get hands-on help from the Codemod team.

​
Learn more

CLI reference

Full CLI command reference.

Workflow reference

Complete workflow.yaml specification.

JSSG

Learn the transformation engine in depth.

Publishing

Authentication methods and CI/CD setup.