TypeScript Administrator & Developer Guide

1. Architecture Overview

TypeScript is a statically-typed superset of JavaScript that compiles to plain JavaScript. It consists of three major subsystems: a compiler (tsc) that performs type checking and code emission, a language service that powers IDE features like IntelliSense and refactoring, and a language server (tsserver) that exposes the language service over a JSON-based protocol to editors.

Architecture Diagram

                            ┌─────────────────────────────────────┐
                            │           tsconfig.json             │
                            │        (project configuration)      │
                            └──────────────┬──────────────────────┘
                                           │
         ┌─────────────────────────────────┼─────────────────────────────┐
         │                                 │                             │
         ▼                                 ▼                             ▼
┌─────────────────┐             ┌───────────────────┐          ┌─────────────────┐
│    tsc (CLI)    │             │  Language Service  │          │    tsserver      │
│  src/tsc/       │             │  src/services/     │          │  src/server/     │
│                 │             │                    │          │  src/tsserver/   │
│  executeCommand │             │  completions       │          │                  │
│  Line()         │             │  diagnostics       │◄────────►│  Session         │
│                 │             │  refactoring       │          │  (JSON protocol) │
│                 │             │  navigation        │          │                  │
└────────┬────────┘             │  formatting        │          │  Projects        │
         │                      │  code fixes        │          │  (configured,    │
         │                      └────────┬───────────┘          │   inferred,      │
         │                               │                      │   external)      │
         │              ┌────────────────┘                      └─────────────────┘
         │              │
         ▼              ▼
┌───────────────────────────────────────────┐
│            Compiler Core                  │
│            src/compiler/                  │
│                                           │
│  Source Text                              │
│    │                                      │
│    ▼                                      │
│  Scanner (scanner.ts)                     │
│    │  tokens                              │
│    ▼                                      │
│  Parser (parser.ts)                       │
│    │  AST (SourceFile)                    │
│    ▼                                      │
│  Binder (binder.ts)                       │
│    │  Symbols + Flow graph                │
│    ▼                                      │
│  Checker (checker.ts)                     │
│    │  Type-checked AST                    │
│    ▼                                      │
│  Emitter (emitter.ts)                     │
│    │  + Transformers (transformers/)      │
│    ▼                                      │
│  Output (.js, .d.ts, .map)               │
└───────────────────────────────────────────┘
         │
         ▼
┌───────────────────────────────────────────┐
│         Standard Library (src/lib/)       │
│  lib.es5.d.ts, lib.es2015.d.ts,         │
│  lib.dom.d.ts, lib.esnext.d.ts, ...     │
│  (107 declaration files)                 │
└───────────────────────────────────────────┘

Component Inventory

Technology Stack

Note

TypeScript is self-hosted: the compiler is written in TypeScript and compiled by a previous version of itself. The devDependencies include typescript: "^6.0.2" for bootstrapping.

2. System Requirements

Development Requirements

3. Configuration Reference

TypeScript configuration is defined in tsconfig.json (or jsconfig.json for JavaScript-only projects). The compiler reads this file to determine compilation options, file scope, and project structure.

Configuration Files

Configuration Hierarchy

Configurations support inheritance via extends:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

Important

Relative paths in extends are resolved relative to the file containing the extends property. The ${configDir} template variable can be used in path-valued options to reference the directory of the current config file.

Compiler Options by Category

File Layout

Environment Settings

Strict Type-Checking

Module Options

Path Mapping

Emit Options

JavaScript Support

JSX

Project References

Completeness

Watch Options

{
  "watchOptions": {
    "watchFile": "useFsEvents",
    "watchDirectory": "useFsEvents",
    "fallbackPolling": "dynamicPriorityPolling",
    "synchronousWatchDirectory": true,
    "excludeDirectories": ["**/node_modules", "dist"]
  }
}

Tip

On Linux systems with many files, you may hit the inotify watch limit. Either increase it (sysctl fs.inotify.max_user_watches=524288) or use polling-based watch strategies.

Environment Variables

Important

TSS_LOG accepts a path (e.g., TSS_LOG="-logToFile true -file /tmp/tsserver.log -level verbose"). This is essential for diagnosing language server issues. Log levels: terse, normal, requestTime, verbose.

File Inclusion/Exclusion

4. Deployment & Scaling

Publishing TypeScript as a Package

TypeScript itself is published to npm as the typescript package. The published artifact contains:

The package.json defines:

{
  "main": "./lib/typescript.js",
  "typings": "./lib/typescript.d.ts",
  "bin": {
    "tsc": "./bin/tsc",
    "tsserver": "./bin/tsserver"
  }
}

