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:

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:

1

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:

Before
<div ref='refName' />;

Should be transformed into:

After
<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.

2

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.

3

Build codemod with AI

By clicking “Autogenerate with Codemod AI” Codemod Studio will begin building your codemod.

4

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:

5

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:

  1. Open .codemodrc.json using your preferred editor.

  2. 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:

    1. adjust the previous auto-generated name value
    2. populate the meta and applicability 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.

​
Publishing the codemod package

Now that our codemod package is ready, we can publish it to Codemod Registry. To do so, you can:

  1. navigate to the root directory of the codemod package
  2. logging in with codemod login
  3. 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:

  1. Navigate to your target project

  2. Run the codemod:

codemod [codemod-name]

In this example, we can run the codemod using:

codemod react/19/replace-string-ref
By default, running the codemod will attempt to apply the transformation on all target files in the current directory. Make sure to run the codemod in the correct project directory.

To learn more about running codemods, refer to this page.

Was this page helpful?

IntroductionReact 18 to 19 Migration