Getting started

This page covers cloning the repo, installing dependencies, building the compiler, running tests, and pointing your editor at a local build.

Prerequisites

• Node.js — current or LTS. The repo's package.json declares engines.node >=14.17. The recommended development version is pinned via Volta to Node 22.22.0.
• npm — bundled with Node. The repo uses npm@8.19.4 (also pinned via Volta).
• Git — for cloning.
• A TypeScript-aware editor is helpful but not required. VS Code is the team's primary editor and has a ready-to-use .vscode/launch.template.json.

Clone and install

git clone --depth=1 https://github.com/microsoft/TypeScript
cd TypeScript
npm ci
npm install -g hereby   # the build task runner; or use `npx hereby` everywhere

npm ci reads package-lock.json and gives you a clean, deterministic install. The repository's lockfile is large (~370 KB) because the dev dependency tree is deep — Mocha, Chai, esbuild, dprint, ESLint, the typescript-eslint plugins, Playwright (for browser tests), and so on. See reference/dependencies for what each one does.

On Windows you may need:

git config --global core.longpaths true

before cloning, because some test fixtures have very long path names.

Build

hereby is the task runner. The most common targets are listed in hereby --tasks. The high-frequency ones are:

hereby local             # Build the compiler into built/local/
hereby clean             # Delete built/local/
hereby tests             # Build the test infrastructure (built/local/run.js)
hereby runtests          # Run all tests sequentially
hereby runtests-parallel # Same, but split across cores (10–15 minutes)
hereby lint              # ESLint over src/
hereby format            # dprint formatter
hereby LKG               # Promote built/local to lib/ (the bootstrap LKG)

A successful hereby local build leaves you with a usable TypeScript compiler at built/local/tsc.js:

node ./built/local/tsc.js --version
node ./built/local/tsc.js --watch path/to/test.ts

The npm run build script invokes hereby local and hereby tests together.

Run a single test

The TypeScript test runner is mocha-based. To run one test:

hereby runtests --tests=2dArrays                   # by file stem
hereby runtests --tests=tests/cases/compiler/2dArrays.ts
hereby runtests --runner=fourslash                 # only language-service tests
hereby runtests --runner=compiler                  # only compiler conformance
hereby runtests --tests=2dArrays -i                # debug under inspector

Tests under tests/cases/ produce baseline files in tests/baselines/local/. After verifying differences against tests/baselines/reference/ you accept new baselines with:

hereby baseline-accept

See how-to-contribute/testing for the full workflow and how-to-contribute/debugging for printf-style debugging tips.

Use the local build in another project

The build emits a complete built/local/ that mirrors lib/ from a published typescript package. To dogfood your build inside another project:

node /path/to/repo/built/local/tsc.js --project /path/to/other/tsconfig.json

Or replace the typescript install in your other project:

cd /path/to/other-project
npm install /path/to/repo

VS Code can be pointed at a local TypeScript via the TypeScript: Select TypeScript Version command; choose "Use Workspace Version" and edit .vscode/settings.json to set typescript.tsdk to /path/to/repo/built/local.

Dev container

The repository ships a .devcontainer/ configuration. Open the folder in a Codespace or with VS Code's Dev Containers: Open Folder in Container command to get an isolated, pre-provisioned environment. This is the fastest way to get up and running on a fresh machine.

What to do next

• Explore the architecture overview.
• Read how-to-contribute/index before submitting any change.
• See systems/program to learn how a tsc invocation produces output end-to-end.