Refactoring with Codemods to Automate API Modifications
As a library developer, you might create a well-liked utility that a whole bunch of
1000’s of builders depend on day by day, comparable to lodash or React. Over time,
utilization patterns would possibly emerge that transcend your preliminary design. When this
occurs, you might want to increase an API by including parameters or modifying
operate signatures to repair edge circumstances. The problem lies in rolling out
these breaking modifications with out disrupting your customers’ workflows.
That is the place codemods are available in—a strong device for automating
large-scale code transformations, permitting builders to introduce breaking
API modifications, refactor legacy codebases, and preserve code hygiene with
minimal handbook effort.
On this article, we’ll discover what codemods are and the instruments you possibly can
use to create them, comparable to jscodeshift, hypermod.io, and codemod.com. We’ll stroll by real-world examples,
from cleansing up function toggles to refactoring element hierarchies.
You’ll additionally discover ways to break down advanced transformations into smaller,
testable items—a apply often called codemod composition—to make sure
flexibility and maintainability.
By the tip, you’ll see how codemods can turn out to be a significant a part of your
toolkit for managing large-scale codebases, serving to you retain your code clear
and maintainable whereas dealing with even essentially the most difficult refactoring
duties.
Breaking Modifications in APIs
Returning to the situation of the library developer, after the preliminary
launch, new utilization patterns emerge, prompting the necessity to lengthen an
For easy modifications, a primary find-and-replace within the IDE would possibly work. In
extra advanced circumstances, you would possibly resort to utilizing instruments like sed
or awk
. Nevertheless, when your library is extensively adopted, the
scope of such modifications turns into tougher to handle. You possibly can’t make certain how
extensively the modification will influence your customers, and the very last thing
you need is to interrupt current performance that doesn’t want
updating.
A standard method is to announce the breaking change, launch a brand new
model, and ask customers emigrate at their very own tempo. However this workflow,
whereas acquainted, usually would not scale nicely, particularly for main shifts.
Take into account React’s transition from class parts to operate parts
with hooks—a paradigm shift that took years for giant codebases to completely
undertake. By the point groups managed emigrate, extra breaking modifications had been
usually already on the horizon.
For library builders, this case creates a burden. Sustaining
a number of older variations to assist customers who haven’t migrated is each
expensive and time-consuming. For customers, frequent modifications threat eroding belief.
They might hesitate to improve or begin exploring extra secure alternate options,
which perpetuating the cycle.
However what in case you may assist customers handle these modifications mechanically?
What in case you may launch a device alongside your replace that refactors
their code for them—renaming features, updating parameter order, and
eradicating unused code with out requiring handbook intervention?
That’s the place codemods are available in. A number of libraries, together with React
and Subsequent.js, have already embraced codemods to clean the trail for model
bumps. For instance, React offers codemods to deal with the migration from
older API patterns, just like the previous Context API, to newer ones.
So, what precisely is the codemod we’re speaking about right here?
What’s a Codemod?
A codemod (code modification) is an automatic script used to rework
code to comply with new APIs, syntax, or coding requirements. Codemods use
Summary Syntax Tree (AST) manipulation to use constant, large-scale
modifications throughout codebases. Initially developed at Fb, codemods helped
engineers handle refactoring duties for giant tasks like React. As
Fb scaled, sustaining the codebase and updating APIs grew to become
more and more tough, prompting the event of codemods.
Manually updating 1000’s of recordsdata throughout completely different repositories was
inefficient and error-prone, so the idea of codemods—automated scripts
that rework code—was launched to deal with this downside.
The method sometimes entails three predominant steps:
- Parsing the code into an AST, the place every a part of the code is
represented as a tree construction. - Modifying the tree by making use of a change, comparable to renaming a
operate or altering parameters. - Rewriting the modified tree again into the supply code.
By utilizing this method, codemods be sure that modifications are utilized
constantly throughout each file in a codebase, lowering the prospect of human
error. Codemods may deal with advanced refactoring situations, comparable to
modifications to deeply nested constructions or eradicating deprecated API utilization.
If we visualize the method, it will look one thing like this:
Determine 1: The three steps of a typical codemod course of
The thought of a program that may “perceive” your code after which carry out
computerized transformations isn’t new. That’s how your IDE works whenever you
run refactorings like
Primarily, your IDE parses the supply code into ASTs and applies
predefined transformations to the tree, saving the consequence again into your
recordsdata.
For contemporary IDEs, many issues occur underneath the hood to make sure modifications
are utilized accurately and effectively, comparable to figuring out the scope of
the change and resolving conflicts like variable identify collisions. Some
refactorings even immediate you to enter parameters, comparable to when utilizing
order of parameters or default values earlier than finalizing the change.
Use jscodeshift in JavaScript Codebases
Let’s take a look at a concrete instance to know how we may run a
codemod in a JavaScript venture. The JavaScript group has a number of
instruments that make this work possible, together with parsers that convert supply
code into an AST, in addition to transpilers that may rework the tree into
different codecs (that is how TypeScript works). Moreover, there are
instruments that assist apply codemods to complete repositories mechanically.
One of the crucial in style instruments for writing codemods is jscodeshift, a toolkit maintained by Fb.
It simplifies the creation of codemods by offering a strong API to
manipulate ASTs. With jscodeshift, builders can seek for particular
patterns within the code and apply transformations at scale.
You should use jscodeshift
to determine and change deprecated API calls
with up to date variations throughout a whole venture.
Let’s break down a typical workflow for composing a codemod
manually.
Clear a Stale Characteristic Toggle
Let’s begin with a easy but sensible instance to show the
energy of codemods. Think about you’re utilizing a function
toggle in your
codebase to regulate the discharge of unfinished or experimental options.
As soon as the function is reside in manufacturing and dealing as anticipated, the subsequent
logical step is to scrub up the toggle and any associated logic.
For example, contemplate the next code:
const information = featureToggle('feature-new-product-list') ? identify: 'Product' : undefined;
As soon as the function is totally launched and not wants a toggle, this
may be simplified to:
const information = identify: 'Product' ;
The duty entails discovering all cases of featureToggle
within the
codebase, checking whether or not the toggle refers to
feature-new-product-list
, and eradicating the conditional logic surrounding
it. On the similar time, different function toggles (like
feature-search-result-refinement
, which can nonetheless be in improvement)
ought to stay untouched. The codemod must perceive the construction
of the code to use modifications selectively.
Understanding the AST
Earlier than we dive into writing the codemod, let’s break down how this
particular code snippet seems in an AST. You should use instruments like AST
Explorer to visualise how supply code and AST
are mapped. It’s useful to know the node sorts you are interacting
with earlier than making use of any modifications.
The picture beneath exhibits the syntax tree when it comes to ECMAScript syntax. It
accommodates nodes like Identifier
(for variables), StringLiteral
(for the
toggle identify), and extra summary nodes like CallExpression
and
ConditionalExpression
.

