TypeScript compiler API basics - Deep Dive

Overview - TypeScript compiler API basics

What is it?

The TypeScript compiler API is a set of tools that lets programmers read, analyze, and transform TypeScript code using code. It allows you to write programs that understand TypeScript files, check their correctness, and even change them automatically. This API is like a bridge between your code and the TypeScript compiler's inner workings.

Why it matters

Without the TypeScript compiler API, developers would have to manually check or change TypeScript code, which is slow and error-prone. This API makes it possible to build tools like code editors, linters, and automatic refactoring helpers that save time and reduce mistakes. It helps keep large projects clean and consistent by automating code understanding and changes.

Where it fits

Before learning this, you should know basic TypeScript syntax and how to use the TypeScript compiler (tsc) from the command line. After this, you can explore advanced code analysis, custom lint rules, or building developer tools that integrate deeply with TypeScript.

Mental Model

Core Idea

The TypeScript compiler API lets your program read and change TypeScript code by working with its internal structure, like a map of the code's pieces.

Think of it like...

Imagine a book with chapters, paragraphs, and sentences. The compiler API lets you open the book, find any sentence, check if it makes sense, and even rewrite it without changing the whole book manually.

Source Code
  │
  ▼
Syntax Tree (AST) ──► Analysis & Transformation ──► New/Modified Code
  │
  ▼
Compiler API Functions

Build-Up - 7 Steps

1

Foundation

Understanding Abstract Syntax Trees

Concept: Learn what an Abstract Syntax Tree (AST) is and why it represents code structure.

When TypeScript code is compiled, it is first turned into a tree-like structure called an AST. Each node in this tree represents a piece of the code, like a variable, function, or expression. The compiler API lets you access and walk through this tree to understand or change the code.

Result

You can visualize code as a tree of nodes, each describing a part of the program.

Understanding that code is not just text but a structured tree is key to using the compiler API effectively.

2

Foundation

Setting Up the Compiler API Environment

Concept: Learn how to start using the TypeScript compiler API in a project.

To use the compiler API, you install TypeScript as a library and import its functions. Then you create a program object that represents your TypeScript files. This program lets you access the AST and other compiler features.

Result

You have a working setup where your code can read TypeScript files and their structure.

Knowing how to initialize the API is the first step to exploring and manipulating TypeScript code programmatically.

3

Intermediate

Navigating the Syntax Tree Nodes

🤔Before reading on: do you think each node in the AST has the same properties or different ones depending on the code part? Commit to your answer.

Concept: Learn how to walk through the AST nodes and understand their types.

Each node in the AST has a kind that tells you what it represents, like a function or a variable. You can use functions like forEachChild to visit each node and check its kind to decide what to do. This helps you find specific code parts to analyze or change.

Result

You can write code that visits every part of a TypeScript file and reacts differently based on node types.

Knowing how to traverse and identify nodes unlocks the ability to analyze or transform code precisely.

4

Intermediate

Using Type Checker for Semantic Info

🤔Before reading on: do you think the syntax tree alone tells you the types of variables, or do you need extra tools? Commit to your answer.

Concept: Learn how to get type information from the compiler API using the type checker.

The syntax tree shows code structure but not the meaning of types. The compiler API provides a type checker that can tell you the type of any expression or symbol. You get the type checker from the program and ask it about nodes to understand their types and relationships.

Result

You can find out if a variable is a string, number, or a custom type, enabling smarter code analysis.

Understanding that syntax and semantics are separate helps you build tools that check code correctness beyond just structure.

5

Intermediate

Creating and Applying Code Transformations

🤔Before reading on: do you think you can change code by editing text directly or by changing the AST nodes? Commit to your answer.

Concept: Learn how to write code that changes TypeScript code by modifying the AST and printing new code.

Instead of editing code as text, you create new AST nodes or modify existing ones. Then you use the printer API to turn the AST back into code text. This method is safer and keeps code formatting consistent. You write transformer functions that receive nodes and return changed nodes.

Result

You can automatically rename variables, add imports, or fix code patterns programmatically.

Knowing how to transform code via the AST is powerful for building automated refactoring tools.

6

