This page guides new contributors through setting up a local development environment for the TypeScript repository, building the compiler from source, and running the test suite. For information about writing specific kinds of tests, see Writing Tests. For the pull request process, see Pull Request Process.
Important: As of TypeScript 6.0, all new feature contributions should be directed to microsoft/typescript-go The JavaScript-based compiler in this repository is in maintenance mode and accepts only critical bug fix contributions. See CONTRIBUTING.md1-3 for the full notice.
| Requirement | Notes |
|---|---|
| Node.js | Current or LTS release; the repo pins node 20.1.0 via Volta. Minimum is >=14.17. |
| npm | 8.19.4 pinned via Volta; npm ci is used for reproducible installs. |
| Git | Standard install. On Windows, run git config --global core.longpaths true before cloning. |
| hereby | Global install: npm install -g hereby. This is the build task runner for the repo. |
| VS Code (recommended) | Used with the workspace settings in .vscode/. |
The engines field in package.json28-30 enforces the Node minimum. The volta field at package.json114-117 pins the exact Node and npm versions when Volta is installed.
Sources: package.json28-30 package.json114-117 CONTRIBUTING.md59-62
--depth=1 skips full history, which significantly reduces clone time on this large repository. Full history can be fetched later with git fetch --unshallow if needed.
Sources: CONTRIBUTING.md67 CONTRIBUTING.md107-108
This installs all devDependencies declared in package.json41-84 into node_modules/. The package-lock.json file is committed and governs exact versions.
After installation, set up the Git hooks:
This installs a pre-commit hook (runs dprint for formatting) and a post-checkout hook (runs hereby generate-diagnostics). See scripts/hooks/post-checkout1-2 for the post-checkout hook.
Sources: package.json89-101 CONTRIBUTING.md65-71 scripts/hooks/post-checkout1-2
The build system is driven by hereby using tasks declared in Herebyfile.mjs Each task is a named unit of work, and tasks can declare dependencies on other tasks.
Build task dependency graph
Sources: Herebyfile.mjs416-551 Herebyfile.mjs453-465
The primary build command produces all outputs under built/local/:
This is also available as:
After a successful build, the directory built/local/ contains:
| File | Description |
|---|---|
built/local/tsc.js | Command-line TypeScript compiler |
built/local/typescript.js | Public compiler API bundle |
built/local/tsserver.js | Language server |
built/local/run.js | Test runner entry point |
built/local/lib.*.d.ts | Compiled standard library files |
Artifact flow through the build
Sources: Herebyfile.mjs82-137 Herebyfile.mjs416-465 Herebyfile.mjs64-80
After building the compiler, build the test harness:
This compiles src/testRunner/ and produces built/local/run.js, which mocha uses as its entry point.
Sources: Herebyfile.mjs532-551
Or equivalently:
This distributes test files across worker processes equal to the system core count by default.
| Example | What it runs |
|---|---|
hereby runtests --tests=compiler | All compiler baseline tests |
hereby runtests --tests=2dArrays | A single test: tests/cases/compiler/2dArrays.ts |
hereby runtests --runner=fourslash | All fourslash language service tests |
The test runner dispatches test files to typed runner instances, defined in src/testRunner/runner.ts58-74:
| Runner kind | Class | Test location |
|---|---|---|
conformance | CompilerBaselineRunner | tests/cases/conformance/ |
compiler | CompilerBaselineRunner | tests/cases/compiler/ |
fourslash | FourSlashRunner | tests/cases/fourslash/ |
fourslash-server | FourSlashRunner | tests/cases/fourslash/server/ |
project | ProjectRunner | tests/cases/projects/ |
transpile | TranspileRunner | tests/cases/transpile/ |
Test dispatch flow
Sources: src/testRunner/runner.ts58-74 src/testRunner/parallel/host.ts36-47 src/testRunner/parallel/worker.ts20-30
The -i flag attaches a Node.js inspector. The .vscode/launch.template.json provides a VS Code debug configuration — copy it to .vscode/launch.json to use the Mocha Tests (currently opened test) launch target from the Run panel.
Sources: CONTRIBUTING.md208-214 .vscode/launch.template.json20-54
Most compiler and fourslash tests emit baseline files into tests/baselines/reference/. When compiler output changes, tests fail with a baseline mismatch.
To inspect the diff between expected and actual output:
After verifying that the changes are correct, accept the new baselines:
This copies tests/baselines/local/ → tests/baselines/reference/ and these reference files are committed as part of your change.
Sources: CONTRIBUTING.md244-270
To use your locally built compiler in place of the globally installed tsc:
To switch VS Code's IntelliSense to use the locally built compiler, add this to .vscode/settings.json (copy from .vscode/settings.template.json):
Sources: CONTRIBUTING.md115-116 .vscode/settings.template.json4-5
| Task | What it does |
|---|---|
hereby local | Builds tsc, tsserver, typescript.js, and libs into built/local/ |
hereby tsc | Builds only the tsc CLI |
hereby services | Builds only typescript.js |
hereby tests | Builds the test runner (built/local/run.js) |
hereby runtests | Runs tests (single-threaded) |
hereby runtests-parallel | Runs tests across multiple workers |
hereby baseline-accept | Promotes local baselines to reference |
hereby generate-diagnostics | Regenerates diagnosticInformationMap.generated.ts from diagnosticMessages.json |
hereby lint | Runs ESLint on compiler and scripts sources |
hereby clean | Deletes built/ |
hereby LKG | Replaces the Last Known Good compiler with the current build |
hereby --tasks | Lists all available tasks |
Sources: CONTRIBUTING.md76-94 Herebyfile.mjs559-604
The repository ships a VS Code dev container definition at .devcontainer/devcontainer.json It uses the javascript-node:1-22-bookworm image and installs the following automatically via postCreateCommand:
hereby (globally via npm)npm ci (project dependencies)pprof (Go profiling tool)graphviz (for visualization tooling)To use it, open the repository folder in VS Code and use Remote-Containers: Open Folder in Container or Clone Repository in Container Volume.
Sources: .devcontainer/devcontainer.json1-44
Copy .vscode/settings.template.json to .vscode/settings.json for the recommended workspace settings. Key settings it configures:
dprint as the default formatter for TypeScript, JavaScript, JSON, and YAML filesformatOnSave enabled for all supported languages.js (required for the project's ESM module paths)Recommended extensions are listed in .vscode/extensions.json:
| Extension ID | Purpose |
|---|---|
dbaeumer.vscode-eslint | ESLint integration |
dprint.dprint | dprint formatter integration |
rbuckton.tsserver-live-reload | Hot-reload tsserver during development |
Sources: .vscode/settings.template.json1-47 .vscode/extensions.json1-11
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.