Determine 2: The Summary Syntax Tree illustration of the function toggle examine
On this AST illustration, the variable information
is assigned utilizing a
ConditionalExpression
. The take a look at a part of the expression calls
featureToggle('feature-new-product-list')
. If the take a look at returns true
,
the consequent department assigns identify: 'Product'
to information
. If
false
, the alternate department assigns undefined
.
For a activity with clear enter and output, I want writing assessments first,
then implementing the codemod. I begin by defining a damaging case to
guarantee we don’t unintentionally change issues we need to depart untouched,
adopted by an actual case that performs the precise conversion. I start with
a easy situation, implement it, then add a variation (like checking if
featureToggle known as inside an if assertion), implement that case, and
guarantee all assessments go.
This method aligns nicely with Check-Pushed Growth (TDD), even
in case you don’t apply TDD frequently. Realizing precisely what the
transformation’s inputs and outputs are earlier than coding improves security and
effectivity, particularly when tweaking codemods.
With jscodeshift, you possibly can write assessments to confirm how the codemod
behaves:
const rework = require("../remove-feature-new-product-list"); defineInlineTest( rework, , ` const information = featureToggle('feature-new-product-list') ? identify: 'Product' : undefined; `, ` const information = identify: 'Product' ; `, "delete the toggle feature-new-product-list in conditional operator" );
The defineInlineTest
operate from jscodeshift means that you can outline
the enter, anticipated output, and a string describing the take a look at’s intent.
Now, operating the take a look at with a standard jest
command will fail as a result of the
codemod isn’t written but.
The corresponding damaging case would make sure the code stays unchanged
for different function toggles:
defineInlineTest( rework, , ` const information = featureToggle('feature-search-result-refinement') ? identify: 'Product' : undefined; `, ` const information = featureToggle('feature-search-result-refinement') ? identify: 'Product' : undefined; `, "don't change different function toggles" );
Writing the Codemod
Let’s begin by defining a easy rework operate. Create a file
known as rework.js
with the next code construction:
module.exports = operate(fileInfo, api, choices) const j = api.jscodeshift; const root = j(fileInfo.supply); // manipulate the tree nodes right here return root.toSource(); ;
This operate reads the file right into a tree and makes use of jscodeshift’s API to
question, modify, and replace the nodes. Lastly, it converts the AST again to
supply code with .toSource()
.
Now we are able to begin implementing the rework steps:
- Discover all cases of
featureToggle
. - Confirm that the argument handed is
'feature-new-product-list'
. - Change the whole conditional expression with the consequent half,
successfully eradicating the toggle.
Right here’s how we obtain this utilizing jscodeshift
:
module.exports = operate (fileInfo, api, choices) const j = api.jscodeshift; const root = j(fileInfo.supply); // Discover ConditionalExpression the place the take a look at is featureToggle('feature-new-product-list') root .discover(j.ConditionalExpression, take a look at: callee: identify: "featureToggle" , arguments: [ value: "feature-new-product-list" ], , ) .forEach((path) => // Change the ConditionalExpression with the 'consequent' j(path).replaceWith(path.node.consequent); ); return root.toSource(); ;
The codemod above:
- Finds
ConditionalExpression
nodes the place the take a look at calls
featureToggle('feature-new-product-list')
. - Replaces the whole conditional expression with the resultant (i.e.,
), eradicating the toggle logic and leaving simplified code
identify: 'Product'
behind.
This instance demonstrates how straightforward it’s to create a helpful
transformation and apply it to a big codebase, considerably lowering
handbook effort.
You’ll want to put in writing extra take a look at circumstances to deal with variations like
if-else
statements, logical expressions (e.g.,
!featureToggle('feature-new-product-list')
), and so forth to make the
codemod sturdy in real-world situations.
As soon as the codemod is prepared, you possibly can try it out on a goal codebase,
such because the one you are engaged on. jscodeshift offers a command-line
device that you should use to use the codemod and report the outcomes.
$ jscodeshift -t transform-name src/
After validating the outcomes, examine that every one practical assessments nonetheless
go and that nothing breaks—even in case you’re introducing a breaking change.
As soon as glad, you possibly can commit the modifications and lift a pull request as
a part of your regular workflow.
Codemods Enhance Code High quality and Maintainability
Codemods aren’t simply helpful for managing breaking API modifications—they will
considerably enhance code high quality and maintainability. As codebases
evolve, they usually accumulate technical debt, together with outdated function
toggles, deprecated strategies, or tightly coupled parts. Manually
refactoring these areas may be time-consuming and error-prone.
By automating refactoring duties, codemods assist hold your codebase clear
and freed from legacy patterns. Commonly making use of codemods means that you can
implement new coding requirements, take away unused code, and modernize your
codebase with out having to manually modify each file.