Building TypeScript

Learn how to build the TypeScript compiler and related tools using hereby

Build System Overview

TypeScript uses hereby, a modern task runner, to orchestrate its build process. The build is defined in Herebyfile.mjs and compiles TypeScript source code using itself (bootstrapping).

Quick Build

To build the entire compiler and services:

hereby local

This command:

• Generates diagnostic messages from src/compiler/diagnosticMessages.json
• Builds the compiler (tsc)
• Builds the language service server (tsserver)
• Builds the TypeScript library (typescript.js)
• Generates library definition files (lib.*.d.ts)
• Creates type definition bundles (typescript.d.ts)

The first build takes several minutes. Subsequent builds are faster due to incremental compilation.

Common Build Tasks

Compiler Only

Build just the command-line compiler:

hereby tsc

Output: built/local/tsc.js

Language Services

Build the TypeScript API library:

hereby services

Output: built/local/typescript.js

Language Server

Build the tsserver for editor integration:

hereby tsserver

Output: built/local/tsserver.js

Minimal Build

Build only tsc and tsserver (fastest):

hereby min

Build Configuration

Bundle Mode (Default)

By default, hereby uses esbuild to create bundled outputs:

hereby local --bundle=true

Advantages:

• Faster execution (single file)
• Smaller output size
• Production-like builds

Unbundled Mode

For development with better source mapping:

hereby local --bundle=false

Advantages:

• Easier debugging
• Faster incremental builds
• Better stack traces

Some tasks like LKG require bundle mode and will fail if --bundle=false is set.

Skip Type Checking

Speed up builds by skipping type checking:

hereby local --no-typecheck

Use --no-typecheck during rapid iteration, but always run a full build before submitting PRs.

Available Build Tasks

Primary Tasks

hereby local             # Full build (default)
hereby tsc               # Command-line compiler
hereby tsserver          # Language server
hereby services          # TypeScript API library
hereby min               # tsc + tsserver only
hereby tests             # Test infrastructure

Utility Tasks

hereby clean             # Delete built files
hereby lint              # Run ESLint
hereby format            # Format code with dprint
hereby LKG               # Update Last Known Good
hereby lib               # Build library files

Advanced Tasks

hereby generate-diagnostics  # Generate diagnostic codes
hereby baseline-accept       # Update test baselines
hereby diff                  # Compare baselines
hereby check-format          # Verify formatting
hereby knip                  # Check for unused code

View all available tasks:

hereby --tasks

Watch Mode

Watch mode is experimental and may not work as expected. Use at your own risk.

Automatically rebuild on file changes:

# Watch full build
hereby watch-local

# Watch minimal build
hereby watch-min

# Watch specific components
hereby watch-tsc
hereby watch-services
hereby watch-tsserver

Build Outputs

Directory Structure

built/local/
├── tsc.js                    # Compiler CLI
├── _tsc.js                   # Compiler CLI (unwrapped)
├── tsserver.js               # Language server
├── _tsserver.js              # Language server (unwrapped)
├── typescript.js             # Public API
├── typescript.d.ts           # Public API types
├── typescript.internal.d.ts  # Internal API types
├── tsserverlibrary.js        # Language service library
├── tsserverlibrary.d.ts      # Language service types
├── typingsInstaller.js       # Automatic type acquisition
├── watchGuard.js             # File watching helper
├── lib.*.d.ts                # Standard library types
└── *.js.map                  # Source maps

Compile Cache Optimization

Node.js 23+ uses module compilation caching. TypeScript generates shim files for:

• built/local/tsc.js → wraps _tsc.js with cache enablement
• built/local/tsserver.js → wraps _tsserver.js with cache enablement
• built/local/typingsInstaller.js → wraps _typingsInstaller.js

This improves startup performance on supported Node versions.

Library Files

TypeScript’s standard library definitions are built from sources:

hereby lib

Sources: src/lib/*.d.ts
Outputs: built/local/lib.*.d.ts

The src/lib/libs.json file defines which libraries are built and their output names.

src/lib/dom.generated.d.ts and src/lib/webworker.generated.d.ts are auto-generated. To modify them, contribute to TSJS-lib-generator.

Last Known Good (LKG)

The LKG is a stable compiler snapshot used to bootstrap builds:

hereby LKG

This copies built/local/* to lib/, replacing the bootstrap compiler.

Only run this command when the built compiler is stable! A broken LKG prevents building from source.

Diagnostic Messages

TypeScript’s error messages are defined in JSON:

hereby generate-diagnostics

Input: src/compiler/diagnosticMessages.json
Outputs:

• src/compiler/diagnosticInformationMap.generated.ts
• src/compiler/diagnosticMessages.generated.json

After modifying diagnostic messages, always run this task before building.

Troubleshooting

Build fails with 'hereby: command not found'

Install hereby globally:

npm install -g hereby

Out of memory during build

Increase Node.js memory:

export NODE_OPTIONS="--max-old-space-size=8192"
hereby local

Build is very slow

Try these optimizations:

• Use hereby min instead of hereby local
• Add --no-typecheck for faster iteration
• Use --bundle=true (default) for faster execution
• Close other applications to free memory

Changes not reflected in build

Clean and rebuild:

hereby clean
hereby local

LKG task fails with missing files

The LKG task requires bundle mode:

hereby local --bundle=true
hereby LKG

NPM Scripts

Alternatively, use npm scripts defined in package.json:

npm run build              # Full build
npm run build:compiler     # Compiler only
npm run build:tests        # Test infrastructure
npm run clean              # Clean outputs
npm run lint               # Run linter
npm run format             # Format code

The npm scripts are wrappers around hereby tasks. Using hereby directly provides more options.

Next Steps

Testing

Learn how to run and write tests

Debugging

Debug the compiler and language service