Advanced

Handling Source Files and Program Structure

🤔Before reading on: do you think the compiler API works on one file at a time or understands whole projects? Commit to your answer.

Concept: Learn how the compiler API manages multiple files and project settings.

The program object represents the entire project, including all source files and compiler options. It understands dependencies between files and can provide diagnostics for the whole project. You can get source files from the program and analyze or transform them collectively.

Result

You can build tools that work on large projects, respecting project settings and file relations.

Understanding project-wide context is essential for tools that need to analyze or change code safely across many files.

7

Expert

Custom Transformers and Compiler Integration

🤔Before reading on: do you think custom transformers run before or after type checking? Commit to your answer.

Concept: Learn how to create custom transformers that integrate into the TypeScript compilation process.

Custom transformers are functions that modify the AST during compilation. They can run before or after type checking, depending on how you configure them. This allows you to add new syntax features, enforce rules, or optimize code. Integrating transformers requires understanding compiler phases and how to hook into them.

Result

You can extend the TypeScript compiler with your own code modifications during build time.

Knowing how to integrate custom transformers unlocks advanced customization and optimization possibilities in TypeScript projects.

Under the Hood

The TypeScript compiler API works by parsing source code into an Abstract Syntax Tree (AST), a detailed tree structure representing every part of the code. It then uses a type checker to analyze the AST nodes and assign types and symbols, enabling semantic understanding. The API exposes functions to traverse, inspect, and modify this AST. When changes are made, a printer converts the AST back into source code text. The compiler API also manages project-wide information, including multiple files and compiler options, to provide accurate diagnostics and transformations.

Why designed this way?

The API was designed to expose the compiler's internal structures to enable powerful tooling beyond simple compilation. By separating syntax parsing, semantic analysis, and code generation, it allows precise control and safe transformations. Alternatives like text-based manipulation were error-prone and limited. The design balances flexibility with safety, enabling tools like editors, linters, and custom compilers to build on a stable foundation.

Source Code
  │
  ▼
Parser ──► AST (Syntax Tree)
  │          │
  ▼          ▼
Type Checker  Transformer Functions
  │          │
  ▼          ▼
Semantic Info Modified AST
  │
  ▼
Printer ──► Output Code

Myth Busters - 4 Common Misconceptions

Quick: Does the compiler API let you run TypeScript code directly? Commit to yes or no.

Common Belief: The compiler API runs TypeScript code like a normal program.

Reality: The compiler API only reads, analyzes, and transforms code; it does not execute it.

Why it matters: Confusing analysis with execution can lead to wrong assumptions about what the API can do, causing wasted effort trying to run code through it.

Quick: Do you think modifying the AST nodes directly always changes the source files on disk? Commit to yes or no.

Common Belief: Changing AST nodes automatically updates the original source files.

Reality: Modifying AST nodes only changes the in-memory representation; you must print and save the code yourself.

Why it matters: Assuming automatic file updates can cause confusion when changes don't appear in files, leading to debugging frustration.

Quick: Do you think the syntax tree alone tells you the types of variables? Commit to yes or no.

Common Belief: The AST contains all type information about the code.

Reality: Type information comes from the type checker, which analyzes the AST with compiler rules and project context.

Why it matters: Ignoring the type checker limits your ability to build tools that understand code meaning, not just structure.

Quick: Can you use the compiler API without understanding TypeScript syntax? Commit to yes or no.

Common Belief: You can use the compiler API effectively without knowing TypeScript syntax.

Reality: Understanding TypeScript syntax is essential because the API works with code structure and types you must recognize.

Why it matters: Lack of syntax knowledge leads to confusion when interpreting AST nodes and writing transformations.

Expert Zone

1

The compiler API's AST nodes are immutable in practice; transformations create new nodes rather than changing existing ones, which prevents side effects.

2

Custom transformers can run at different compilation phases, affecting what information is available and how changes impact type checking.

3

Source maps can be generated alongside transformations to keep debugging accurate, but require careful handling of node positions.

When NOT to use

