Refactoring with Codemods to Automate API Changes

Clean a Stale Feature Toggle

Let’s start with a simple yet practical example to demonstrate the
power of codemods. Imagine you’re using a feature
toggle in your
codebase to control the release of unfinished or experimental features.
Once the feature is live in production and working as expected, the next
logical step is to clean up the toggle and any related logic.

For instance, consider the following code:

const data = featureToggle('feature-new-product-list') ? { name: 'Product' } : undefined;

Once the feature is fully released and no longer needs a toggle, this
can be simplified to:

const data = { name: 'Product' };

The task involves finding all instances of featureToggle in the
codebase, checking whether the toggle refers to
feature-new-product-list, and removing the conditional logic surrounding
it. At the same time, other feature toggles (like
feature-search-result-refinement, which may still be in development)
should remain untouched. The codemod needs to understand the structure
of the code to apply changes selectively.

Understanding the AST

Before we dive into writing the codemod, let’s break down how this
specific code snippet looks in an AST. You can use tools like AST
Explorer to visualize how source code and AST
are mapped. It’s helpful to understand the node types you’re interacting
with before applying any changes.

The image below shows the syntax tree in terms of ECMAScript syntax. It
contains nodes like Identifier (for variables), StringLiteral (for the
toggle name), and more abstract nodes like CallExpression and
ConditionalExpression.

Figure 2: The Abstract Syntax Tree representation of the feature toggle check

In this AST representation, the variable data is assigned using a
ConditionalExpression. The test part of the expression calls
featureToggle('feature-new-product-list'). If the test returns true,
the consequent branch assigns { name: 'Product' } to data. If
false, the alternate branch assigns undefined.

For a task with clear input and output, I prefer writing tests first,
then implementing the codemod. I start by defining a negative case to
ensure we don’t accidentally change things we want to leave untouched,
followed by a real case that performs the actual conversion. I begin with
a simple scenario, implement it, then add a variation (like checking if
featureToggle is called inside an if statement), implement that case, and
ensure all tests pass.

This approach aligns well with Test-Driven Development (TDD), even
if you don’t practice TDD regularly. Knowing exactly what the
transformation’s inputs and outputs are before coding improves safety and
efficiency, especially when tweaking codemods.

With jscodeshift, you can write tests to verify how the codemod
behaves:

const transform = require("../remove-feature-new-product-list");

defineInlineTest(
  transform,
  {},
  `
  const data = featureToggle('feature-new-product-list') ? { name: 'Product' } : undefined;
  `,
  `
  const data = { name: 'Product' };
  `,
  "delete the toggle feature-new-product-list in conditional operator"
);

The defineInlineTest function from jscodeshift allows you to define
the input, expected output, and a string describing the test’s intent.
Now, running the test with a normal jest command will fail because the
codemod isn’t written yet.

The corresponding negative case would ensure the code remains unchanged
for other feature toggles:

defineInlineTest(
  transform,
  {},
  `
  const data = featureToggle('feature-search-result-refinement') ? { name: 'Product' } : undefined;
  `,
  `
  const data = featureToggle('feature-search-result-refinement') ? { name: 'Product' } : undefined;
  `,
  "do not change other feature toggles"
);

Writing the Codemod

Let’s start by defining a simple transform function. Create a file
called transform.js with the following code structure:

module.exports = function(fileInfo, api, options) {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  // manipulate the tree nodes here

  return root.toSource();
};

This function reads the file into a tree and uses jscodeshift’s API to
query, modify, and update the nodes. Finally, it converts the AST back to
source code with .toSource().

Now we can start implementing the transform steps:

1. Find all instances of featureToggle.
2. Verify that the argument passed is 'feature-new-product-list'.
3. Replace the entire conditional expression with the consequent part,
   effectively removing the toggle.

Here’s how we achieve this using jscodeshift:

module.exports = function (fileInfo, api, options) {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  // Find ConditionalExpression where the test is featureToggle('feature-new-product-list')
  root
    .find(j.ConditionalExpression, {
      test: {
        callee: { name: "featureToggle" },
        arguments: [{ value: "feature-new-product-list" }],
      },
    })
    .forEach((path) => {
      // Replace the ConditionalExpression with the 'consequent'
      j(path).replaceWith(path.node.consequent);
    });

  return root.toSource();
};

The codemod above:

• Finds ConditionalExpression nodes where the test calls
  featureToggle('feature-new-product-list').
• Replaces the entire conditional expression with the consequent (i.e., {
name: 'Product' }), removing the toggle logic and leaving simplified code
  behind.

This example demonstrates how easy it is to create a useful
transformation and apply it to a large codebase, significantly reducing
manual effort.

You’ll need to write more test cases to handle variations like
if-else statements, logical expressions (e.g.,
!featureToggle('feature-new-product-list')), and so on to make the
codemod robust in real-world scenarios.

