Utilities for handling *.{js,ts} files as abstract syntax tree

@codemod-utils/ast-javascript provides methods from recast to help you parse and transform *.{js,ts} files.

import { AST } from '@codemod-utils/ast-javascript';

function transformCode(file: string, isTypeScript: boolean): string {
  const traverse = AST.traverse(isTypeScript);

  const ast = traverse(file, {
    /* Use AST.builders to transform the tree */
  });

  return AST.print(ast);
}

In the traverse call, you can specify how to visit the nodes of interest ("visit methods") and how to modify them ("builders").

• Builders
• Visit methods

Currently, recast lacks documentation and tutorials. This is unfortunate, given the large amount of builders and visit methods that it provides to help you transform code.

I recommend using AST Explorer to test a small piece of code and familiarize with the API. The error messages from TypeScript, which you can find in your browser's console, can sometimes help. AST Workshop provides a good starting point for Handlebars.

If you intend to publish your codemod, I recommend using @codemod-utils/tests (create and test file fixtures) to check the output and prevent regressions.

Select the following options to create a 4-tab window:

• Language: JavaScript
• Parser: recast
• Transform: recast

Copy-paste the visit methods from your file to AST explorer, then rename AST.builders to b.

Example

/* Your file */
import { AST } from '@codemod-utils/ast-javascript';

export function transformCode(file) {
  const traverse = AST.traverse(true);

  const ast = traverse(file, {
    visitClassDeclaration(path) {
      const { body } = path.node.body;

      const nodesToAdd = [
        AST.builders.classProperty(
          AST.builders.identifier('styles'),
          AST.builders.identifier('styles'),
        ),
      ];

      body.unshift(...nodesToAdd);

      return false;
    },
  });

  return AST.print(ast);
}

/* AST Explorer */
export default function transformer(code, { recast, parsers }) {
  const ast = recast.parse(code, { parser: parsers.typescript });
  const b = recast.types.builders;

  recast.visit(ast, {
    visitClassDeclaration(path) {
      const { body } = path.node.body;

      const nodesToAdd = [
        b.classProperty(
          b.identifier('styles'),
          b.identifier('styles')
        )
      ];

      body.unshift(...nodesToAdd);

      return false;
    }
  });

  return recast.print(ast).code;
}

@codemod-utils/ast-javascript avoids re-exporting the types from recast. This is to prevent a change in their API from catastrophically affecting your code.

When you write a function that depends on their implementation, type what you don't own as unknown, then use @ts-ignore or @ts-expect-error as needed.

Most importantly, write tests to document the inputs and outputs of your codemod. When there is an API change, you can refactor code with ease and confidence.

• Node.js v18 or above

See the Contributing guide for details.

This project is licensed under the MIT License.