This document provides an overview of how to contribute to the TypeScript compiler repository at microsoft/TypeScript, covering issue reporting, code contributions, development setup, and testing procedures.
🚨 Important: As of TypeScript 6.0, active compiler development has moved to microsoft/typescript-go This repository is winding down JavaScript-based development. Pull requests will only be merged if they fix critical issues present in TypeScript 6.0 (bugs that existed in 5.9 but are not security issues are not considered critical). New feature contributions should be submitted to
microsoft/typescript-go.
See CONTRIBUTING.md1-4 for the authoritative notice.
The sub-pages under this section cover each area of the contribution process in detail:
| Sub-page | Topic |
|---|---|
| [15.1] Getting Started | Environment setup, building, and first test run |
| [15.2] Writing Tests | Compiler baseline tests, fourslash, and tsserver tests |
| [15.3] Pull Request Process | CLA, automated checks, and review workflow |
| [15.4] Issue Reporting Overview | Which issue template to use |
| [15.5] Bug Reports | Required information for bug reports |
| [15.6] Feature Requests | Feature proposal process and viability checklist |
| [15.7] Library Definition Changes | lib.d.ts and DOM API change process |
| [15.8] Module Resolution Issues | Reproducing and reporting module resolution bugs |
| [15.9] Understanding Type Narrowing Behavior | Narrowing behavior and how to interpret it |
For the build system mechanics, see page 12 (Build and Test System). For development environment setup, see page 10 (Development Environment). For diagnostic message localization, see page 9 (Diagnostic Message Localization).
The TypeScript project uses GitHub issue templates to structure reports. Before filing, always:
site:github.com/microsoft/TypeScript <keywords> (GitHub search is less precise than a general search engine)npm install typescript@nextIssue templates available (see page 15.4 for guidance on which to use):
| Template | File | Use for |
|---|---|---|
| Bug report | .github/ISSUE_TEMPLATE/bug_report.yml | Compiler misbehavior |
| Feature request | .github/ISSUE_TEMPLATE/feature_request.yml | New language/compiler features |
| Library change | .github/ISSUE_TEMPLATE/lib_change.yml | lib.d.ts type definition fixes |
| Module resolution | .github/ISSUE_TEMPLATE/module_resolution.yml | Module resolution failures |
| Narrowing behavior | .github/ISSUE_TEMPLATE/types-not-correct-in-with-callback.md | Narrowing-related "bugs" |
| Other | .github/ISSUE_TEMPLATE/other.yml | Everything else |
The config.yml file (.github/ISSUE_TEMPLATE/config.yml) disables blank issues and redirects users to Stack Overflow and the TypeScript FAQ for questions.
Sources: CONTRIBUTING.md5-47 .github/ISSUE_TEMPLATE/config.yml1-16 .github/ISSUE_TEMPLATE/bug_report.yml1-10 .github/ISSUE_TEMPLATE/feature_request.yml1-13
See page 10 (Development Environment) and page 10.1 (Dev Container Setup) for full environment documentation. A quick summary of the required steps is provided here.
Required tools
| Tool | Purpose |
|---|---|
| Node.js (Current or LTS) | Runs the build and test scripts |
hereby CLI (npm install -g hereby) | Task runner for builds and tests |
| Git | Source control; use --depth=1 for faster clones |
| VS Code (recommended) | Editor; workspace settings and extensions are pre-configured |
Windows note: Run git config --global core.longpaths true before cloning on Windows.
Setup sequence (CONTRIBUTING.md63-74):
git clone --depth=1 ...)npm install -g herebycd TypeScript && npm cihereby runtests-parallel — confirms the build and tests passDev Container: The .devcontainer/devcontainer.json configuration installs hereby, pprof, and Graphviz automatically and pre-installs the dbaeumer.vscode-eslint and dprint.dprint VS Code extensions. See page 10.1 for details.
hereby CommandsBuild and test task flow
| Command | Effect |
|---|---|
hereby local | Compile compiler to built/local/ |
hereby clean | Delete built/ |
hereby LKG | Copy built/local/ to lib/ (bootstrap step) |
hereby tests | Build test infrastructure using built compiler |
hereby runtests | Run tests; use --tests=<regex> and --runner=<name> |
hereby runtests-parallel | Parallel test run; use --workers=<n> |
hereby baseline-accept | Overwrite reference baselines with local results |
hereby lint | Run ESLint on TypeScript source |
hereby generate-diagnostics | Regenerate diagnosticInformationMap.generated.ts from diagnosticMessages.json |
Valid --runner values: conformance, compiler, fourslash, project.
Sources: CONTRIBUTING.md75-95 CONTRIBUTING.md63-74 .devcontainer/devcontainer.json1-44
Scope reminder: Due to the transition to
typescript-go, only bug fixes for critical issues will be merged into this repository. New features should go tomicrosoft/typescript-go.
PR flow from issue to merge
Issue selection rules (CONTRIBUTING.md115-130):
Backlog milestone — required per the PR templatePR checklist (.github/pull_request_template.md1-19):
Backlog milestone issue linked in the PR bodymainhereby runtests passes locallyDo not force-push after submitting — PRs are squash-merged, so individual commit history does not matter. Force pushes make review diffs unviewable on GitHub (CONTRIBUTING.md149-153).
The pr-modified-files.yml workflow (.github/workflows/pr-modified-files.yml) runs on every PR and performs three checks:
Automated PR checks and their triggers
| Trigger File | Action |
|---|---|
src/lib/dom.generated.d.ts, src/lib/webworker.generated.d.ts (and iterable variants) | PR is automatically closed — changes must go to microsoft/TypeScript-DOM-lib-generator |
src/server/protocol.ts | Comment posted pinging TSServer API reviewers |
tests/baselines/reference/api/typescript.d.ts | Comment posted requesting API Breaking Changes wiki update |
Sources: .github/workflows/pr-modified-files.yml1-139 CONTRIBUTING.md114-153 .github/pull_request_template.md1-22
See page 12.2 (Test Infrastructure) and page 12.3 (Test Baseline Management) for full documentation. The summary below covers the contribution-relevant aspects.
Test locations and baseline outputs
| Runner | Test location | Tests |
|---|---|---|
compiler | tests/cases/compiler/ | Compiler output and diagnostics |
conformance | tests/cases/conformance/ | Spec compliance |
fourslash | tests/cases/fourslash/ | Language service behavior |
project | tests/cases/project/ | Multi-project compilation |
Test file metadata (CONTRIBUTING.md218-225): Tests use // @metaDataName: value comment syntax to set compiler options. The // @filename: name.ts tag splits a single test file into multiple virtual files, useful for testing module imports:
// @filename: file1.ts
export function f() { }
// @filename: file2.ts
import { f as g } from "file1";
tests/baselines/local/git diff --no-index ./tests/baselines/reference ./tests/baselines/localhereby baseline-accept — copies local/ to reference/tests/baselines/reference/ files with your PRDebugging: Use hereby runtests --tests=<name> -i for Node.js inspector mode. The .vscode/launch.template.json file provides a VS Code debug configuration — rename it to launch.json and press F5 with the test file open.
Sources: CONTRIBUTING.md180-214 CONTRIBUTING.md240-267
See page 15.7 (Library Definition Changes) and page 6 (Standard Library) for full documentation.
src/lib/ file flow
| Location | Purpose |
|---|---|
src/lib/ | Source of truth for all hand-edited .d.ts library files |
built/local/ | Build output; updated by hereby local |
lib/ | LKG files used to bootstrap compilation; updated by hereby LKG |
Do not edit lib/ directly unless publishing a new version.
dom.generated.d.ts, dom.iterable.generated.d.ts, webworker.generated.d.ts, and webworker.iterable.generated.d.ts are auto-generated. PRs editing these files are automatically closed by the pr-modified-files.yml workflow. Changes must be submitted to the microsoft/TypeScript-DOM-lib-generator repository instead.
Standards thresholds for adding new APIs (src/lib/README.md12-23):
Sources: CONTRIBUTING.md154-174 src/lib/README.md1-27 .github/workflows/pr-modified-files.yml89-107
See page 9 (Diagnostic Message Localization) for full documentation.
All user-visible strings are stored in src/compiler/diagnosticMessages.json. After editing that file, run:
hereby generate-diagnostics
This regenerates src/compiler/diagnosticInformationMap.generated.ts, which contains the typed Diagnostic interface used throughout the compiler. The post-checkout git hook (scripts/hooks/post-checkout1-3) runs this automatically on branch switches.
Follow the coding guidelines for diagnostic message format (referenced in CONTRIBUTING.md274-275).
Sources: CONTRIBUTING.md270-275 scripts/hooks/post-checkout1-3
The TypeScript repository includes Git hooks for maintaining code quality and consistency throughout the development process.
Automated Code Formatting
pre-commit hook runs dprint fmt on staged filesDiagnostic Regeneration
post-checkout hook runs generate-diagnosticsGit Configuration Requirements
autocrlf = input to handle line endingswhitespace = cr-at-eol for consistencySources: scripts/hooks/post-checkout1-3 scripts/hooks/pre-commit1-5 scripts/link-hooks.mjs1-28 CONTRIBUTING.md144-148
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.