Release Process

TypeScript uses Azure Pipelines for CI/CD:

1. Build pipeline (azure-pipelines.release.yml): triggers on release-* branches, runs tests, produces a tarball artifact
2. Publish pipeline (azure-pipelines.release-publish.yml): manual trigger, publishes the tarball to npm with a tag (dev, beta, rc, latest) and creates a GitHub release

Publish tags:

Embedding TypeScript

TypeScript can be used as a library:

import * as ts from "typescript";

const program = ts.createProgram(["src/index.ts"], {
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.NodeNext,
});

const diagnostics = ts.getPreEmitDiagnostics(program);
diagnostics.forEach(d => {
  console.log(ts.flattenDiagnosticMessageText(d.messageText, "\n"));
});

The public API is exported from src/typescript/typescript.ts which re-exports all public symbols from the compiler and services.

Note

The TypeScript API is large and not all of it is documented. Many internal types are accessible but marked @internal and may change between versions without notice.

5. Operations

Build System

TypeScript uses hereby as its task runner (replacing the legacy Gulp setup via .gulp.js compatibility shim):

npx hereby <task>

Key build tasks (from package.json scripts):

Tip

Use npm run build:tests:notypecheck (hereby tests --no-typecheck) for faster test builds when you know the types are correct.

Code Coverage

Coverage is configured via .c8rc.json:

{
  "reporter": ["lcovonly", "cobertura", "v8", "v8-json", "codecov"],
  "src": "src",
  "include": ["src/**", "built/local/**"],
  "exclude": ["**/node_modules/**"],
  "mergeAsync": true
}

Language Server Operations

The tsserver language server is the backbone of IDE integration. It manages project state and responds to editor requests over a JSON-based protocol.

tsserver Command-Line Arguments

Typings Installer Arguments

Note

The typings installer runs as a child process of tsserver. It discovers JavaScript files that need @types packages and installs them automatically via npm. The types registry is at node_modules/types-registry/index.json in the global cache.

6. Performance

Compilation Performance

TypeScript uses several strategies to optimize compilation speed:

Memory Optimization

For large projects exceeding memory limits:

1. Split into smaller projects using project references
2. Enable skipLibCheck to avoid checking third-party declarations
3. Use disableReferencedProjectLoad for lazy-loading referenced projects
4. Limit lib to only the libraries actually needed
5. Exclude test and generated files from the main tsconfig.json

Profiling

npx tsc --generateTrace trace_output

Open trace_output/trace.json in chrome://tracing or the Chrome DevTools Performance tab to identify slow phases (binding, checking, emitting).

Tip

The --extendedDiagnostics flag prints timing breakdown for each compilation phase (I/O, parsing, binding, checking, emitting) and memory usage.

npx tsc --extendedDiagnostics

Files:           1523
Lines of Library:  41023
Lines of Definitions: 128402
Lines of TypeScript:  89234
Nodes of Library:  172048
Nodes of Definitions: 498123
Nodes of TypeScript:  412893
Identifiers:     321034
Symbols:         198234
Types:           89102
Instantiations:  234891
Memory used:     312412K
Assignability cache size: 98234
Identity cache size:      1234
Subtype cache size:       4521
Strict subtype cache size: 2345
I/O Read time:   0.12s
Parse time:      0.45s
ResolveModule time: 0.08s
ResolveTypeReference time: 0.02s
Program time:    0.89s
Bind time:       0.23s
Check time:      2.34s
Emit time:       0.56s
Total time:      4.02s

7. Security

Supply Chain Security

TypeScript's package.json defines "browser" overrides that disable Node.js-specific modules (fs, os, path, crypto, buffer, inspector, perf_hooks, source-map-support) when TypeScript is loaded in a browser context. This prevents accidental exposure of server-side APIs.

Configuration Security

• skipLibCheck: While it improves performance, it skips type checking of declaration files, which means type errors in third-party packages won't be caught
• allowJs + checkJs: When enabled on untrusted JavaScript, TypeScript's JSDoc parser processes all JSDoc comments, which could contain misleading type assertions
• plugins: Language service plugins run in the tsserver process with full Node.js access. Only install plugins from trusted sources
• allowLocalPluginLoads: When tsserver is started with this flag, it loads plugins from node_modules relative to the project, which could be a vector for malicious packages

Warning

Language service plugins execute arbitrary JavaScript in the editor's TypeScript process. Review any plugins before enabling --allowLocalPluginLoads in your editor configuration.

Source Map Security