Avoid using the compiler API for simple text replacements or small scripts where regular expressions suffice. For runtime code execution or dynamic evaluation, use JavaScript engines or runtime tools instead. Also, for very large projects, the API can be slow; consider incremental or cached analysis tools.

Production Patterns

In production, the compiler API is used to build linters like ESLint plugins, code formatters, automated refactoring tools, and custom build pipelines. It integrates with editors to provide real-time feedback and with CI systems to enforce code quality. Advanced users write custom transformers to add new language features or optimize code during compilation.

Connections

Abstract Syntax Trees (ASTs) in Compilers

Builds-on

Knowing general AST concepts from compiler theory helps understand how the TypeScript compiler API represents and manipulates code.

Static Code Analysis

Same pattern

The compiler API is a practical tool for static analysis, which checks code without running it, enabling bug detection and style enforcement.

Document Object Model (DOM) in Web Browsers

Similar structure

Both the compiler API's AST and the DOM represent hierarchical structures that can be traversed and modified, showing a common pattern in software for handling complex data.

Common Pitfalls

#1 Trying to modify source code by changing AST nodes without printing and saving the new code.

Wrong approach:

const newNode = ts.updateVariableDeclaration(oldNode, newName);
// Assume file is changed automatically

Correct approach:

const newNode = ts.updateVariableDeclaration(oldNode, newName);
const printer = ts.createPrinter();
const newCode = printer.printFile(sourceFile);
fs.writeFileSync('file.ts', newCode);

Root cause:

Misunderstanding that AST changes are in-memory only and require explicit code generation and file writing.

#2 Using the compiler API without initializing a program or type checker, leading to missing semantic info.

Wrong approach:

const sourceFile = ts.createSourceFile('file.ts', code, ts.ScriptTarget.Latest);
// Try to get type info without program or checker

Correct approach:

const program = ts.createProgram(['file.ts'], {});
const checker = program.getTypeChecker();
const sourceFile = program.getSourceFile('file.ts');

Root cause:

Not realizing that semantic analysis requires a program context and type checker.

#3 Assuming all AST nodes have the same properties and trying to access missing ones directly.

Wrong approach:

if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
console.log(node.name.text);
} else {
console.log(node.name.text); // Error if node has no name
}

Correct approach:

if (node.kind === ts.SyntaxKind.FunctionDeclaration && node.name) {
console.log(node.name.text);
}

Root cause:

Not checking node kinds and properties carefully before accessing them.

Key Takeaways

The TypeScript compiler API lets you work with code as a structured tree, not just text, enabling powerful analysis and transformation.

Separating syntax (AST) and semantics (type checking) is essential to understand and use the API effectively.

Modifying code requires creating new AST nodes and printing them back to source code explicitly.

The API manages whole projects, allowing tools to work across multiple files with full context.

Advanced use includes custom transformers that integrate deeply into the compilation process for powerful code customization.

Practice

1.

What is the primary purpose of the TypeScript compiler API?

SourceFile is a key part of it. What does it help you do?

easy

A. Run TypeScript code directly in the browser

B. Read and modify TypeScript code programmatically

C. Convert TypeScript to JavaScript manually

D. Create user interfaces with TypeScript

Solution

1. Step 1: Understand the role of the compiler API

   The TypeScript compiler API is designed to let programs read and change TypeScript code, not to run it or build UI.

2. Step 2: Identify what SourceFile represents

   SourceFile is an object representing the code text, allowing exploration and modification.

3. Final Answer:

   Read and modify TypeScript code programmatically -> Option B

4. Quick Check:

   Compiler API = Code reading and modification [OK]

Hint: Remember: compiler API reads and changes code, not runs it [OK]

Common Mistakes:

• Thinking it runs TypeScript code directly
• Confusing it with UI libraries
• Assuming it manually converts code without automation

2.

Which of the following is the correct way to create a SourceFile using the TypeScript compiler API?

const sourceFile = ts.createSourceFile(____);

easy

A. (codeText, ts.ScriptTarget.Latest)

B. ('file.ts', codeText)

C. (codeText, 'file.ts', ts.ScriptTarget.Latest)

D. ('file.ts', codeText, ts.ScriptTarget.Latest)

Solution

