TypeScript Source Maps & Debugging — Complete Guide

In this tutorial, you will learn about TypeScript Source Maps & Debugging. We cover key concepts, practical examples, and best practices to help you master this topic.

TypeScript source maps bridge the gap between compiled JavaScript and TypeScript source — they map line numbers and column positions so you can set breakpoints, inspect variables, and debug directly in your original TypeScript files.

What You'll Learn

• How source maps work
• Configuring sourceMap and inlineSourceMap
• Debugging in VS Code
• Debugging in Chrome DevTools
• Troubleshooting common source map issues

Why It Matters

Without source maps, debugging TypeScript means reading compiled JavaScript — variables are renamed, async/await is transformed, and line numbers don't match. Source maps make TypeScript debugging feel like debugging native TypeScript.

Real-World Use

Every DodaTech application ships with source maps enabled in development. The Durga Antivirus Pro dashboard uses VS Code debugger with TypeScript breakpoints for real-time threat analysis. In production, source maps are stripped to avoid exposing source code.

Learning Path

flowchart LR
  A[Module Resolution] --> B[Source Maps]
  B --> C[Linting]
  B --> D[You Are Here]
  C --> E[Bundling]
  E --> F[React Components]

How Source Maps Work

A source map is a .map file that maps each line/column in the compiled JavaScript back to the original TypeScript:

// Compiled JS: dist/index.js
// Source map: dist/index.js.map
// Maps line 5, col 10 in JS -> line 3, col 5 in src/index.ts

Browser and debugger tools read .map files automatically to show you TypeScript source instead of compiled JS.

Configuration

Separate .map Files

{
  "compilerOptions": {
    "sourceMap": true,
    "outDir": "./dist"
  }
}

Produces .js + .js.map files side by side. The .map file contains a reference back to the original .ts file.

Inline Source Maps

{
  "compilerOptions": {
    "inlineSourceMap": true
  }
}

Embeds the source map as a base64 comment at the end of the .js file. No separate .map file is created.

Inline Sources

{
  "compilerOptions": {
    "inlineSources": true
  }
}

Embeds the actual TypeScript source code into the source map instead of referencing external files. Useful when the .ts files may not be accessible.

Debugging in VS Code

Launch Configuration

// .vscode/launch.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"],
      "sourceMaps": true
    }
  ]
}

Key Settings

// .vscode/settings.json
{
  "debug.javascript.autoAttachFilter": "smart",
  "debug.javascript.terminalOptions": {
    "skipFiles": ["<node_internals>/**"]
  }
}

Setting Breakpoints

1. Open any .ts file
2. Click the gutter (left margin) to add a breakpoint (red dot)
3. Press F5 to start debugging
4. Execution pauses on your TypeScript code
5. Inspect variables, call stack, and watches

Debugging in Chrome DevTools

With Webpack/Vite Bundling source maps into the bundle:

1. Open Chrome DevTools (F12)
2. Go to Sources tab
3. Find your .ts files under webpack:// or . folder
4. Set breakpoints directly in TypeScript
5. Reload the page

Chrome Workspaces

Chrome can persist changes back to disk:

1. Sources tab > Filesystem
2. Add your project folder
3. Chrome maps source files to disk
4. Edit TypeScript in Chrome, changes save to disk

Debugging with ts-node

# Install
npm install --save-dev ts-node

# Debug a script directly
node --inspect-brk -r ts-node/register src/script.ts

Or use the VS Code launch config with ts-node:

{
  "type": "node",
  "request": "launch",
  "name": "TS-Node Debug",
  "runtimeArgs": ["-r", "ts-node/register"],
  "args": ["${workspaceFolder}/src/script.ts"]
}

Debugging Tests

// .vscode/launch.json for Vitest
{
  "type": "node",
  "request": "launch",
  "name": "Debug Tests",
  "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
  "args": ["run", "--reporter", "verbose"],
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen"
}

Common Source Map Issues

1. Source Maps Not Loading

Check: Are .map files alongside the .js files? Is sourceMap: true in tsconfig?

2. Wrong Line Numbers

Stale .map files — rebuild with tsc --clean && tsc.

3. No Source in Chrome DevTools

Ensure bundler is configured for source maps:

// vite.config.ts
export default defineConfig({
  build: { sourcemap: true }
})

// webpack.config.js
module.exports = {
  devtool: 'source-map'
}

4. Exposing Source Code in Production

Don't deploy .map files to production. Use .gitignore for *.js.map or configure your build tool.

5. Source Maps with Bundlers

Each bundler has unique source map configuration. Always verify source maps work end-to-end after changing bundler config.

Practice Questions

1. What does sourceMap: true do? Generates .js.map files that map compiled JS back to original TS sources.

2. What is the difference between sourceMap and inlineSourceMap? sourceMap creates separate .map files. inlineSourceMap embeds the map as a base64 comment in the .js file.

3. How do you debug TypeScript in VS Code? Create a .vscode/launch.json with sourceMaps: true, pointing outFiles to the compiled output directory.

4. Why remove source maps from production? Source maps reveal your original TypeScript source code to anyone who inspects the browser.

Challenge: Set up a TypeScript project with sourceMap: true. Create a simple Express server, set a breakpoint in a .ts route handler, and step through it using VS Code's debugger.

FAQ

What's Next

Now explore linting and formatting:

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.