Source maps (sourceMap, inlineSourceMap, inlineSources) can expose original TypeScript source code. In production deployments, either disable source maps or ensure they are not served publicly.

8. Developer Internals

Repository Structure

microsoft/TypeScript/
├── src/
│   ├── compiler/          # Core compiler (36 files, 3.3M chars)
│   │   ├── scanner.ts     # Lexical analysis → token stream
│   │   ├── parser.ts      # Syntax analysis → AST (SourceFile)
│   │   ├── binder.ts      # Symbol creation + control flow graph
│   │   ├── checker.ts     # Type checking (the largest file in the project)
│   │   ├── emitter.ts     # Code generation orchestration
│   │   ├── transformer.ts # AST transformation pipeline
│   │   ├── transformers/  # Individual transformers (ES2015→ES5, JSX, etc.)
│   │   ├── types.ts       # All AST node types and compiler types
│   │   ├── program.ts     # Program creation and management
│   │   ├── sys.ts         # System abstraction (file I/O, watch)
│   │   ├── commandLineParser.ts  # CLI argument parsing
│   │   ├── moduleNameResolver.ts # Module resolution algorithms
│   │   ├── core.ts        # Core utilities (Queue, sorting, etc.)
│   │   ├── utilities.ts   # Internal utility functions
│   │   ├── utilitiesPublic.ts    # Public utility functions
│   │   ├── diagnosticInformationMap.generated.ts  # All diagnostic messages
│   │   ├── tracing.ts     # Performance tracing
│   │   └── factory/       # AST node factory functions
│   ├── services/          # Language service (38 files, 1.6M chars)
│   │   ├── services.ts    # LanguageService implementation
│   │   ├── completions.ts # IntelliSense completion provider
│   │   ├── goToDefinition.ts
│   │   ├── findAllReferences.ts
│   │   ├── rename.ts
│   │   ├── signatureHelp.ts
│   │   ├── documentHighlights.ts
│   │   ├── callHierarchy.ts
│   │   ├── inlayHints.ts
│   │   ├── navigateTo.ts
│   │   ├── navigationBar.ts
│   │   ├── organizeImports.ts
│   │   ├── outliningElementsCollector.ts
│   │   ├── smartSelection.ts
│   │   ├── formatting/    # Code formatting rules engine
│   │   │   ├── rules.ts   # Formatting rule definitions
│   │   │   └── ...
│   │   ├── refactors/     # Refactoring providers
│   │   ├── codefixes/     # Code fix providers
│   │   └── classifier.ts  # Semantic/syntactic classification
│   ├── server/            # Language server (13 files, 789K chars)
│   │   ├── session.ts     # Request/response handler (protocol implementation)
│   │   ├── project.ts     # Project types and management
│   │   ├── editorServices.ts # Editor integration services
│   │   ├── protocol.ts    # Wire protocol type definitions
│   │   ├── utilitiesPublic.ts # Server utility functions
│   │   └── ...
│   ├── tsserver/          # Server entry point (3 files)
│   │   ├── server.ts      # Main entry + startup
│   │   ├── nodeServer.ts  # Node.js system initialization + logging
│   │   └── common.ts      # Shared types
│   ├── tsc/               # CLI entry point (1 file)
│   │   └── tsc.ts         # Calls ts.executeCommandLine()
│   ├── typescript/        # Library entry (1 file)
│   │   └── typescript.ts  # Re-exports all public API
│   ├── lib/               # Standard library (107 .d.ts files)
│   ├── jsTyping/          # JS type acquisition
│   ├── typingsInstaller/  # @types installer (Node.js)
│   ├── typingsInstallerCore/ # @types installer core logic
│   ├── watchGuard/        # fs.watch safety check subprocess
│   ├── deprecatedCompat/  # Deprecated API shims
│   ├── harness/           # Test harness (23 files)
│   └── testRunner/        # Test runner (6 files)
├── tests/                 # Test suite (80K+ files, mostly baselines)
│   ├── cases/             # Test input files
│   ├── baselines/         # Expected output baselines
│   └── lib/               # Test library stubs
├── scripts/               # Build and maintenance scripts
│   ├── eslint/            # Custom ESLint rules for the project
│   └── hooks/             # Git hooks
├── lib/                   # Published library output (not in source)
├── .c8rc.json             # Coverage configuration
├── .gulp.js               # hereby compatibility shim
├── package.json           # Package manifest
└── azure-pipelines.*.yml  # CI/CD pipeline definitions

Architecture Deep Dive

Compiler Pipeline

The TypeScript compiler processes source code through five sequential phases:

1. Scanner (scanner.ts) Converts source text into a stream of tokens. The scanner is re-entrant and supports rescanning for template literals and JSX. It handles Unicode, regular expressions, and comment parsing.

2. Parser (parser.ts) Consumes the token stream and produces an Abstract Syntax Tree (AST). Each source file becomes a SourceFile node. The parser handles:

• Full ECMAScript grammar + TypeScript extensions (type annotations, enums, decorators, etc.)
• JSX syntax
• JSDoc comment parsing for JavaScript type checking
• Error recovery (produces a valid AST even for malformed input)

3. Binder (binder.ts) Walks the AST and creates Symbol objects that connect declarations to their uses. The binder also constructs the control flow graph used for narrowing (type guards, null checks). Key responsibilities:

• Symbol table construction (mapping names to declarations)
• Control flow graph for type narrowing
• Container/scope identification
• Module and namespace resolution
• Export assignment tracking

4. Checker (checker.ts) The type checker is the largest and most complex component. It performs:

• Type inference (return types, generic instantiation, contextual typing)
• Type compatibility checking (assignability, subtype, identity)
• Overload resolution
• Generic type parameter inference and constraint checking
• Control-flow-based type narrowing (typeof, instanceof, truthiness, discriminated unions)
• Excess property checking
• JSX element type checking
• Diagnostic message generation for type errors

5. Emitter (emitter.ts) + Transformers (transformer.ts, transformers/) Converts the type-checked AST into output files. The emitter orchestrates a pipeline of transformers, each handling a specific downlevel transformation:

• TypeScript → JavaScript (strip types, transform enums)
• ES2015+ → ES5 (arrow functions, classes, destructuring, generators, async/await)
• JSX → JavaScript (createElement/jsx calls)
• Module → target format (CommonJS, AMD, SystemJS, UMD, ESM)
• Declaration emit (.d.ts generation)

Module Resolution

Module resolution (moduleNameResolver.ts) implements multiple strategies:

Resolution steps (simplified):

1. Check paths mappings
2. Check rootDirs virtual directories
3. Try file extensions: .ts, .tsx, .d.ts, .js, .jsx
4. Check package.json exports/main/types/typings
5. Check @types packages
6. Check node_modules up the directory tree

Program and Project Management

The Program object (program.ts) represents a complete compilation unit:

• Resolves the full set of source files from tsconfig.json
• Creates and manages the SourceFile instances
• Coordinates the checker and emitter
• Handles incremental build state (.tsbuildinfo)
• Manages project references and composite builds

The sys module (sys.ts) abstracts file system operations, enabling TypeScript to run in different environments (Node.js, browser, virtual file systems for testing).

Module Reference

src/compiler/types.ts

Defines the complete TypeScript AST type hierarchy. Contains:

• SyntaxKind enum (all node types)
• AST node interfaces (Node, Statement, Expression, Declaration, etc.)
• Type system interfaces (Type, Symbol, Signature)
• CompilerOptions interface
• Diagnostic types
• SourceFile interface

src/compiler/core.ts

Core utility functions used throughout the compiler:

• Array manipulation (map, filter, flatMap, some, every)
• Queue data structure
• String utilities
• Assertion helpers via Debug
• Memoization utilities

src/compiler/commandLineParser.ts

Parses CLI arguments and tsconfig.json files:

• parseCommandLine() — parse tsc arguments
• parseJsonConfigFileContent() — parse tsconfig.json
• convertCompilerOptionsFromJson() — JSON to CompilerOptions
• generateTSConfig() — produce default tsconfig.json (for --init)
• Contains the authoritative list of all compiler options with their types, defaults, categories, and descriptions

src/compiler/sys.ts

System abstraction layer:

• File reading/writing
• Directory operations
• File watching (watchFile, watchDirectory)
• Environment variable access
• Process management
• Supports multiple watch strategies (fs events, polling variants)

src/services/services.ts

The LanguageService interface and its implementation. Key methods:

src/services/formatting/

The formatting engine, documented in its own README:

• Formatting decisions are rule-based (rules.ts contains the full rule set)
• Rules specify spacing/indentation between pairs of AST nodes
• The formatter is NOT publicly exported; it's only accessible through the language service
• Used by all language service operations that insert or modify code

src/server/session.ts

The tsserver session handles the JSON protocol between editors and the language service:

• Registers command handlers for all protocol commands
• Maps protocol requests to language service API calls
• Handles request cancellation
• Manages asynchronous operations (semantic diagnostics, project loading)

src/server/project.ts

Defines project types:

Code Patterns and Conventions

Testing Strategy

TypeScript uses a multi-layered testing approach:

