Publishing Codemods

Learn how to publish your codemods to Codemod Registry and share them with the world.

You can easily share your codemods with thousands of people around the world by adding them to Codemod Registry. Once added, they will automatically integrate with Codemod platform. This simplifies codemod discovery and distribution, and offers a better running codemods experience.

Publishing codemods to the registry is especially useful for framework/library builders. With features like shareable codemod deep links and Codemod CLI & IDE extenion, your users can adopt your latest releases with one click, straight from your migration doc. See example ->

Supported codemod engines

Codemod platform currently supports the following codemod engines: ast-grep, filemod, jscodeshift, ts-morph, and piranha.

Required codemod package structure

To make your codemod package compatible with Codemod platform, it needs to have a .codemodrc.json configuration file in the project root and conform to one of the structures, depending on the codemod engine used.

.codemodrc.json reference

name · string · required

Specifies the slugified name of the codemod published to the codemod registry.

version · string · required

Specifies the current codemod version. Should follow the SemVer scheme.

The version field must be bumped every time the codemod is published.

private · boolean · default: "false"

Can be used to set the codemod visibility to private.

By default, when a codemod is published without a namespace, visibility will be set as public. If a codemod is published under a namespace, such as @codemod/my-codemod, visibility will be set as private.

engine · string · required

Specifies the engine used to run the codemod. Can be any of:

• filemod
• jscodeshift
• ts-morph
• ast-grep
• piranha (requires additional language field that specifies one of the supported piranha languages: java, kt, go, py, swift, ts, tsx, or scala)
• recipe (requires additional names field, which is an ordered array of codemod names that will be executed)

include · glob pattern array

Can be used to override the default glob pattern for files that will be processed by the codemod.

applicability · object

The applicability field is an object with from and to keys that are both arrays of tuples. This field can be used to specify the dependencies and versions this codemod is made for.

Specifying the applicability criteria of your codemod helps:

1. Reduce false positives
2. Proactively recommend the codemod to users who might need it
3. Improve codemod performance, as it will only process projects that make sense
4. Allow daisy-chaining codemods (e.g., migrating from v1 to v3 by combining v1-to-v2 and v2-to-v3 codemods)

Each tuple consists of three elements:

1. a library name
2. a comparison operator (<, >, <=, >=, =)
3. a version number (SemVer compatible)

deps · array of strings

Can be used to specify dependencies to be installed after successful a codemod run. You can also specify a package to be removed by prepending it with a - sign. Each dependency should be a string in one of the following formats:

• package-name@version
• -package-name
• package-name

arguments · array of objects

If your codemod requires arguments, you can specify them in this field.

Show Argument fields

name · string

Specifies the argument name.

description · string

Specifies the argument description.

kind · string

Specifies the argument argument type. Can be any of: string, number, or boolean.

required · boolean

Specifies if the argument is required.

meta · object

Specifies additional information about your codemod for discoverability purposes.

Show Meta child fields

tags · array of strings

Specifies tags for your codemods (ex: next.js, react).

git · string

Specifies the url to the codemod’s repository.

build · object

Specifies custom paths for the build input and output files.

Show Build child fields

input · string

Specifies the path to the input file.

output · string

Specifies the path to the output file.

Example of a valid configuration file:

.codemodrc.json

  {
    "name": "my-unique-codemod-name",
    "version": "1.0.0",
    "private": false,
    "engine": "filemod",
    "include": ["**/*.js"],
    "applicability": {
      "from": [["react", ">", "17.0.0"], ["react", "<", "17.1.9"]],
      "to": [["react", "=", "18.0.0"]]
    },
    "deps": ["-jest", "vitest@2.0.0"],
    "arguments": [
      {
        "name": "arg1",
        "description": "Arg number one",
        "kind": "string",
        "required": false
      },
      {
        "name": "arg2",
        "description": "Some other arg",
        "kind": "number",
        "required": true
      }
    ],
    "meta": {
      "tags": ["react", "migration"],
      "git": "https://github.com/codemod-com/codemod"
    },
    "build": {
      "input": "src/index.ts",
      "output": "dist/index.cjs"
    }
  }

