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: ast-grep
, filemod
, jscodeshift
, ts-morph
, and piranha
.
.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.
Specifies the slugified name of the codemod published to the codemod registry.
Specifies the current codemod version. Should follow the SemVer scheme.
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
.
Specifies the engine used to run the codemod. Can be any of:
filemod
jscodeshift
ts-morph
ast-grep
piranha
(requires additionallanguage
field that specifies one of the supported piranha languages:java
,kt
,go
,py
,swift
,ts
,tsx
, orscala
)recipe
(requires additionalnames
field, which is an ordered array of codemod names that will be executed)
Can be used to override the default glob pattern for files that will be processed by the codemod.
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)
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
If your codemod requires arguments, you can specify them in this field.
Specifies additional information about your codemod for discoverability purposes.
Specifies custom paths for the build input and output files.
Codemod package structure
Below, you can find the required codemod package structure for each codemod engine supported by Codemod platform.
Example of a jscodeshift/ts-morph/filemod codemod package:
Next steps
Building a codemod package ->
Get started with building a codemod package.
Was this page helpful?