1. Compiler baseline tests (src/testRunner/compilerRunner.ts)

• Conformance tests (tests/cases/conformance/): ECMAScript spec conformance
• Compiler tests (tests/cases/compiler/): regression tests for specific bugs
• Each test is a .ts file; output is compared against reference baselines

2. Fourslash tests (src/harness/fourslashImpl.ts)

• Language service integration tests
• Use a special markup syntax with markers (/**/) and annotations
• Test completions, go-to-definition, refactoring, code fixes, formatting
• Each test file defines both the source code and expected behavior

3. Project tests

• Test tsconfig.json parsing and resolution
• Test project references and composite builds
• Test build mode (--build) behavior

4. Unit tests (src/testRunner/unittests/)

• Test individual components (config parsing, services, etc.)
• Standard Mocha describe/it structure

5. Parallel test execution (src/testRunner/parallel/)

• Worker-based parallel test runner
• Distributes test files across multiple Node.js workers
• Custom Mocha mixins for timeout and clone support

Note

The test suite contains 80,000+ files, with the vast majority being baseline reference files (expected outputs). The actual source code under src/ is approximately 250 files totaling ~7MB.

Potential Improvements

Based on source analysis and community issues:

1. Module default behavior in v6: Community issue #63330 discusses that the default module setting in TypeScript 6.0 may not be esnext as expected. This transition area may need documentation updates.

2. rewriteRelativeImportExtensions for declarations: Issue #61037 notes that tsc doesn't rewrite extensions in emitted declaration files even when rewriteRelativeImportExtensions is enabled. This is a known limitation.

3. baseUrl deprecation discussion: Issue #62207 proposes deprecating baseUrl in favor of paths with relative resolution. This would affect many existing configurations.

4. Language server stability: Issues #63405 and #63151 report recurring language server crashes, particularly on large projects. Memory management and complex type computation are contributing factors.

5. Error message clarity: Issue #63206 reports confusing error messages (TS2322 vs TS2741) for certain property assignment scenarios. Error message quality is an ongoing area of improvement.

Contributing

Setup:

git clone https://github.com/microsoft/TypeScript.git
cd TypeScript
npm install
npm run setup-hooks
npm run build

Development workflow:

1. Make changes in src/
2. Build: npm run build:compiler
3. Test: npm test
4. Lint: npm run lint
5. Format: npm run format

Running specific tests:

npx hereby runtests --tests=<test-name-regex>

Updating baselines after intentional changes:

npx hereby baseline-accept

Caution

Always review baseline changes carefully before accepting. Baseline diffs can reveal unintended behavioral changes that affect downstream users.

Key conventions for contributors:

• All code is TypeScript (self-hosted)
• Use Debug.assert() for invariants, not throw
• Mark non-public API with /** @internal */
• Add baseline tests for compiler changes, fourslash tests for language service changes
• The codebase uses hereby (not Gulp) for build tasks
• Formatting is enforced by dprint; run npm run format before committing
• Custom ESLint rules in scripts/eslint/ enforce project-specific patterns

9. Integration Points

Editor Integration

TypeScript integrates with editors through tsserver, which communicates via a JSON-based protocol over stdin/stdout:

Language Service Plugin API

Plugins extend the language service with custom behavior:

function init(modules: { typescript: typeof ts }): ts.server.PluginModule {
  return {
    create(info: ts.server.PluginCreateInfo) {
      const proxy = Object.create(null);
      for (const k of Object.keys(info.languageService)) {
        proxy[k] = (info.languageService as any)[k];
      }
      // Override methods as needed
      proxy.getCompletionsAtPosition = (fileName, position, options) => {
        const prior = info.languageService.getCompletionsAtPosition(fileName, position, options);
        // Modify completions...
        return prior;
      };
      return proxy;
    },
  };
}

export = init;

Configure in tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      { "name": "my-typescript-plugin" }
    ]
  }
}

Build Tool Integration

Note

Bundlers and transpilers like esbuild, SWC, and Babel perform transpilation only — they strip type annotations without checking them. Always run tsc --noEmit separately for type safety.

Programmatic API

Key entry points for embedding TypeScript:

import * as ts from "typescript";

// Create a program from files
const program = ts.createProgram(fileNames, compilerOptions);

// Parse a single file
const sourceFile = ts.createSourceFile(
  "example.ts",
  sourceCode,
  ts.ScriptTarget.Latest
);

// Create a language service
const service = ts.createLanguageService(host);

// Parse tsconfig.json
const config = ts.readConfigFile("tsconfig.json", ts.sys.readFile);
const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, ".");