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.