Making Your First Codemod
In this tutorial, you’ll learn how to build, publish, and run your first codemod. During this process you will learn different concepts such as:
- Building codemod packages with Codemod Studio
- Configuring codemod packages using
.codemodrc.json
- Publishing codemods to Codemod Registry
- Running codemods using Codemod CLI
To keep this tutorial practical, you will learn these concepts by creating a codemod that addresses string refs deprecation in React 19. However, these concepts will apply to many codemods you will build for various use cases moving forward.
Building codemods with Codemod Studio
To get started, we will head to Codemod Studio. Codemod Studio uses tuned Codemod AI to build codemods using before/after code examples. You can learn more about Codemod Studio here.
To start building the codemod:
Add before/after code examples
We will use the before/after code examples in the React 19 migration guide.
In this case, the following transformation should happen:
<div ref='refName' />;
Should be transformed into:
<div ref={(ref) => (this.refs.refName = ref)} />;
We will add these before/after code examples to the before and after code panes in Codemod Studio:
You can add multiple before/after code snippets to cover edge cases. Please refer to Codemod Studio’s tips and best practices while adding more test cases.
Add natural language descriptions
To improve codemod generation accuracy, you can provide more context about the transformation to Codemod AI by adding natural language descriptions.
Build codemod with AI
By clicking “Autogenerate with Codemod AI” Codemod Studio will begin building your codemod.
Test codemod (and iterate)
After the codemod is generated, it will automatically be pasted into the codemod editor on the right side. The Output
panel will show the result of running the codemod over the Before
snippet in real time.
This allows you to compare the actual output of the codemod to the After
snippet. If Codemod Studio detects discrepancies between the Output
and After
snippet, the code example will be highlighted in red.
Fixing various issues:
Exporting codemod
Once your codemod is working correctly, you can:
- export the codemod package locally
- publish it to your private registry
In this tutorial, we will export the codemod package locally as we will be publishing to the public Codemod Registry in the next steps.
To export the codemod package, you can click Download and run locally.
Configuring codemod packages
Now that we have a local codemod package, we can configure the .codemodrc.json
file. Doing so helps Codemod platform understand more information about your codemod package to allow for a better publishing and running experience to your codemod.
To configure the .codemodrc.json
file, you can:
-
Open
.codemodrc.json
using your preferred editor. -
Customize configuration fields.
By default, the file will look something similar to this:
.codemodrc.json{ "$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json", "name": "react-19-callback-ref-replace", "version": "1.0.0", "engine": "jscodeshift", "private": false, "arguments": [], "meta": {} }
In this example, we will:
- adjust the previous auto-generated
name
value - populate the
meta
andapplicability
fields.
This will allow our codemod to integrate better with Codemod Registry’s search and filtering so that users can find this codemod easily.
.codemodrc.json{ "$schema": "https://codemod-utils.s3.us-west-1.amazonaws.com/configuration_schema.json", "name": "react/19/replace-string-ref", "version": "1.0.0", "engine": "jscodeshift", "private": false, "arguments": [], "meta": { "git": "https://github.com/codemod-com/codemod/tree/main/packages/codemods/react/19/replace-string-ref", "tags": ["react", "migration"] }, "applicability": { "from": [["react", "<=", "18"]] } }
You can find a list of all supported
.codemodrc.json
fields here. - adjust the previous auto-generated
Publishing the codemod package
Now that our codemod package is ready, we can publish it to Codemod Registry. To do so, you can:
- navigate to the root directory of the codemod package
- logging in with
codemod login
- running
codemod publish
To learn more about publishing codemods, refer to this guide.
Now, your codemod will be available for anyone to discover and run from Codemod Registry.
You can find the published codemod built in this example here.
Running codemods
Finally, we can run the published codemod using Codemod CLI. To do so, you can:
-
Navigate to your target project
-
Run the codemod:
codemod [codemod-name]
In this example, we can run the codemod using:
codemod react/19/replace-string-ref
To learn more about running codemods, refer to this page.
Was this page helpful?