Skip to main content

​
Directory Layout

my-codemod-package/
├─ codemod.yaml
├─ workflow.yaml
├─ scripts/
└─ rules/
The folder—called a codemod package—is the root when you run npx codemod workflow run -w ./my-codemod-package/.
You can combine types in a single package. The scripts/ and rules/ folders are conventional, not required—use any paths and reference them from workflow.yaml.
A codemod package is a directory containing your workflow.yaml and any scripts, rules, or assets referenced by your workflow.
  • When you run 
    npx codemod workflow run -w ./my-codemod-package/
    the directory is used as the root for all relative paths.
  • You can also run a workflow directly from a file: 
    npx codemod workflow run -w workflow.yaml

​
Workflow File

workflow.yaml
version: "1"
state:
  schema: []
templates: []
nodes: []
See Building codemod packages for a deep dive into nodes, steps, params, strategy, and examples.

​
codemod.yaml fields

These are the fields you define when scaffolding a new codemod (based on the actual CLI template and prompts):
​
schema_version
string
default:"1.0"
required
Codemod workflow schema version.
​
name
string
required
Codemod package name (unique within scope).Naming rules: /^[a-z0-9-_/]+$/ (lowercase letters, numbers, hyphens, underscores, and / for scope separation only)Not allowed: uppercase letters, dots, commas, spaces, or other special charactersValid examples:
  • remove-console-logs
  • @scope/remove-console-logs (using @organization-or-project-scope/name provides better discoverability in the Codemod Registry)
​
version
string
default:"0.1.0"
required
Semantic version of the package.
​
description
string
required
Brief description of what the codemod does.
​
author
string
required
Author name and email, e.g., Jane Doe <jane@example.com>.
​
license
string
default:"MIT"
required
License identifier (SPDX), e.g., MIT.
​
workflow
string
default:"workflow.yaml"
required
Relative path to your workflow file.
​
category
string
default:"migration"
Category for the codemod.
​
targets.languages
string[]
Languages targeted by this codemod (selected language during codemod init; editable later).
​
keywords
string[]
Keyword tags are an optional feature helping developers quickly identify the purpose, scope, and relevance of a codemod. They also enable better search, filtering, and reporting when managing many codemods across frameworks and projects.Example: keywords: ["react", "v18-to-v19", "migration"]
  • Keep tags concise (1–2 words).
  • Use lowercase for consistency.
  • Don’t overload with tags — 2–4 per codemod is ideal.
  • Prioritize transformation type + framework/library + version (if relevant).
1. Transformation Type TagsConsider these categories when describing why the codemod exists:
  • upgrade – helps upgrade code to newer versions (encompasses both breaking changes and feature adoption). You may also consider adding one of the following tags:
    • breaking-change – adapts code to framework/library breaking API changes.
    • feature-adoption – helps adoption of new optional or incremental features.
  • security – addresses known vulnerabilities or unsafe patterns.
  • cross-migration – replaces one library/framework with another.
  • i18n – internationalization migrations or improvements.
  • a11y – accessibility improvements and compliance.
  • standardization – unifies patterns, conventions, or APIs across a codebase.
  • code-mining – identifies, flags, or extracts patterns without transforming. Use if codemod is for detection-only.
Rule of thumb: Pick one primary type tag per codemod. Avoid mixing breaking-change and feature-adoption in the same codemod.
2. Target Version TagsUse these to indicate the framework/library version the codemod prepares for.
  • Format: vX or vX-to-vY (for upgrades).
  • Examples:
    • v17-to-v18 (React 17 → 18)
    • v5-to-v6 (React Router 5 → 6)
    • v16 (Angular 16 breaking changes)
Rule of thumb: If the codemod is version-specific, always tag it.
3. Framework / Library / SDK TagsAlways add the ecosystem name to improve discoverability.
  • Examples:
    • react
    • nextjs
    • nodejs
    • angular
    • msw
    • i18next
Rule of thumb: Use the official, common name of the framework/library.
4. Example Tag SetsHere are some examples to illustrate how tags combine:
  • React Root API Upgrade (17 → 18)
    • Tags: upgrade, breaking-change, v17-to-v18, react
  • Adopt React Hooks
    • Tags: upgrade, feature-adoption, react
  • Migrate from Moment.js to Day.js
    • Tags: cross-migration, momentjs, dayjs
  • Remove Hardcoded Strings for i18n
    • Tags: i18n, i18next
  • Add ARIA labels for accessibility
    • Tags: a11y, react
  • Detect Insecure crypto API usage
    • Tags: security, nodejs, crypto
​
registry.access
string
default:"public"
Access controls who can run/use the codemod (once they can see it).
  • public: Anyone can run the codemod.
  • private: Only the owner can run the codemod.
  • pro: Only Pro plan users can run the codemod.
Access applies on top of visibility. For example, visibility: public with access: pro shows the package publicly, but only Pro users can run it.
​
registry.visibility
string
default:"public"
Visibility controls who can see the package in the Registry (search, listings, and UI).
  • public: Everyone can see the package in the Registry.
  • private: Only the owner can see the package.
  • org: Members of the package’s organization scope can see the package.
  • user: Visible only to the publishing user (user-scoped visibility).
During scaffolding, the CLI sets public/private based on —private. You can change to any supported value above when publishing.
Example:
codemod.yaml
schema_version: "1.0"

name: "my-awesome-codemod"
version: "0.1.0"
description: "Transform legacy patterns to modern syntax"
author: "Your Name <you@example.com>"
license: "MIT"
workflow: "workflow.yaml"
category: "migration"

targets:
  languages: ["typescript"]

keywords: ["upgrade", "breaking-change", "react", "v17-to-v18"]

registry:
  access: "public"
  visibility: "public"
⌘I