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.
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.md5 and README.md31-39 for the full notice.
| Requirement | Notes |
|---|---|
| Node.js | Current or LTS release; the repo pins node 22.22.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.json113-116 pins the exact Node and npm versions when Volta is installed.
Sources: package.json28-30 package.json113-116 CONTRIBUTING.md85-88
--depth=1 skips full history, which significantly reduces clone time on this large repository.
Sources: CONTRIBUTING.md93-94 .github/copilot-instructions.md38
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 runs node scripts/link-hooks.mjs as defined in package.json100
Sources: package.json41-84 package.json100 CONTRIBUTING.md95-96
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.mjs45-137 Herebyfile.mjs416-551
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.mjs64-80 Herebyfile.mjs86-92 Herebyfile.mjs416-465 package.json92
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 package.json93
Or equivalently:
This distributes test files across worker processes equal to the system core count by default.
Sources: package.json89 scripts/build/tests.mjs69-81
| 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 |
Sources: scripts/build/tests.mjs36-40 .github/copilot-instructions.md48-50
The test runner dispatches test files to typed runner instances.
Test dispatch flow
Sources: scripts/build/tests.mjs34-52 scripts/build/tests.mjs132-135
The --break or --inspect flag attaches a Node.js inspector.
Sources: scripts/build/tests.mjs38 scripts/build/tests.mjs123-126
Most compiler and fourslash tests emit baseline files into tests/baselines/reference/. When compiler output changes, tests fail with a baseline mismatch.
To accept the new baselines after verifying changes:
This copies tests/baselines/local/ → tests/baselines/reference/.
Sources: scripts/build/tests.mjs22-23 .github/copilot-instructions.md51
The repository includes recommended settings for VS Code.
dprint as specified in .dprint.jsonceslint.config.mjs and custom rules in scripts/eslint/rules/.To run formatting and linting manually:
Sources: .dprint.jsonc1-61 package.json97-99
| 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 diagnostic generated files |
hereby lint | Runs ESLint |
hereby format | Runs dprint formatting |
hereby clean | Deletes built/ |
hereby LKG | Replaces the Last Known Good compiler |
Sources: Herebyfile.mjs9-137 Herebyfile.mjs416-551 package.json89-100
Refresh this wiki