1. Step 1: Recall the createSourceFile signature

   The method requires filename, source text, and script target in that order.

2. Step 2: Match the correct argument order

   ('file.ts', codeText, ts.ScriptTarget.Latest) correctly uses ('file.ts', codeText, ts.ScriptTarget.Latest).

3. Final Answer:

   ('file.ts', codeText, ts.ScriptTarget.Latest) -> Option D

4. Quick Check:

   Filename, text, target order = A [OK]

Hint: Filename first, then code text, then script target [OK]

Common Mistakes:

• Swapping filename and code text
• Omitting the script target argument
• Passing arguments in wrong order

3.

Given this code snippet using the TypeScript compiler API:

const sourceFile = ts.createSourceFile('test.ts', 'let x = 5;', ts.ScriptTarget.Latest);
const firstStatement = sourceFile.statements[0];
console.log(firstStatement.kind);

What will be printed?

medium

A. SyntaxKind.VariableStatement

B. 5

C. SyntaxKind.Identifier

D. undefined

Solution

1. Step 1: Understand what sourceFile.statements[0] is

   The first statement is let x = 5;, which is a variable declaration statement.

2. Step 2: Identify the kind of this statement

   Its kind is SyntaxKind.VariableStatement, a numeric enum value representing variable statements.

3. Final Answer:

   SyntaxKind.VariableStatement -> Option A

4. Quick Check:

   First statement kind = VariableStatement [OK]

Hint: Statements array holds top-level code pieces; kind shows their type [OK]

Common Mistakes:

• Expecting the value 5 to be printed
• Confusing statement kind with identifier kind
• Assuming undefined because of missing imports

4.

Consider this code snippet:

const sourceFile = ts.createSourceFile('file.ts', 'const a = 10;', ts.ScriptTarget.Latest);
const firstStatement = sourceFile.statements[0];
console.log(firstStatement.name.text);

What is the error in this code?

medium

A. firstStatement has no property name

B. sourceFile is not created correctly

C. text is not a valid property

D. No error, code runs fine

Solution

1. Step 1: Check the type of firstStatement

   firstStatement is a VariableStatement node, which does not have a direct name property.

2. Step 2: Understand how to access variable name

   The variable name is inside firstStatement.declarationList.declarations[0].name, not directly on firstStatement.

3. Final Answer:

   firstStatement has no property name -> Option A

4. Quick Check:

   VariableStatement lacks direct name property [OK]

Hint: Variable names are nested inside declarations, not on statement directly [OK]

Common Mistakes:

• Accessing name directly on VariableStatement
• Assuming sourceFile creation is wrong
• Confusing property names on nodes

5.

You want to write a function using the TypeScript compiler API that extracts all variable names from a given source code string. Which approach is best?

1. Create a SourceFile from the code string.
2. Traverse its statements and declarations.
3. Collect names from variable declarations.

Which code snippet correctly starts this process?

function getVariableNames(code: string): string[] {
  const sourceFile = ts.createSourceFile('temp.ts', code, ts.ScriptTarget.Latest);
  const names: string[] = [];
  sourceFile.statements.forEach(statement => {
    if (ts.isVariableStatement(statement)) {
      statement.declarationList.declarations.forEach(decl => {
        if (ts.isIdentifier(decl.name)) {
          names.push(decl.name.text);
        }
      });
    }
  });
  return names;
}

hard

A. Incorrect because it uses forEach on a non-iterable

B. Fails because it does not parse the code into a SourceFile

C. Correctly traverses variable declarations and extracts names

D. Wrong because it pushes declaration nodes instead of names

Solution

1. Step 1: Verify SourceFile creation

   The code correctly creates a SourceFile from the input string.

2. Step 2: Check traversal and extraction logic

   It loops over statements, filters variable statements, then loops declarations to extract identifier names properly.

3. Final Answer:

   Correctly traverses variable declarations and extracts names -> Option C

4. Quick Check:

   Traversal and extraction logic is correct [OK]

Hint: Traverse statements, check variable statements, then extract names [OK]

Common Mistakes:

• Not creating SourceFile before traversal
• Trying to loop on non-iterable objects
• Pushing nodes instead of text names