This page documents the public TypeScript compiler API exposed through the typescript npm package. It covers the primary programmatic entry points for invoking the compiler, inspecting ASTs, and performing semantic analysis. For information about the language service API (editor features like completions and refactorings), see Language Service. For details on tsserver and the JSON protocol used by editors, see Language Server (tsserver).
The typescript package ships a single bundled module (lib/typescript.js) that exports everything under the ts namespace. The public surface is canonically defined in the generated declaration file at tests/baselines/reference/api/typescript.d.ts1-50
The API has three main uses:
| Use Case | Primary Entry Points |
|---|---|
| Full compilation (type-check + emit) | createProgram, Program.emit |
| Single-file parsing only | createSourceFile |
| Single-file transpilation (no type-check) | transpileModule |
| Editor / tooling integration | createLanguageService |
The diagram below maps user-facing API calls to the internal compiler components they drive.
Diagram: Public API Entry Points to Internal Components
Sources: src/compiler/program.ts264-265 src/services/services.ts212 src/compiler/checker.ts117 src/compiler/emitter.ts1-5
createProgramcreateProgram is the primary entry point for full compilations. It is defined in src/compiler/program.ts42-43 and documented in detail in Programmatic Compilation (createProgram and Hosts).
The returned Program object is the top-level handle for all subsequent operations. Its key methods include:
| Method | Description |
|---|---|
getSourceFiles() | Returns all SourceFile nodes in the program |
getTypeChecker() | Returns the TypeChecker for semantic queries |
emit() | Runs the emitter; returns EmitResult |
getSyntacticDiagnostics() | Parse-level errors |
getSemanticDiagnostics() | Type-level errors |
For details, see Programmatic Compilation (createProgram and Hosts).
Sources: src/compiler/program.ts264-265 tests/baselines/reference/api/typescript.d.ts3200-3350
createSourceFilecreateSourceFile parses a single source text string into a SourceFile AST node without creating a full Program. This is useful for tools that only need the parse tree.
Sources: src/compiler/parser.ts44-45 tests/baselines/reference/api/typescript.d.ts3380-3400
transpileModulePerforms single-file TypeScript-to-JavaScript transpilation with no cross-file type checking. This is significantly faster than createProgram for cases where semantic correctness is not required.
Sources: tests/baselines/reference/api/typescript.d.ts3400-3430
createLanguageServiceCreates an editor-facing LanguageService instance backed by a caller-supplied LanguageServiceHost. The host provides file contents and compiler options incrementally. See Language Service for a full treatment of these capabilities.
Sources: src/services/services.ts212-213 tests/baselines/reference/api/typescript.d.ts5000-5100
CompilerHost InterfaceCompilerHost is the file system and environment abstraction used by createProgram. Callers can supply a custom host to redirect file I/O (e.g. for in-memory compilation). A default host for Node.js is available via createCompilerHost(options).
Sources: src/compiler/types.ts30-31 src/compiler/program.ts25-26
Program Object and Compilation FlowDiagram: Program Lifecycle and Internal Calls
Sources: src/compiler/program.ts50 src/compiler/binder.ts47 src/compiler/checker.ts50 src/compiler/emitter.ts66
The compiler API exposes a rich set of interfaces for interacting with the code's structure and semantics:
For details, see AST, Types, Symbols, and Node Factory APIs.
Sources: src/compiler/types.ts40-492 src/compiler/checker.ts1-100
TypeCheckerThe TypeChecker is obtained from program.getTypeChecker(). It provides all semantic analysis queries, such as getSymbolAtLocation and getTypeAtLocation.
Diagram: TypeChecker Key Methods and What They Return
Sources: src/compiler/checker.ts1-1155 tests/baselines/reference/api/typescript.d.ts3000-3200
TypeScript provides a transformation pipeline for modifying ASTs and a printer for converting ASTs back into source text.
transform(): Applies a set of TransformerFactory functions to an AST.Printer: Converts a SourceFile or Node into a string.For details, see Using the Transform and Printer APIs.
Sources: src/compiler/emitter.ts1-100 tests/baselines/reference/api/typescript.d.ts3600-3800
BuilderProgram, see Incremental and Project Builds.Sources: src/services/services.ts212 src/server/session.ts190 src/compiler/program.ts9
Refresh this wiki