Skip to content
Tutorials Center
My learning

Topics

Lesson 61 of 96 ยท Modern Features

Compiler API and Custom Transformers

Learn how the TypeScript compiler API works with programs, source files, the AST, the type checker, visitors, transformers and codemods, with runnable AST and type-stripping examples.

The tsc command is only one front end for the TypeScript compiler. Behind it sits a library that can read your code, build a tree of what it means, answer questions about types and rewrite the result. Tools you use every day, from editors and linters to documentation generators and code-modification scripts ("codemods"), are built on it. Knowing how the pieces fit together turns "the compiler is magic" into "the compiler is a program I can call."

This lesson explains the main ideas: programs, source files, the abstract syntax tree (AST), the type checker, visitors, and transformers. The compiler package isn't available in our in-browser runner, so the TypeScript API snippets are read-only. The runnable examples show the same concepts with a hand-built AST and with Node's own type-stripping function.

TypeScript 7 moves the compiler into a native executable, which is why tsc is so much faster. The long-established JavaScript API shown here (import ts from 'typescript') comes from the 6.x line of the package, and many tools still depend on it. A programmatic API for the native compiler is evolving separately, so check the release notes for your version before you build on it. The concepts below (programs, ASTs, checkers, transforms) are the same in both.

From text to types: the compiler pipeline

Every run of the compiler goes through the same stages:

flowchart LR
  A["Source text<br/>.ts files"] --> B["Scanner<br/>tokens"]
  B --> C["Parser<br/>AST (SourceFile)"]
  C --> D["Binder<br/>symbols"]
  D --> E["Checker<br/>types and errors"]
  E --> F["Emitter<br/>.js and .d.ts"]

The scanner and parser create the tree; the binder and checker add meaning; the emitter writes output.

The scanner splits text into tokens (const, x, =, 5). The parser arranges the tokens into a tree. The binder connects declarations with their uses (this x is that x). The checker works out the type of everything and reports errors. The emitter prints JavaScript and declaration files, and it's where transformers hook in.

What an AST looks like

An AST is a tree where every node has a kind and children. Take this line:

TypeScript
const total = price * 2;

The parser turns it into something like this (simplified):

TEXT
VariableStatement
  VariableDeclaration  name: Identifier "total"
    initializer: BinaryExpression  operator: *
      left:  Identifier "price"
      right: NumericLiteral 2

The real compiler has about 400 node kinds (SyntaxKind.Identifier, SyntaxKind.CallExpression, SyntaxKind.InterfaceDeclaration, and so on). Because the AST keeps the structure and positions of the code, a tool can find every call to a function or rename a variable without text search, which would also match comments and strings.

The first example builds a tiny AST by hand for a toy expression language and walks it with a visitor, the same pattern the compiler API uses. It's a stand-in, much smaller than the real thing, but the shape is identical: nodes with a kind, a recursive walk and a function that decides what to do per kind.

TypeScript A toy AST: walk it and write a codemod

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Three ideas to carry over to the real API. First, the visitor walks the tree and the callback sees every node. Second, a transformer returns a new tree instead of editing the old one, which keeps rewrites predictable. Third, a printer turns the tree back into text. Because Node is a discriminated union, the switch is exhaustively checked: add a new node kind and print stops compiling until you handle it.

Programs, source files and the checker

With the real API, the entry point is a program: a set of root files plus compiler options, from which the compiler loads every imported file.

TypeScript
import ts from 'typescript';

const program = ts.createProgram(['src/index.ts'], {
  target: ts.ScriptTarget.ES2024,
  module: ts.ModuleKind.NodeNext,
  strict: true,
  noEmit: true,
});

