How to develop TypeScript

This article contains my most used workflow when working on the TypeScript repo with VSCode.

Normal development workflow

Build commands

  • Core compiler: npx gulp watch-tsc / npx gulp tsc
  • Language service: npx gulp watch-tsserver / npx gulp tsserver
  • …or both: npx gulp watch-min / npx gulp min


  • Run all tests: npx gulp runtests-parallel
  • Run tests that name matches “class”: npx gulp runtests -t=class
  • Run test failed in the last run: npx gulp runtests --failed
  • Accept new test results: npx gulp baseline-accept
  • Run linter: npx gulp lint

Add a new error message

  • Open src/compiler/diagnosticMessages.json.
  • Add the message you want.
  • Run npx gulp generate-diagnostics.
  • If VSCode doesn’t show the new error message in the Diagnostics object, open src/compiler/diagnosticInformationMap.generated.ts in VSCode to load the latest result.


Debug tsc

  1. Open a debug terminal.
    A menu that "Open JavaScript Debug Terminal" is highlighted.

  2. Run tsc by node ./built/local/tsc.js.
    Debugging command line compiler

Debug language server

First-time setup

  1. Create a folder at ../vscode-debug.

  2. Add a .vscode/launch.json with the content in the gist.

  3. Switch to the “Debug and Run” panel, start the debug profile. It should open a new VSCode window. A screenshot of the "Debug and Run" panel, with an arrow pointing to the "start debug" icon.

  4. Open the JSON settings of the newly opened VSCode, add some recommended settings.

  5. Add a ../vscode-debug/package.json with the content in the gist

  6. Create a TypeScript project in the ../vscode-debug

Debug routine

  1. Launch the debug profile VSCode.
  2. Select “Attach to VS Code TS Server via Port”. "Attach to VS Code TS Server via Port"
  3. It will open a prompt of which port you want to attach.
  4. Type “local” to filter the result. Selecting port to attach
  5. Now you can debug using the breakpoint in the VSCode. Debugging ts server

If you have an “unbound breakpoint”, which means the editor doesn’t handle the source map yet (it might never will). You should use the debugger statement to trigger it. An unbound breakpoint

If you want to reload the debugging TS Server, run > TypeScript: Restart TS server command, then you may need to re-attach by the steps above.

Restart tsserver

Debug tests

Follow the debug language server set up, and you’ll find “Mocha Tests (currently opened test)” in the debug targets.

Open a test you want to debug (e.g. tests/cases/compiler/2dArrays.ts), and start the debug.

Debugging tests

Some development tips

Use ES6+ syntax for the build

This can reduce pain when debugging step by step (for…of will be transformed into ES5 otherwise!).

Change target to ES2020 (or later) in src/tsconfig-base.json, and run

git update-index --assume-unchanged ./src/tsconfig-base.json

Jack Works

Posted on


Updated on


Licensed under