Package requirements

A codemod package is compatible with Codemod platform when it:

uses a supported codemod engine
has a valid .codemodrc.json configuration file in its root directory
has a valid codemod package structure.

The .codemodrc.json configuration file allows Codemod platform to better understand information about your codemod, as well as bring an enhanced running experience.

The structure of the codemod package can vary based on the codemod engine used. This document explains the requirements for a valid codemod package for each of the supported codemod engines.

Supported codemod engines

Codemod platform currently supports the following codemod engines: jscodeshift, ts-morph, and ast-grep (recommended).

`.codemodrc.json` reference

The .codemodrc.json configuration file includes several metafields that can be used to help Codemod platform understand more information about your codemod package.

name

string

required

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

We recommend using the following naming convention for better codemod discoverability:

library/version/codemod-name

Optionally, you can specify an organization’s namespace for your codemod:

@organization/library/version/codemod-name

To create an organization namespace, contact us message us on the Slack community.

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.

If a codemod is published under an organization’s namespace, such as @codemod/my-codemod, visibility will default to private unless explicitly specified.

engine

string

required

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

ast-grep
jscodeshift
ts-morph
workflow
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:

Reduce false positives
Proactively recommend the codemod to users who might need it
Improve codemod performance, as it will only process projects that make sense
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:

a library name
a comparison operator (<, >, <=, >=, =)
a version number (SemVer compatible)

deps

array of strings

Can be used to specify dependencies to be installed after a successful 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.

Codemod package structure

Below, you can find the required codemod package structure for each codemod engine supported by Codemod platform.

├── 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.
│   ├── ...
│   package.json
├── .codemodrc.json # contains the codemod configuration
└── README.md # contains a short description and examples, such as in the example at the bottom of this page

{
  "$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/workflow",
  "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.
│   ├── ...
│   package.json
├── .codemodrc.json # contains the codemod configuration
└── README.md # contains a short description and examples, such as in the example at the bottom of this page

{
  "$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/workflow",
  "meta": {
    "tags": ["framework", "migration", "etc"],
    "git": "https://github.com/user/repo"
  },
  "applicability": {
    "from": [["framework", "<=", "version"]],
    "to": [["framework", "=", "version"]]
  }
}

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

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

{
  "$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"]]
  }
}

│   package.json
├── .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

Codemod recipes are a collection of codemods that are run in consecutive order. Codemod recipes allow you to daisy-chain a set of codemods that help with a large-scope migration.

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.

{
  "$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"]]
  }
}

Guides & Examples

Migrations

Supported codemod engines

`.codemodrc.json` reference

Codemod package structure

Codemod package examples

jscodeshift package

ast-grep package

Recipe package

Next steps

Building a codemod package ->

Guides & Examples

Migrations

​Supported codemod engines

​.codemodrc.json reference

​Codemod package structure

​Codemod package examples

jscodeshift package

ast-grep package

Recipe package

​Next steps

Building a codemod package ->

Supported codemod engines

`.codemodrc.json` reference

Codemod package structure

Codemod package examples

Next steps