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.