// 1. Diagnostics: the same errors tsc would print
const diagnostics = ts.getPreEmitDiagnostics(program);
for (const d of diagnostics) {
  console.log(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
}

// 2. The type checker answers questions about types
const checker = program.getTypeChecker();
const file = program.getSourceFile('src/index.ts')!;

ts.forEachChild(file, function walk(node) {
  if (ts.isVariableDeclaration(node)) {
    const type = checker.getTypeAtLocation(node.name);
    console.log(node.name.getText(), ':', checker.typeToString(type));
  }
  ts.forEachChild(node, walk);
});

ts.forEachChild is the built-in visitor. The ts.isVariableDeclaration, ts.isCallExpression and similar functions are type guards: after the check, TypeScript narrows node to the specific node type, so node.name and node.initializer are typed. The checker is what separates this from a text parser: checker.getTypeAtLocation(node) tells you what TypeScript inferred, including inferred types you never wrote.

To parse a string without building a whole program (fast, no type information), use ts.createSourceFile:

TypeScript
const source = ts.createSourceFile(
  'example.ts',
  'export const answer: number = 42;',
  ts.ScriptTarget.Latest,
  /* setParentNodes */ true,
);

Set setParentNodes to true if you want to use node.parent, getText() and similar helpers.

Custom transformers

The compiler can run your function on the AST during emit. A transformer is a factory that receives a context and returns a function for each source file:

TypeScript
import ts from 'typescript';

// Replaces every `__BUILD_YEAR__` identifier with a number literal
const buildYear: ts.TransformerFactory<ts.SourceFile> = (context) => (sourceFile) => {
  const visitor = (node: ts.Node): ts.Node => {
    if (ts.isIdentifier(node) && node.text === '__BUILD_YEAR__') {
      return context.factory.createNumericLiteral(new Date().getFullYear());
    }
    return ts.visitEachChild(node, visitor, context);
  };
  return ts.visitNode(sourceFile, visitor) as ts.SourceFile;
};

const result = program.emit(undefined, undefined, undefined, false, {
  before: [buildYear], // run before TypeScript's own transforms
});

There are three slots: before (your code runs on TypeScript source, before types are removed), after (on the JavaScript) and afterDeclarations (on the .d.ts output). This is the mechanism behind tools that add dependency-injection metadata, remove debug calls or generate code from types. Use context.factory.create... to build new nodes, and never mutate existing nodes in place.

Note that plain tsc can't load transformers from a config file; you need a wrapper tool (or you call program.emit yourself, as above). This is also why many projects choose build-time tools like Babel or SWC plugins, or code generation, instead.

Codemods: automated refactors

A codemod applies a refactor to many files. Typical tasks include renaming an API after a breaking upgrade, replacing a deprecated call or adding import type. Two common approaches:

  • ts-morph wraps the compiler API in a friendlier object model (project.getSourceFiles(), node.rename(...), addImportDeclaration(...)) and saves the edited files back to disk.
  • jscodeshift and similar tools use other parsers and are good for JavaScript-heavy migrations.

A safe codemod workflow is the same as for any refactor: run it on a clean git branch, review the diff, let the type checker and the tests prove the result, and keep the script in the repository if the migration will be needed again.

Stripping types with Node

One transform doesn't need the compiler package at all. Node 24 has a built-in function that removes TypeScript syntax and keeps everything else in place, which is how it runs .ts files directly. It performs no type checking:

TypeScript Stripping types with node:module

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

It prints (Node also writes an experimental-feature warning to stderr):

TEXT
export function distance(a       , b       )         {
  return Math.hypot(a.x - b.x, a.y - b.y);
}
--- type error ignored, because nothing is checked ---
const n         = "oops";

The interface and annotations are replaced with whitespace, so line and column numbers in the output still match your source. That is the key difference from the full compiler: stripping is purely syntactic. The const n: number = "oops" line passes straight through, which is why a separate tsc --noEmit step stays essential (see Tooling and Node.js and TypeScript). Features that generate code, such as enum and namespace, aren't erasable, so Node's stripping rejects them unless you enable its transform mode.

Before writing a transformer, ask whether a simpler tool already solves it: a lint rule with an auto-fix (typescript-eslint), a build-tool plugin, a code generator that reads your types, or a plain search and replace with a type-check afterwards. The compiler API is powerful, but every program you build on it must follow compiler version changes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is an AST?

    The parser turns source text into an abstract syntax tree. Tools walk and rewrite that tree instead of searching raw text.
  2. 2. Which part of the compiler can tell you the inferred type of an expression?

    createSourceFile only parses. The checker needs a program (with all imported files) to compute types, for example with getTypeAtLocation.
  3. 3. Why does a transformer return a new node instead of editing the old one?

    Nodes are treated as immutable. Visitors return replacements and the factory builds new nodes, so the original tree is never half-edited.
  4. 4. What does Node's stripTypeScriptTypes do with const n: number = "oops";?

    Stripping is syntactic only. Type errors remain until tsc (or an editor) checks the code.
  5. 5. Which statement about a codemod is best practice?

    Codemods change many files at once. A clean branch and a reviewed diff make them reversible, and the type checker plus tests confirm nothing broke.

Summary

  • The compiler pipeline is scanner, parser, binder, checker and emitter; the parser's output is the AST.
  • With the JavaScript API, ts.createProgram loads files, program.getTypeChecker() answers type questions and ts.createSourceFile parses a single string.
  • ts.forEachChild and ts.isXxx type guards let you walk and narrow nodes; a visitor looks at nodes, a transformer returns replacements built with context.factory.
  • Transformers run during program.emit in the before, after or afterDeclarations slots, and plain tsc cannot load them from tsconfig.json.
  • Codemods (ts-morph, jscodeshift) automate large refactors; verify them with the type checker and tests.
  • Node's stripTypeScriptTypes removes types without checking them, so keep running tsc --noEmit.

Next: Node.js and TypeScript