Skip to main content
Codemod provides infrastructure for framework and library maintainers to build, test, and distribute automated migrations. When you ship breaking changes, codemods help your users upgrade by eliminating the repetitive, mechanical parts of migration, reducing the effort that keeps them stuck on old versions. Users on outdated versions create ongoing costs:
  • security vulnerabilities go unpatched
  • bug reports duplicate issues already fixed upstream
  • community support fragments across versions
Codemods address this by making upgrades less painful.

​
What Codemod enables

  • Eliminate repetitive migration work - Codemods handle mechanical changes like renaming APIs, updating imports, and refactoring patterns. Your users focus on the parts that require human judgment.
  • Handle real-world complexity - Migrations aren’t always simple. Workflows supports multiple step types, manual approval gates for human intervention, and AI-assisted steps for non-deterministic tasks.
  • Distribute through a central registry - Publish codemods to the Codemod Registry where users discover and run them via CLI or Codemod platform.

​
How it works

  1. Write codemods that automate breaking changes using jssg, YAML rules, or multi-step workflows
  2. Publish to the registry under your framework’s namespace using the CLI or CI/CD
  3. Users run them with a single CLI command or through Codemod platform

​
Examples

See how other frameworks use Codemod to help their communities upgrade:

Node.js

Node.js API deprecation and upgrade codemods.

React

Automated migrations for React version upgrades.

Nuxt

Codemods for Nuxt framework migrations.

pnpm

Tooling migrations for pnpm package manager.

MSW

Mock Service Worker v1 to v2 migration.

Fastify

Fastify framework upgrade automation.
Want to add your framework? Ping us on Slack or start building below.

​
Getting started

Codemods can be built using:
  • CLI - Scaffold and build locally with npx codemod init
  • MCP - AI-assisted creation in your IDE
  • Studio - Web-based prototyping with Codemod AI
This guide uses the CLI. The workflow is the same regardless of how you create the codemod.

​
Build your first codemod

1

Scaffold a new package

npx codemod init
The CLI walks you through setup:
  • Codemod type - jssg (simple transforms) or multi-step workflow (complex migrations)
  • Target language - TypeScript, JavaScript, Python, etc.
  • Package name - Use @your-framework/codemod-name for scoped packages
This creates a folder with the required structure:
my-codemod/
├── codemod.yaml        # Package metadata
├── workflow.yaml       # Workflow definition
└── scripts/
    └── codemod.ts      # Your transformation logic
2

Write your transformation

Open scripts/codemod.ts and write your transformation. Here’s a minimal example that replaces console.log with logger.log:
scripts/codemod.ts
import type { Transform } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";

const transform: Transform<TSX> = (root) => {
  const node = root.root();
  const matches = node.findAll({ pattern: "console.log($$$ARGS)" });

  if (matches.length === 0) return null;

  const edits = matches.map((match) => {
    const args = match.getMultipleMatches("ARGS").map(a => a.text()).join(", ");
    return match.replace(`logger.log(${args})`);
  });

  return node.commitEdits(edits);
};

export default transform;
See the jssg quickstart for patterns and API details.
3

Test locally

Run your codemod against a target directory:
npx codemod workflow run -w ./my-codemod/ -t ./path/to/test-repo
For automated testing, create input/expected fixtures:
tests/
  basic-case/
    input.ts       # Before
    expected.ts    # After
Then run:
npx codemod jssg test ./scripts/codemod.ts -l tsx
See testing documentation for more options.

​
Publish to the registry

Once your codemod works locally, publish it so your users can run it.
1

Login

npx codemod login
This opens a browser for authentication. You can sign in with GitHub, GitLab, or SSO.
2

Publish

npx codemod publish
Your codemod is now live in the Codemod Registry. Users can run it with:
npx codemod @your-framework/codemod-name
Use scoped package names (e.g., @nuxt/v3-to-v4) to group codemods under your framework’s namespace.

​
CI/CD and automation

For ongoing codemod development, use the migrations template to get a ready-to-use repository with GitHub Actions for validation and publishing.
1

Create your codemods repository

Fork or use the migrations template in your GitHub organization.
2

Link your organization

  1. Sign in to Codemod
  2. Create an organization matching your GitHub org name
  3. Install the Codemod GitHub App
This enables trusted publishing—passwordless publishing from GitHub Actions with no API keys to manage.
3

Configure your workflow

For trusted publishing, ensure your workflow has OIDC permissions:
permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@v4
  - uses: codemod/publish-action@v1
Prefer API keys instead? Create one and add it as a repository secret named CODEMOD_API_KEY. See publishing for all options.
4

Push and publish

Add codemods to your repository. The GitHub Action validates on PR and publishes on release.

​
Getting help

Join the community

Ask questions, get help, and connect with other framework maintainers on Slack.

Book a call

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

​
Next steps

CLI

Learn more about Codemod CLI.

Workflows

Orchestrate complex multi-step migrations.

JSSG

Learn the transformation engine in depth.

Publishing

Authentication methods and CI/CD setup.