Once the codemod is ready, you can test it out on a target codebase,
such as the one you’re working on. jscodeshift provides a command-line
tool that you can use to apply the codemod and report the results.

$ jscodeshift -t transform-name src/

After validating the results, check that all functional tests still
pass and that nothing breaks—even if you’re introducing a breaking change.
Once satisfied, you can commit the changes and raise a pull request as
part of your normal workflow.

Codemods Improve Code Quality and Maintainability

Codemods aren’t just useful for managing breaking API changes—they can
significantly improve code quality and maintainability. As codebases
evolve, they often accumulate technical debt, including outdated feature
toggles, deprecated methods, or tightly coupled components. Manually
refactoring these areas can be time-consuming and error-prone.

By automating refactoring tasks, codemods help keep your codebase clean
and free of legacy patterns. Regularly applying codemods allows you to
enforce new coding standards, remove unused code, and modernize your
codebase without having to manually modify every file.

Refactoring an Avatar Component

Now, let’s look at a more complex example. Suppose you’re working with
a design system that includes an Avatar component tightly coupled with a
Tooltip. Whenever a user passes a name prop into the Avatar, it
automatically wraps the avatar with a tooltip.

Figure 3: A avatar component with a tooltip

Here’s the current Avatar implementation:

import { Tooltip } from "@design-system/tooltip";

const Avatar = ({ name, image }: AvatarProps) => {
  if (name) {
    return (
      
        
      
    );
  }

  return ;
};

The goal is to decouple the Tooltip from the Avatar component,
giving developers more flexibility. Developers should be able to decide
whether to wrap the Avatar in a Tooltip. In the refactored version,
Avatar will simply render the image, and users can apply a Tooltip
manually if needed.

Here’s the refactored version of Avatar:

const Avatar = ({ image }: AvatarProps) => {
  return ;
};

Now, users can manually wrap the Avatar with a Tooltip as
needed:

import { Tooltip } from "@design-system/tooltip";
import { Avatar } from "@design-system/avatar";

const UserProfile = () => {
  return (
    
      
    
  );
};

The challenge arises when there are hundreds of Avatar usages spread
across the codebase. Manually refactoring each instance would be highly
inefficient, so we can use a codemod to automate this process.

Using tools like AST Explorer, we can
inspect the component and see which nodes represent the Avatar usage
we’re targeting. An Avatar component with both name and image props
is parsed into an abstract syntax tree as shown below:

Figure 4: AST of the Avatar component usage

Writing the Codemod

Let’s break down the transformation into smaller tasks:

• Find Avatar usage in the component tree.
• Check if the name prop is present.
• If not, do nothing.
• If present:
• Create a Tooltip node.
• Add the name to the Tooltip.
• Remove the name from Avatar.
• Add Avatar as a child of the Tooltip.
• Replace the original Avatar node with the new Tooltip.

To begin, we’ll find all instances of Avatar (I’ll omit some of the
tests, but you should write comparison tests first).

defineInlineTest(
    { default: transform, parser: "tsx" },
    {},
    `
    
    `,
    `
    
      
    
    `,
    "wrap avatar with tooltip when name is provided"
  );

Similar to the featureToggle example, we can use root.find with
search criteria to locate all Avatar nodes:

root
  .find(j.JSXElement, {
    openingElement: { name: { name: "Avatar" } },
  })
  .forEach((path) => {
    // now we can handle each Avatar instance
  });

Next, we check if the name prop is present:

root
  .find(j.JSXElement, {
    openingElement: { name: { name: "Avatar" } },
  })
  .forEach((path) => {
    const avatarNode = path.node;

    const nameAttr = avatarNode.openingElement.attributes.find(
      (attr) => attr.name.name === "name"
    );

    if (nameAttr) {
      const tooltipElement = createTooltipElement(
        nameAttr.value.value,
        avatarNode
      );
      j(path).replaceWith(tooltipElement);
    }
  });

For the createTooltipElement function, we use the
jscodeshift API to create a new JSX node, with the name
prop applied to the Tooltip and the Avatar
component as a child. Finally, we call replaceWith to
replace the current path.

Here’s a preview of how it looks in
Hypermod, where the codemod is written on
the left. The top part on the right is the original code, and the bottom
part is the transformed result:

Figure 5: Run checks inside hypermod before apply it to your codebase

This codemod searches for all instances of Avatar. If a
name prop is found, it removes the name prop
from Avatar, wraps the Avatar inside a
Tooltip, and passes the name prop to the
Tooltip.

By now, I hope it’s clear that codemods are incredibly useful and
that the workflow is intuitive, especially for large-scale changes where
manual updates would be a huge burden. However, that’s not the whole
picture. In the next section, I’ll shed light on some of the challenges
and how we can address these less-than-ideal aspects.