This page covers how to set up a local development environment for working on the TypeScript compiler repository. It describes prerequisites, repository setup, dependency installation, and the initial build sequence. For detailed sub-topics, see:
For information about what hereby tasks build and what test categories exist, see Build and Test System.
| Requirement | Minimum Version | Notes |
|---|---|---|
| Node.js | 14.17 | Defined in package.json engines field |
| npm | 8.19.4 | Pinned via packageManager field |
| hereby (global) | ^1.11.1 | Task runner; install with npm install -g hereby |
| Git | Any modern | Windows users need long-path support (see below) |
The repository uses Volta to pin tool versions. If Volta is installed, it will automatically select Node 20.1.0 and npm 8.19.4 as declared in package.json114-117
Windows note: File paths in the repository can exceed the default Windows limit. Run the following before cloning:
Sources: package.json28-30 package.json113-117 CONTRIBUTING.md108-111
A shallow clone significantly reduces download time:
The full history is large; --depth=1 is sufficient for most development tasks. A full clone is only necessary when doing git bisect or historical analysis.
Sources: CONTRIBUTING.md67-68 CONTRIBUTING.md106-107
All build and test dependencies are devDependencies. Install them with:
npm ci is preferred over npm install because it performs a clean install from package-lock.json, ensuring a reproducible environment.
Key development dependencies include:
| Package | Role |
|---|---|
hereby | Task runner (build, test orchestration) |
dprint | Code formatter |
eslint | Linter |
mocha | Test runner |
esbuild | Bundler for compiler outputs |
typescript | LKG compiler (bootstraps the build) |
c8 | Code coverage collection |
chokidar | File watching in watch mode |
Sources: package.json41-85 CONTRIBUTING.md65-66
After installing dependencies, install the repository's git hooks:
This is exposed as the setup-hooks npm script package.json101
The hooks perform automated tasks on git operations. See Git Configuration for details on what each hook does.
Sources: package.json101 scripts/hooks/post-checkout1-3
The following diagram shows the sequence of steps from a fresh clone to a fully built and tested environment.
Diagram: Setup and Build Flow
Sources: CONTRIBUTING.md64-73 Herebyfile.mjs416-427 Herebyfile.mjs534-551
hereby local is the alias for what Herebyfile.mjs calls the tsc task. It compiles the source, generates library files, and produces built/local/tsc.js. The hereby tests task produces built/local/run.js, which is the test runner entry point.
Sources: CONTRIBUTING.md79-93 Herebyfile.mjs416-471 Herebyfile.mjs532-551
The following table summarizes the most frequently used tasks. Run hereby --tasks for the full list.
| Task | Description |
|---|---|
hereby local | Build compiler to built/local/ |
hereby clean | Delete built/local/ |
hereby LKG | Promote built/local/ to the last-known-good (LKG) |
hereby tests | Build test infrastructure |
hereby runtests | Run tests (single-threaded); supports --tests=<regex> and --runner=<name> |
hereby runtests-parallel | Run tests across all CPU cores; supports --workers=<n> |
hereby baseline-accept | Accept new test baselines |
hereby lint | Run ESLint on compiler and scripts |
hereby generate-diagnostics | Regenerate diagnosticInformationMap.generated.ts from diagnosticMessages.json |
hereby format | Run dprint formatter |
hereby check-format | Check that files are properly formatted (CI mode) |
Sources: CONTRIBUTING.md79-93 Herebyfile.mjs559-605 Herebyfile.mjs86-102
Diagram: Build Task to Output File Mapping
Sources: Herebyfile.mjs416-551 Herebyfile.mjs64-80 Herebyfile.mjs86-102
After running hereby local, the locally built compiler can be invoked directly:
To make VS Code use the local build for IntelliSense, set typescript.tsdk to "built/local" in your .vscode/settings.json. The template at .vscode/settings.template.json4-6 includes this as a commented-out example.
Sources: CONTRIBUTING.md115-116 .vscode/settings.template.json4-6
The repository includes a devcontainer configuration at .devcontainer/devcontainer.json for contributors who prefer an isolated environment. Using a dev container skips all prerequisite installation steps, as the container image includes Node.js 22 and the postCreateCommand installs hereby, runs npm ci, and installs profiling tools (pprof, Graphviz).
See Dev Container Setup for full details.
Sources: .devcontainer/devcontainer.json1-44
The repository includes VS Code workspace configuration:
| File | Purpose |
|---|---|
| .vscode/settings.template.json | Workspace settings template (rename to settings.json) |
| .vscode/extensions.json | Recommended and unwanted extension list |
| .vscode/tasks.json | Build tasks: compile, watch, build tests |
| .vscode/launch.template.json | Debug launch configurations (rename to launch.json) |
Recommended extensions declared in .vscode/extensions.json2-6:
dbaeumer.vscode-eslint — ESLint integrationrbuckton.tsserver-live-reload — Reload the language server without restarting VS Codedprint.dprint — Formatter integrationCode formatting is handled by dprint, configured in .dprint.jsonc The formatter is set to run on save for TypeScript, JavaScript, JSON, and YAML files when using the settings template.
See Editor and Formatting Configuration for complete details.
Sources: .vscode/extensions.json1-11 .vscode/settings.template.json1-47 .vscode/tasks.json1-54 .dprint.jsonc1-60
Diagram: Repository Root Directory to Key Build Concepts
Sources: Herebyfile.mjs1-100 CONTRIBUTING.md156-170 .gitignore1-66
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.