The TypeScript build system is a specialized infrastructure designed to compile the TypeScript compiler, bundle its various outputs for different environments (Node.js, browser), and manage a complex testing suite. It utilizes hereby as a task orchestrator and esbuild for high-performance bundling, while relying on the "Last Known Good" (LKG) compiler for bootstrapping and type-checking.
The build system is driven by `hereby` a task runner that replaces traditional tools like Gulp or Jake. Task definitions are located in Herebyfile.mjs9-10 The system manages several critical workflows:
lib/ to compile the current source package.json22-23esbuild to package modular source code into single-file outputs like tsc.js and typescript.js Herebyfile.mjs5-6lib.d.ts) Herebyfile.mjs64-80diagnosticMessages.json into TypeScript constants Herebyfile.mjs86-92The primary entry points for developers are defined in package.json package.json88-101:
| Command | Action |
|---|---|
npm run build | Builds the compiler and the test runner package.json91 |
npm run build:compiler | Executes hereby local to build core binaries package.json92 |
npm test | Runs the full test suite in parallel package.json89 |
npm run lint | Executes hereby lint for code quality checks package.json97 |
Sources: package.json88-101 Herebyfile.mjs1-10
The build process produces several distinct artifacts in the built/local/ directory. These are generated by specific tasks that handle bundling, .d.ts generation, and library packaging.
Diagram: Build Artifact Generation Pipeline
Sources: Herebyfile.mjs82-92 Herebyfile.mjs51-80 Herebyfile.mjs180-201 Herebyfile.mjs416-430
Tasks in Herebyfile.mjs are defined using the task() function Herebyfile.mjs9 Dependencies are managed explicitly, ensuring that generated files (like diagnostics) exist before compilation begins.
generate-diagnostics: Runs scripts/processDiagnosticMessages.mjs to create the diagnostic map Herebyfile.mjs86-92lib: Aggregates files from src/lib into the built/local directory with appropriate copyright headers Herebyfile.mjs64-80build-src: Compiles the src directory. It depends on generate-diagnostics Herebyfile.mjs132-137local: The default task that produces a complete local build including tsc, services, tsserver, and lssl (Language Service Shell Library) Herebyfile.mjs666-671For details on how tasks are defined and orchestrated, see hereby Task Runner.
Sources: Herebyfile.mjs45-137 Herebyfile.mjs666-671
The build system uses a hybrid approach for performance. While tsc is used for type-checking and producing initial .js files in a project-references structure Herebyfile.mjs15-19 esbuild is used to bundle these files into single-file distributions Herebyfile.mjs5
The createBundler function Herebyfile.mjs180 configures esbuild with specific settings for the TypeScript project:
node Herebyfile.mjs191es2020 and node14.17 Herebyfile.mjs192cjs (CommonJS) Herebyfile.mjs193For details on the compilation pipeline and bundling strategy, see Build Pipeline.
Sources: Herebyfile.mjs180-201 package-lock.json37
TypeScript is "self-hosted," meaning the compiler is written in TypeScript and compiled by itself. To avoid circular dependencies and ensure stability, the repository maintains a Last Known Good (LKG) version in the lib/ directory package.json22-23
Diagram: Bootstrapping Logic
For details on the LKG update process and bootstrapping, see Last Known Good (LKG).
Sources: package.json22-23 Herebyfile.mjs673-678 azure-pipelines.release.yml81
The build system also manages the execution of the test suite. The runConsoleTests function scripts/build/tests.mjs34 orchestrates Mocha to run tests defined in built/local/run.js.
Key testing features include:
c8 for V8-based code coverage scripts/build/tests.mjs147-159--tests flag scripts/build/tests.mjs36Sources: scripts/build/tests.mjs34-52 scripts/build/tests.mjs69-81 package.json89