recast

Recast parses JavaScript (and TypeScript, via configurable parsers) into an abstract syntax tree using the ast-types library, lets calling code freely mutate that tree, and then reprints it back to source — preserving the original formatting, comments, and whitespace of any part of the tree left untouched. This nondestructive reprinting is what distinguishes it from a plain parse-then-generate pipeline: hand-written code stays byte-identical except where it was actually changed.

Because of this property, recast is the parsing/printing engine underneath widely used codemod tools like jscodeshift and is used directly by Babel plugins, linters, and other JavaScript tooling that needs to programmatically rewrite source files without reformatting the rest of the file.

What You Get

• parse/print functions for round-tripping JavaScript/TypeScript source through an editable AST
• Nondestructive pretty-printing that preserves untouched code’s original formatting and comments
• Pluggable parser support (Babel, esprima, acorn, TypeScript, Flow) via the parser option
• Automatic source map generation for transformed output
• Deep integration with ast-types for node construction, traversal, and type-checked builders

Common Use Cases

• Writing codemods that rewrite a codebase’s API usage while preserving unrelated formatting
• Building custom lint-fix or refactoring tools that programmatically edit source files
• Powering higher-level codemod frameworks such as jscodeshift
• Generating or patching configuration/boilerplate files while respecting hand-written surrounding code

Under The Hood

Architecture recast’s core (lib/parser.ts, lib/printer.ts, lib/patcher.ts) parses source into an ast-types tree annotated with original token/location info, then on print() walks the tree (lib/fast-path.ts for efficient traversal) comparing each node against its original source slice; unchanged subtrees are copied verbatim from the original text via lib/lines.ts and lib/patcher.ts, while changed subtrees are regenerated by the pretty-printer and spliced back in. lib/comments.ts handles reattaching comments to the correct nodes after mutation.

Tech Stack Written in TypeScript, built with tsc, and built on top of the author’s own ast-types package for AST node definitions and traversal; supports pluggable parsers (Babel parser by default, with esprima/acorn/TypeScript/Flow parser adapters available).

Code Quality Uses a Mocha-based test suite (test/run.sh) combined with ESLint and Prettier enforced via npm test, and has 109 contributors with a long, incremental commit history dating back over a decade — though maintenance has slowed to infrequent updates in recent years relative to its enormous download volume (31M+ weekly).

API Design The two-function parse/print surface is minimal and well documented via the README’s worked examples, and its tight coupling to ast-types gives typed node builders instead of hand-built plain objects — but effective use requires understanding ast-types’ node shape conventions, which adds a real learning curve beyond the basic parse/print calls.