The TypeScript repository contains the complete implementation of the TypeScript compiler, language services, language server (tsserver), standard library declaration files, and the build/test infrastructure that supports all of them.
The public npm package (typescript) exposes the compiler API via lib/typescript.js and lib/typescript.d.ts. The tsc and tsserver binaries are entry points in bin/.
| Area | Directory | Key Entry Points |
|---|---|---|
| Compiler | src/compiler/ | createProgram, createTypeChecker, emitFiles |
| Language Service | src/services/ | createLanguageService, DocumentRegistry |
| Language Server | src/server/ | Session, ProjectService |
| Standard Library | src/lib/ | lib.es5.d.ts, lib.dom.d.ts, etc. |
| Test Harness | src/harness/ | harnessLanguageService.ts, compiler test utilities |
| Test Cases | tests/cases/ | fourslash/, compiler/, tsserver/ |
| Test Baselines | tests/baselines/reference/ | .js, .d.ts, .errors.txt, .symbols, .types |
| Build System | Herebyfile.mjs | hereby local, hereby runtests, hereby lkg |
Sources: package.json1-40 src/compiler/program.ts1-50 src/services/services.ts1-50 src/server/session.ts1-50
The following diagram maps the major runtime systems to their primary source files and exported API surfaces.
System Map: Code Entities
Sources: src/compiler/program.ts1-100 src/compiler/checker.ts1-100 src/compiler/emitter.ts1-100 src/services/services.ts1-100 src/server/session.ts1-100 src/server/editorServices.ts1-100
Compilation Pipeline
Sources: src/compiler/program.ts1-100 src/compiler/scanner.ts1-50 src/compiler/parser.ts1-100 src/compiler/binder.ts1-100 src/compiler/checker.ts1-100 src/compiler/emitter.ts1-100
The compiler transforms TypeScript source into JavaScript through a multi-stage pipeline. The Program object (created by createProgram in src/compiler/program.ts) is the top-level orchestrator. It manages source files, compiler options, module resolution, and provides access to the TypeChecker.
| Stage | File | Key Function / Type |
|---|---|---|
| Scanning | src/compiler/scanner.ts | createScanner(), SyntaxKind |
| Parsing | src/compiler/parser.ts | createSourceFile(), SourceFile, Node |
| Binding | src/compiler/binder.ts | bindSourceFile(), Symbol, SymbolTable, FlowNode |
| Type Checking | src/compiler/checker.ts | createTypeChecker(), TypeChecker, Type, TypeFlags |
| Transformation | src/compiler/transformer.ts | transformNodes(), TransformationContext |
| Emit | src/compiler/emitter.ts | emitFiles(), Printer, EmitFlags |
Core type definitions shared across all stages live in src/compiler/types.ts, which defines SyntaxKind, NodeFlags, TypeFlags, SymbolFlags, ModifierFlags, and all AST node interfaces.
See page 2 for Compiler Architecture details, and pages 2.1–2.5 for each pipeline stage.
Sources: src/compiler/types.ts40-492 src/compiler/program.ts1-100 src/compiler/checker.ts1-200
Between type checking and emit, the compiler runs a series of transformers that downlevel TypeScript-specific syntax and modern ECMAScript features. The pipeline is driven by transformNodes in src/compiler/transformer.ts, with individual transformers in src/compiler/transformers/. Transformers operate on the AST using a visitor pattern via TransformationContext and NodeFactory.
Sources: src/compiler/emitter.ts395-430
The language service is the layer that powers editor features. createLanguageService in src/services/services.ts is its primary entry point, returning a LanguageService object. It wraps a Program and TypeChecker and provides:
| Feature | File |
|---|---|
| Code completions | src/services/completions.ts |
| Code fixes | src/services/codefix.ts + src/services/codefixes/ |
| Refactorings | src/services/refactors/ |
| Formatting | src/services/formatting/ |
| Find all references / rename | src/services/findAllReferences.ts |
| Navigation | src/services/navigationBar.ts, src/services/navigateTo.ts |
| Signature help | src/services/signatureHelp.ts |
| Inlay hints | src/services/inlayHints.ts |
| Organize imports | src/services/organizeImports.ts |
The DocumentRegistry (createDocumentRegistry in src/services/documentRegistry.ts) caches and shares SourceFile objects across multiple language service instances.
See page 4 and pages 4.1–4.10 for language service details.
Sources: src/services/services.ts362-370 src/services/types.ts1-100
tsserver is a long-running Node.js process that editors communicate with via a JSON-based protocol. Its architecture:
Session (src/server/session.ts): Receives JSON requests, dispatches to handlers, writes JSON responses. Entry point for all protocol messages.ProjectService (src/server/editorServices.ts): Manages the lifecycle of projects and open files. Creates and owns Project instances.Project (src/server/project.ts): Wraps a LanguageService instance. Three project kinds: ConfiguredProject (tsconfig.json-based), InferredProject (loose files), ExternalProject (client-defined).The tsserver binary is at bin/tsserver and boots via src/server/server.ts.
See page 5 for tsserver architecture, page 5.1 for the protocol, and page 5.2 for project management.
Sources: src/server/session.ts1-100 src/server/editorServices.ts1-150 src/server/project.ts1-50
src/lib/ contains the .d.ts declaration files that describe the JavaScript runtime environment. The lib compiler option selects which files are included. Files are organized by ECMAScript version and environment:
lib.es5.d.ts, lib.es2015.d.ts, … lib.esnext.d.ts — ECMAScript built-inslib.dom.d.ts, lib.dom.iterable.d.ts — Browser DOM APIs (generated from web standards)lib.webworker.d.ts — Web Worker APIsSee pages 6.1 and 6.2 for details.
Sources: src/compiler/utilities.ts417-418
The typescript npm package exposes a public API via lib/typescript.js. Primary entry points include createProgram, createLanguageService, createSourceFile, and transpileModule. The TypeChecker interface exposes symbol resolution, type queries, and diagnostic collection. See page 7 for usage patterns.
Sources: tests/baselines/reference/api/typescript.d.ts1-100
BuilderProgram and BuilderState in src/compiler/builder.ts implement incremental compilation by tracking file versions, signatures, and a dependency graph (referencedMap). The solution builder in src/compiler/tsbuild.ts handles multi-project builds with project references. See page 8.
Sources: src/compiler/program.ts1-50
Diagram: CI workflow job structure as defined in .github/workflows/ci.yml
The main CI pipeline in .github/workflows/ci.yml spawns 12+ parallel jobs that must all pass before code can merge. The test job runs a matrix of 15 OS/Node.js version combinations spanning Ubuntu, Windows, and macOS on Node.js versions 14-24. The required job aggregates all results and serves as the final merge gate.
Sources: .github/workflows/ci.yml1-449
| Job Name | Runner | Key Commands | Purpose |
|---|---|---|---|
test | ubuntu-latest, windows-latest, macos-latest | npm run test -- --no-lint --bundle=true | Execute full test suite on OS/Node matrix |
coverage | self-hosted (1ES.Pool) | npm test -- --no-lint --coverage | Generate and upload coverage to Codecov |
lint | ubuntu-latest | npm run lint | ESLint validation |
knip | ubuntu-latest | npm run knip | Detect unused exports |
format | ubuntu-latest | npx dprint check | Format validation |
browser-integration | ubuntu-latest | npx hereby test-browser-integration | Browser import tests with Playwright |
typecheck | ubuntu-latest | npx hereby build-src | TypeScript type checking |
smoke | ubuntu-latest | npx hereby lkg + npx tsc --version | Package installation and CLI validation |
package-size | ubuntu-latest | node ./scripts/checkPackageSize.mjs | Compare package size vs base branch |
misc | ubuntu-latest | npx hereby run-eslint-rules-tests | ESLint plugin tests |
self-check | ubuntu-latest | npx hereby build-src --built | Bootstrap compiler build |
baselines | ubuntu-latest | npx hereby baseline-accept + diff check | Validate baselines are current |
required | ubuntu-latest | Aggregates all job results | Final merge gate |
Sources: .github/workflows/ci.yml27-449
The test job runs across a matrix defined in .github/workflows/ci.yml28-118:
--no-bundle flag (skipped in merge queues)The matrix uses fail-fast: ${{ github.event_name == 'merge_group' }} to optimize merge queue execution by failing fast, while allowing full execution for PRs to identify all issues.
Sources: .github/workflows/ci.yml28-119
The TypeScript package is distributed through two npm channels:
Insiders Channel (@insiders tag): Daily builds from the main branch published via .github/workflows/insiders.yaml. These builds are triggered manually or by repository dispatch events. The workflow runs the full test suite, configures the package for insiders with npx hereby configure-insiders, builds LKG with npx hereby LKG, and publishes with npm publish --tag insiders.
Release Channel (@latest tag): Stable releases from release-* branches managed through .github/workflows/new-release-branch.yaml and .github/workflows/lkg.yml. Release branches are created manually, version numbers are updated, and the Last Known Good (LKG) build in the lib/ directory is updated before publication.
Sources: .github/workflows/insiders.yaml1-66
Diagram: Insiders publishing workflow as defined in .github/workflows/insiders.yaml
The insiders workflow in .github/workflows/insiders.yaml consists of two sequential jobs:
Both jobs require github.repository == 'microsoft/TypeScript' to prevent execution in forks.
Sources: .github/workflows/insiders.yaml1-66
The repository provides a complete development environment through Dev Containers defined in .devcontainer/devcontainer.json:
Base Image: mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm (Node.js 22 on Debian Bookworm)
Additional Features:
ghcr.io/devcontainers/features/go:1 (for pprof profiling tool)Post-Create Commands .devcontainer/devcontainer.json17-21:
sudo npm install -g hereby
npm ci
go install github.com/google/pprof@latest
sudo apt install graphviz
VS Code Extensions .devcontainer/devcontainer.json35-38:
dbaeumer.vscode-eslint: ESLint integrationdprint.dprint: dprint formatter integrationThe container runs as the node user (non-root) for security.
Sources: .devcontainer/devcontainer.json1-44
| Tool | Installation | Purpose |
|---|---|---|
hereby | npm install -g hereby | Task runner for build automation |
npm | Included in base image | Package manager and script executor |
pprof | go install github.com/google/pprof@latest | Performance profiling |
graphviz | sudo apt install graphviz | Graph visualization for profiling |
eslint | Via npm ci | JavaScript/TypeScript linting |
dprint | Via npm ci | Fast code formatting |
Sources: .devcontainer/devcontainer.json17-21
The repository enforces multiple quality gates before code can merge:
Linting: ESLint rules enforce code style and catch common mistakes. Run with npx hereby lint locally or automatically in the lint job .github/workflows/ci.yml178-189
Formatting: dprint enforces consistent code formatting. Configuration in .dprint.jsonc defines formatting rules for TypeScript, JavaScript, JSON, and Markdown files. Validated in the format job .github/workflows/ci.yml204-222
Coverage: c8 measures test coverage and uploads results to Codecov. Configuration in .c8rc.json defines coverage thresholds and excluded files. Run in the coverage job .github/workflows/ci.yml144-177
Security: CodeQL performs security scanning with configuration in .github/codeql/. The workflow analyzes code for security vulnerabilities and common programming errors.
Unused Exports: Knip detects unused exports and dependencies. Run in the knip job .github/workflows/ci.yml191-202
Sources: .github/workflows/ci.yml144-222
The baseline system tracks expected test outputs in tests/baselines/reference/. When compiler behavior changes, test outputs change, and baselines must be updated.
Local Workflow:
npx hereby runtestsnpx hereby baseline-acceptCI Validation: The baselines job .github/workflows/ci.yml378-424 ensures baselines remain current by:
rm -rf tests/baselines/referencenpm testnpx hereby baseline-acceptgit diff --stagedIf baselines are out of sync, the job uploads a fix_baselines.patch artifact containing the required changes.
Sources: .github/workflows/ci.yml378-424 .github/copilot-instructions.md22
The hereby task runner orchestrates all build and test operations. Common tasks defined in Herebyfile.mjs:
local: Build compiler to built/local/clean: Remove build artifactstests: Build test infrastructureruntests: Execute test suiteruntests-parallel: Execute tests in parallelbaseline-accept: Accept new test baselineslint: Run ESLintformat: Run dprint formattinglkg: Build Last Known Good for releaseThese tasks are used both locally by developers and in CI jobs to ensure consistent build behavior.
Sources: .github/copilot-instructions.md13-25
Diagram: Integration flow from local development through CI to npm publication
Code flows from local development through PR validation in ci.yml, merges to main or release branches, and publishes to npm through automated workflows. The hereby commands used locally are the same commands executed in CI, ensuring consistency between local and CI environments.
Sources: .github/workflows/ci.yml1-449 .github/workflows/insiders.yaml1-66
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.