jscodeshift, ts-morph, and filemod

├── dist
│   ├── index.cjs # built codemod file. when someone runs your codemod, this file will be executed.
├── src
│   ├── index.ts # the default path for the codemod's entry point file.
│   ├── ...
├── .codemodrc.json # contains the codemod configuration
└── README.md # contain a short description and examples, such as in the example at the bottom of this page

.codemodrc.json

{
"$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json",
"version": "1.0.0",
"private": false,
"name": "framework/version/codemod-name",
"description": "example codemod description",
"engine": "jscodeshift/ts-morph/filemod",
"meta": {
  "tags": ["framework", "migration", "etc"],
    "git": "https://github.com/user/repo"
},
"applicability": {
  "from": [["framework", "<=", "version"]],
  "to": [["framework", "=", "version"]]
  }
}

├── dist
│   ├── index.cjs # built codemod file. when someone runs your codemod, this file will be executed.
├── src
│   ├── index.ts # the default path for the codemod's entry point file.
│   ├── ...
├── .codemodrc.json # contains the codemod configuration
└── README.md # contain a short description and examples, such as in the example at the bottom of this page

.codemodrc.json

{
"$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json",
"version": "1.0.0",
"private": false,
"name": "framework/version/codemod-name",
"description": "example codemod description",
"engine": "jscodeshift/ts-morph/filemod",
"meta": {
  "tags": ["framework", "migration", "etc"],
    "git": "https://github.com/user/repo"
},
"applicability": {
  "from": [["framework", "<=", "version"]],
  "to": [["framework", "=", "version"]]
  }
}

├── src
│   ├── rule.yaml # ast-grep rule file.
├── .codemodrc.json # should contain "engine" field set to "ast-grep"
└── README.md

To learn how to build your first rule, check out ast-grep’s documentation.

.codemodrc.json

{
"$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json",
"version": "1.0.0",
"private": false,
"name": "framework/version/codemod-name",
"description": "example codemod description",
"engine": "ast-grep",
"meta": {
  "tags": ["framework", "migration", "etc"],
  "git": "https://github.com/user/repo"
},
"applicability": {
  "from": [["framework", "<=", "version"]],
  "to": [["framework", "=", "version"]]
  }
}

├── .codemodrc.json # should contain "engine" field set to "recipe" and "names" field with an ordered array of codemod names that will be executed.
└── README.md

Unlike JavaScript and ast-grep codemods, recipes do not inlcude input files in .codemodrc.json. To specify codemods that should be run by the recipe, simply add the codemod names under the names field.

.codemodrc.json

{
  "$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json",
  "name": "framework/version/recipe-name",
  "version": "1.0.0",
  "private": false,
  "engine": "recipe",
  "names": [
    "framework/version/codemod-1",
    "framework/version/codemod-2",
    "framework/version/codemod-3"
  ],
  "meta": {
    "tags": ["framework", "migration"],
    "git": "https://github.com/user/repo"
  },
  "applicability": {
    "from": [["framework", "<=", "version"]],
    "to": [["framework", "=", "version"]]
  }
}

Publish with Codemod CLI

Once your codemod package is compatible with Codemod platform, you can use Codemod CLI to publish a local codemod to the codemod registry.

1. Login to Codemod platform

   Login to Codemod platform by using:

   codemod login
   

   You will be redirected to Codemod platform login page. Upon successful login, our CLI will automatically authenticate you.

2. Build your local project

   This will build a JavaScript project using esbuild and create a dist directory in your project root. If your codemod is not using a JavaScript engine, you can skip this step.

   If your local project is not already built, you can build it using codemod CLI:

   codemod build
   

3. Publish your codemod

   Publish your codemod by using the following command inside your project’s directory:

   codemod publish