Skip to main content

​
Introduction

The TypeScript codebase is organized into a modular architecture designed to support both command-line compilation and rich IDE integration. This document provides an overview of the major components and their relationships.

​
Directory Structure

The TypeScript source code is organized under src/ with the following key directories:

​
Core Compiler (src/compiler/)

Scanner & Parser

Lexical analysis and syntax tree construction

Binder

Symbol creation and scope resolution

Checker

Type checking and semantic analysis

Emitter

JavaScript code generation
The compiler directory contains 77+ TypeScript files including:
  • scanner.ts (4,101 lines) - Tokenizes source code
  • parser.ts (10,823 lines) - Builds Abstract Syntax Trees
  • binder.ts (3,913 lines) - Creates symbols and control flow
  • checker.ts (54,434 lines) - The type checker (largest file)
  • emitter.ts (6,378 lines) - Generates JavaScript output
  • types.ts - Core type definitions and SyntaxKind enum
  • utilities.ts - Shared utility functions

​
Language Services (src/services/)

The services layer provides IDE features like autocompletion, navigation, and refactoring.
Contains 168+ TypeScript files organized into: Core Services:
  • completions.ts - Autocompletion engine
  • goToDefinition.ts - Symbol navigation
  • findAllReferences.ts - Symbol usage tracking
  • rename.ts - Symbol renaming
  • documentHighlights.ts - Occurrence highlighting
Formatting & Editing:
  • formatting/ - Code formatting rules
  • codefixes/ - Quick fixes for diagnostics
  • refactors/ - Refactoring operations
  • organizeImports.ts - Import statement organization
Analysis Features:
  • callHierarchy.ts - Call graph navigation
  • inlayHints.ts - Inline type hints
  • navigationBar.ts - File outline view

​
Language Server (src/server/ & src/tsserver/)

TSServer Protocol

The language server implements the editor communication protocol defined in protocol.ts
Provides the server-side implementation for editor integration:
  • Request/response handling
  • Session management
  • Project coordination

​
Supporting Modules

DirectoryPurpose
src/typescript/Public API exports
src/tsc/Command-line compiler
src/typingsInstaller/Automatic type acquisition
src/harness/Test infrastructure
src/lib/Built-in type definitions

​
Component Relationships

1

Source Input

Source files are read and passed to the Scanner
2

Lexical Analysis

Scanner tokenizes the input into a stream of tokens
3

Syntax Analysis

Parser constructs an Abstract Syntax Tree (AST)
4

Binding

Binder creates symbols and resolves scopes
5

Type Checking

Checker performs semantic analysis and type checking
6

Transformation

Transformers convert newer syntax to target version
7

Emission

Emitter generates JavaScript and declaration files

​
Compilation Pipeline

The compilation process follows this flow:
The checker (checker.ts) is the heart of the compiler, containing the type system implementation and spanning over 54,000 lines of code.

​
Language Service Architecture

The language service layer sits on top of the compiler and provides incremental, interactive features: 
// Services use the compiler's Program and TypeChecker
const program = createProgram(files, options);
const checker = program.getTypeChecker();
const sourceFile = program.getSourceFile(fileName);

// Services provide IDE features
const completions = getCompletionsAtPosition(...);
const definitions = getDefinitionAtPosition(...);
const references = findAllReferences(...);

​
Key Design Principles

AST nodes are immutable. Transformations create new nodes rather than modifying existing ones.
Type checking and symbol resolution happen on-demand to support incremental compilation.
Language service features work with text positions rather than requiring full AST traversal.
The forEachChild function enables efficient AST traversal and transformation.

​
Program and Type Checker

The Program interface (src/compiler/program.ts) is the central coordinator:

Program

  • Manages source files
  • Coordinates module resolution
  • Provides access to TypeChecker
  • Handles diagnostics collection

TypeChecker

  • Performs type inference
  • Resolves symbols
  • Checks type compatibility
  • Reports semantic errors

​
Transformers

The src/compiler/transformers/ directory contains transformation pipelines:
  • ES downleveling: es2015.ts, es2016.ts, es2017.ts, etc.
  • Feature transforms: jsx.ts, generators.ts, decorators.ts
  • Module transforms: module/ directory for various module formats
Transformers convert modern TypeScript/JavaScript syntax into code compatible with older runtimes.

​
Public API Surface

The src/typescript/ directory defines the public API exported to consumers: 
// Public API usage
import * as ts from 'typescript';

const program = ts.createProgram(fileNames, options);
const emitResult = program.emit();
const diagnostics = ts.getPreEmitDiagnostics(program);

​
Development Entry Points

1

Command-Line Compiler

Entry point: src/tsc/tsc.ts - Implements the tsc command
2

Language Server

Entry point: src/tsserver/tsserver.ts - Implements editor integration
3

Programmatic API

Entry point: src/typescript/typescript.ts - Public API exports

​
Next Steps

Compiler Internals

Deep dive into scanner, parser, binder, checker, and emitter

Language Service

How IDE features like completions and navigation work
The TypeScript codebase is highly optimized for performance. When contributing, be mindful of allocation patterns and traversal efficiency.

Build docs developers (and LLMs) love

Get started for freeTalk to us