Debug TypeScript in VS Code

VS Code has a built-in debugger that works with TypeScript through source maps. This guide shows you how to debug TypeScript in VS Code with breakpoints, step-through debugging, and launch configurations. The debugger never runs your TypeScript directly. It runs the compiled JavaScript and uses source maps to show you the original source.

The setup takes two steps: enable source maps in your TypeScript config, and tell VS Code where to find the compiled output. Once those are in place, debugging feels native. For the test runner that pairs well with debugging, see Test TypeScript Code with Vitest.

The TypeScript compiler generates both the JavaScript output and a source map file. The source map is a JSON file that maps every position in the compiled JavaScript back to the corresponding position in your original TypeScript. When the debugger pauses, it uses the source map to show your .ts file instead of the compiled .js.

Enable Source Maps

Debugging TypeScript in VS Code depends entirely on source maps existing. The only compiler option you need to turn them on is sourceMap. Add it to your tsconfig.json:

json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "outDir": "dist",
    "sourceMap": true
  }
}

With sourceMap enabled, every .ts file produces two outputs: a .js file and a .js.map file. The map file is small and only used during debugging. It never ships to production.

Build your project to generate both:

bash

npx tsc

You will now see .js.map files alongside each .js file in your output directory.

Create a Launch Configuration

VS Code stores debug settings in a launch.json file inside the .vscode folder. The quickest way to create one is to open the Run and Debug panel and click "create a launch.json file." Choose Node.js as the environment.

A minimal launch.json for TypeScript debugging:

json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TypeScript",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build - tsconfig.json",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

The program field points to your entry .ts file. The preLaunchTask runs the TypeScript compiler before each debug session so your code is always up to date. The outFiles field tells the debugger where to find the compiled JavaScript. Without it, source maps cannot be resolved and breakpoints will not hit.

Set Breakpoints and Debug

Open any .ts file, click in the left gutter next to a line number, and a red dot appears. That is a breakpoint. Press F5 to start debugging. VS Code runs the preLaunchTask, launches Node.js with your compiled JavaScript, and pauses at your breakpoint.

While paused, you can inspect the current state of every variable in the Run and Debug side panel. You can also hover over any variable in the editor to see its value. The Debug Console at the bottom lets you evaluate expressions in the current scope.

The debug toolbar lets you continue execution, step over the current line, step into a function call, or step out of the current function. These controls work identically to any other debugger.

Debug Browser TypeScript

For client-side TypeScript, switch the debugger type from node to a browser. Install the Edge or Chrome debugger extension, then change the type field:

json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "msedge",
      "request": "launch",
      "name": "Debug in Edge",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}"
    }
  ]
}

Browser debugging works the same way. You set breakpoints in .ts files, and the browser's developer tools pause at those lines. Vite's dev server serves source maps that VS Code resolves out of the box, so this minimal config is usually enough. If your bundler prefixes source maps with webpack:// instead, add a sourceMapPathOverrides field mapping that prefix to ${webRoot} so the debugger can find your original files.

Watch Expressions and Call Stack

The debug panel shows two useful sections beyond variable inspection. The Watch section lets you type any expression and see its value update as you step through code. This is useful for tracking derived values or checking conditions without adding console.log calls.

The Call Stack section shows the full chain of function calls that led to the current breakpoint. Click any frame in the stack to jump to that function and inspect its local variables. This works across TypeScript files and even into node_modules if those packages ship source maps.

Common Debugging Pitfalls

If breakpoints appear hollow instead of solid red, VS Code cannot map your TypeScript to the compiled JavaScript. Check that sourceMap is true in your tsconfig and that outFiles matches your output directory.

If the debugger launches but breakpoints never hit, the compiled JavaScript may be in a different location than outFiles expects. Run your build and verify the .js.map files exist next to the .js files.

For more on configuring the compiler that produces those outputs, see TypeScript compiler explained.