Course overview

Introduction

Understand the basics of an AST and how it relates to real-world code

What is an Abstract Syntax Tree? Visualizing Code Like a Compiler

Looking at an example code snippet and how it relates to the resulting AST

How to View Abstract Syntax Tree Code With AST Explorer

An overview of the tooling available in the web frontend (JavaScript) ecosystem that rely on ASTs

The Best JavaScript AST Tools - ESLint, Babel, Terser, and More

A quick overview of the basic environment setup used throughout this course

Environment setup

Understanding Abstract Syntax Trees (AST)

Exploring tools to convert (or parse) JavaScript into a real AST

How to Generate a JavaScript AST With Babel Plugins

Programmatically traverse an AST and visit arbitrary nodes

Traversing an AST With Babel Traverse

Add Type Safety and Prevent Runtime Errors With AST

Working with Abstract Syntax Trees

A practical example of needing to perform a code audit (static analysis) to understand the current state of a codebase

Practical code audits

Create a custom script to audit a codebase

How to Audit Your Code With AST Programming

Introduce a shared Button component to replace all existing button elements

How to Add a Component and Update an AST

A rough formula to determine when to use AST-based tooling

When to Use Abstract Syntax Tree Tooling to Refactor at Scale

Code Audits

Transforming code in place by mutating an AST

How to Mutate an AST and Automatically Replace Code Components

Using jscodeshift to make the same code transformations with less boilerplate

How to Create Codemods Using jscodeshift

Create tests for jscodeshift transforms for a faster feedback loop

How to Unit Test jscodeshift Transforms With ts-jest

Codemods

Implement a linting rule to prevent the code we just transformed from being reintroduced in the future

How to Ensure Codebase is Up to Date With Linting Rules

Use ESLint to create the same linting rule for the code with less boilerplate

How to Use ESLint to Create AST Rules With Babel Traverse

Testing custom ESLint linting rules to verify they work as expected

How to Test Custom ESLint Linting Rules With AST

Linting

In this course, we'll start with the fundamentals of abstract syntax trees (ASTs) and learn the basic mental models. This general AST knowledge can be translated to almost any tool that works with ASTs.

## Why this course?

Understanding and using ASTs unlocks the ability to make sweeping changes in a safe and reliable way in any size codebase.

## Course topics

Throughout this course, we'll have converted source code into ASTs, traversed, mutated, and generated ASTs. With these concepts we'll then explore several practical applications including things like code audits (static analysis), code transformations (codemods), and linting.

### Module 1

We'll learn the fundamentals of abstract syntax trees. 

- What is an AST?
- How to explore an AST
- Examples of JavaScript tools that work with ASTs

### Module 2

We'll learn how to work with ASTs.

- How to turn code into an AST
- How to programmatically navigate any AST 
- How to leverage TypeScript to prevent runtime errors

### Module 3

We'll learn how to statically analyze, or "audit" code to understand the state of the codebase using abstract syntax trees.

- An introduction to an example codebase and refactor
- Understanding the state of the current codebase
- When to use an AST-based tool versus doing something manually

### Module 4

We'll learn how to transform, or "codemod" code from one state to another using abstract syntax trees.

- How to make changes to an AST
- How to change ASTs with [jscodeshift](https://github.com/facebook/jscodeshift)
- How to test a code transform

### Module 5

We'll learn how to write rules, or "lint" code using abstract syntax trees.

- How to create rules for code
- How to create custom rules with [ESLint](https://eslint.org)
- How to test a rule

In this course, you'll learn the fundamentals of abstract syntax trees, what they are, how they work, and dive into several practical use cases of abstract syntax trees to maintain a JavaScript codebase.

Practical Abstract Syntax Trees

JavaScript tools that work with abstract syntax trees

How to parse, traverse, and generate abstract syntax trees

Practical skill set for maintaining large JavaScript codebases

In order to create a codemod, we needed to install several dependencies, and boilerplate code for reading, parsing, and writing files.

This is where a more specialized tool like 

 becomes useful. It's a toolkit for running codemods. It takes care of all the dependencies, and boilerplate for finding, reading, parsing, and writing back to files. It also has some other nice features for working in large codebases, like running a transform in parallel on multiple files, as well as a summary of how many files were changed.

Let's get started by creating a new directory and installing the dependencies.

# Create a new directory for the transform script
mkdir jscodeshift

# Change into the new jscodeshift directory
cd jscodeshift

# Initialize a new package.json file
npm init -y

# Add the necessary dependencies
npm i jscodeshift prettier
npm i -D @types/jscodeshift @types/prettier

. Prettier was installed again to consistently format code, but that's a "nice to have." The types were also installed since we're using TypeScript.

import { Transform } from "jscodeshift";

// Define a transform function that adheres to the jscodeshift API.
// The function accepts three arguments: 
//  - fileInfo: info about the current file
//  - api: jscodeshift library and helper functions
//  - options: all options passed to the runner via the CLI
const transform: Transform = (fileInfo, api) => {
  // Alias the jscodeshift API for ease of use.
  const j = api.jscodeshift;

  // Convert the file source into an AST.
  const root = j(fileInfo.source);

  // TODO: make desired transformations.

  // Convert the AST back to a string. In this case, 
  // nothing changed so `null` could be returned and
  // jscodeshift wouldn't do anything. 
  return root.toSource();
};

// The transform function then needs to be the default export.
// This will then be executed by jscodeshift for every file.
export default transform;

This transform function follows the jscodeshift API, which is a function that is the default export that accepts three arguments. It also supports transforms written in TypeScript with no additional setup (notice we didn't have to install anything except jscodeshift and its types).

Now, this can be executed with the jscodeshift CLI. It has a 

. The only required option is the path to the files to run the transform on.

npx jscodeshift --transform ./transform-00.ts ../flash-cards/src/

The Flash app is a basic setup, so the defaults work well.

If working with a codebase written in TypeScript, it would require overriding the 

. Additionally, it would require passing 

. This can be somewhat confusing, because 

---
title: How to Create Codemods Using jscodeshift
description: Using jscodeshift to make the same code transformations with less boilerplate
privateVideoUrl: "https://fullstack.wistia.com/medias/45tcpeyaty"
code: https://gitlab.com/fullstackio/books/newline-course-apps/spencer-miskoviak-practical-abstract-syntax-trees-app/-/tree/main/code/module_05/lesson_05.02/App?ref_type=heads
---

# Using jscodeshift

In order to create a codemod, we needed to install several dependencies, and boilerplate code for reading, parsing, and writing files.

This is where a more specialized tool like [`jscodeshift`](https://github.com/facebook/jscodeshift) becomes useful. It's a toolkit for running codemods. It takes care of all the dependencies, and boilerplate for finding, reading, parsing, and writing back to files. It also has some other nice features for working in large codebases, like running a transform in parallel on multiple files, as well as a summary of how many files were changed.

## Getting started

Let's get started by creating a new directory and installing the dependencies.

```bash
# Create a new directory for the transform script
mkdir jscodeshift

# Change into the new jscodeshift directory
cd jscodeshift

# Initialize a new package.json file
npm init -y

# Add the necessary dependencies
npm i jscodeshift prettier
npm i -D @types/jscodeshift @types/prettier
```

The only required dependency is `jscodeshift`. Prettier was installed again to consistently format code, but that's a "nice to have." The types were also installed since we're using TypeScript.

## Creating the transform

Next, create a new `transform-00.ts` file with the [transform boilerplate](https://github.com/facebook/jscodeshift#transform-module) to work with jscodeshift.

```typescript { actualFilename=./protected/jscodeshift/transform-00.ts endChar=882 endLine=25 startChar=0 startLine=1 statedFilename=transform-00.ts url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_05/lesson_05.02/protected/jscodeshift/transform-00.ts }
import { Transform } from "jscodeshift";

// Define a transform function that adheres to the jscodeshift API.
// The function accepts three arguments: 
//  - fileInfo: info about the current file
//  - api: jscodeshift library and helper functions
//  - options: all options passed to the runner via the CLI
const transform: Transform = (fileInfo, api) => {
  // Alias the jscodeshift API for ease of use.
  const j = api.jscodeshift;

  // Convert the file source into an AST.
  const root = j(fileInfo.source);

  // TODO: make desired transformations.

  // Convert the AST back to a string. In this case, 
  // nothing changed so `null` could be returned and
  // jscodeshift wouldn't do anything. 
  return root.toSource();
};

// The transform function then needs to be the default export.
// This will then be executed by jscodeshift for every file.
export default transform;
```

This transform function follows the jscodeshift API, which is a function that is the default export that accepts three arguments. It also supports transforms written in TypeScript with no additional setup (notice we didn't have to install anything except jscodeshift and its types).

Now, this can be executed with the jscodeshift CLI. It has a [number of options](https://github.com/facebook/jscodeshift#usage-cli). The only required option is the path to the files to run the transform on.

```bash
npx jscodeshift --transform ./transform-00.ts ../flash-cards/src/
```

The Flash app is a basic setup, so the defaults work well.

:::tip

If working with a codebase written in TypeScript, it would require overriding the `--extensions` option to `ts` or `tsx` since it defaults to `js`. Additionally, it would require passing `ts` or `tsx` for the [`--parser` option](https://github.com/facebook/jscodeshift#parser).

:::

The default jscodeshift parser is `babel`. The other options are: `babylon`, `flow`, `ts`, or `tsx`. This can be somewhat confusing, because `babylon` was the previous name of `@babel/parser`.

:::note

The default `babel` parser is a legacy configuration option to behave like babel v5, while `babylon` is a more modern configuration.

Additionally, the `babel` parser adds the [`estree` babel plugin](https://github.com/facebook/jscodeshift/blob/master/parser/babel5Compat.js#L24). It changes the types of nodes in the AST, which can be confusing if using the `@babel/parser` plugin option in the AST Explorer. The `estree` plugin merges different types of nodes like `StringLiteral` and `NumericLiteral` into a single `Literal` node, [along with several others](https://babeljs.io/docs/en/babel-parser#output).

:::

While it isn't strictly necessary in this case, we will also pass `babylon` as the parser option to avoid some of this confusion and use the more modern configuration.

```bash
npx jscodeshift --transform ./transform-00.ts --parser babylon ../flash-cards/src/
```

The output should look something like the following.

```txt { actualFilename=./protected/jscodeshift-output-00.txt endChar=605 endLine=23 startChar=0 startLine=1 statedFilename=output.txt url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_05/lesson_05.02/protected/jscodeshift-output-00.txt }
Processing 14 files...
Spawning 14 workers...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
Sending 1 files to free worker...
All done.
Results:
0 errors
14 unmodified
0 skipped
0 ok
Time elapsed: 0.885seconds
```

Right now, this transform isn't doing anything, but we have verified that it's all working properly. This setup has taken care of everything except the custom logic of transforming `button` elements into `Button` components. Jscodeshift has taken care of all the dependencies, finding relevant files, reading files, parsing files into an AST, and writing that AST back to files.

Spencer Miskoviak

In order to create a code mod, we needed to install several dependencies in

code for reading, parsing, and writing files.

This is where a more specialized tool like JS code shift becomes useful.

It takes care of all the dependencies in boilerplate for finding, reading,

It also has some other nice features for working in large code bases, like

in parallel on multiple files, as well as a summary of how many files were

Let's again get started by switching to our terminal and creating a new

JS code shift, and initialize another package.json.

This time, the only dependency we need is JS code shift, but we'll also install

Again, the only required dependency here was JS code shift.

Critier was installed, again, to consistently format code, but that's a nice to

The types were also installed since we're using TypeScript.

We can then add the necessary boilerplate for a JS code shift transform.

We'll start by importing the transform type from JS code shift, because it

call signature for the transform function.

Then we can define the transform function, which takes in a file info object,

For convenience, we'll alias the JS code shift API to the variable J. Then,

J, we'll invoke it with the source from the file info object, which will give

And finally, we'll return the root converted back to source.

And lastly, we'll make this transform function the default export.

This transform function follows the basic JS code shift API, which is a

is the default export that accepts three arguments.

It also supports transforms written in TypeScript with no additional setup.

Notice that we didn't have to install anything except J is code shift in its

Now this basic transform can be executed using JS code shift, with the path to

that we want to transform, as well as the transform file to the transform flag.

There are several other options that JS code shift accepts.

For example, if working with a code base written in TypeScript, it would

the extensions flag option to TS or TSX, since it defaults to JS.

Additionally, it would require passing TS or TSX for the parser option.

The default JS code shift parser is Babel.

The other options are Babylon, Flow, TS, or TSX.

This can be somewhat confusing because Babylon was the previous name of Babel

The default Babel parser is a legacy configuration option to behave like Babel

Additionally, the Babel parser adds the ES tree Babel plugin.

It changes the types of nodes in the AST, which can be confusing if using the

parser plugin option in the AST Explorer.

The ES tree plugin merges different types of nodes like string literal and

into a single literal node, along with several other changes.

While it isn't strictly necessary in this case, we will still pass Babel on as

option to avoid some of this confusion and use the more modern configuration.

Right now, this transform isn't doing anything, but we have verified that it's

The setup has taken care of everything except the custom logic of transforming

JS code shift has taken care of all the dependencies, finding relevant files,

files into an AST, and writing that AST back to files.

Additionally, it provides convenient helpers like find JSX elements when

Lastly, it runs the transformations in parallel, and outputs a summary of the

which become more important as the size of the code base grows.

The output shows it found 14 files that matched that provided path.

It then processed those files in various workers and printed the results.

Since the transform isn't doing anything yet, all 14 files were unmodified.

Much of the same logic from the previous lesson can be reused for traversing

Since we're now using JS code shift helpers, it will look a little different.

Let's switch back to our editor and add a few imports that we'll need.

First, the JSX attribute type from JS code shift.

We'll also need nodes path utilities as well as prettier.

Then we'll still want to keep track if the file contains any buttons.

For now, let's skip over the traversal logic.

If the file contains any buttons, then we need to add the import as before, as

If the file doesn't contain any buttons, then we don't need to make any changes