Debug TypeScript Source Maps: VS Code, Chrome, Node.js, and Bundler Breakpoint Fixes
TypeScriptSource MapsVS CodeNode.jsDebuggingVite

Debug TypeScript Source Maps: VS Code, Chrome, Node.js, and Bundler Breakpoint Fixes

TTypeScript.page Editorial Team
2026-11-18
9 min read

Fix TypeScript breakpoints and stack traces with a practical source-map checklist for VS Code, Chrome, Node.js, Vite, Webpack, and tests.

When TypeScript breakpoints stop in generated JavaScript, stack traces show unfamiliar files, or local variables appear unavailable, the problem is usually a source-map mismatch rather than a TypeScript type error. This checklist explains how source maps connect runtime JavaScript to original TypeScript and how to fix that connection in VS Code, Chrome DevTools, Node.js, Vite, Webpack, and test runners.

Overview

TypeScript is normally compiled before it runs. A debugger sees the emitted JavaScript, while you want to inspect the .ts or .tsx file that you wrote. A source map is a file, or embedded mapping data, that relates locations in the generated file to locations in the original source.

When mappings work, you can set a breakpoint in TypeScript, step through the original source, inspect variables, and read stack traces in terms of your project files. When they fail, common symptoms include:

  • Breakpoints remain hollow, move to another line, or never pause.
  • The debugger opens a compiled dist, build, or temporary file instead of the TypeScript source.
  • Stack traces contain .js paths, incorrect line numbers, or duplicated directory segments.
  • Chrome shows bundled code while VS Code shows a different copy of the source.
  • Variables are missing or appear different after stepping through transformed code.

Debugging becomes easier when you separate the problem into three layers: the compiler or bundler must produce usable mappings, the runtime must load the correct generated files, and the debugger must resolve mapped paths to the files open in your workspace.

Source-map modes at a glance

ModeWhere mapping data livesUseful forTrade-off
External source mapA separate .map file beside the generated JavaScriptLocal development, Node.js, browser debugging, and readable build outputThe map must be copied and served with the matching JavaScript
Inline source mapEmbedded at the end of the generated JavaScriptSmall development builds, temporary scripts, and tools that do not preserve extra filesGenerated files become larger and may expose source content
Hidden source mapA separate map without a public source-map comment in the JavaScriptControlled error reporting or private debugging workflowsBrowsers will not automatically discover it; access must be configured separately

Do not treat sourceMap and declarationMap as interchangeable. sourceMap maps runtime JavaScript back to TypeScript for debugging. declarationMap maps generated declaration files back to source files, which helps when navigating or debugging a published TypeScript library.

Checklist by scenario

1. Start with the TypeScript compiler

For a direct TypeScript-to-JavaScript build, confirm that the active configuration enables source maps and that the output directory is not being confused with the source directory.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true,
    "inlineSources": true
  },
  "include": ["src/**/*.ts"]
}

Run the same build that your debug command uses, then inspect the output. You should normally find a JavaScript file and a matching map, such as dist/server.js and dist/server.js.map. Open the map as text and check that its sources entries refer to the expected files. If the build writes to a different directory than the debugger expects, no launch setting can fully repair the mismatch.

inlineSources embeds the original source text in the map. It can make local debugging more reliable when the debugger cannot find the original files, but it also increases output size and may include source code in artifacts. Use it deliberately, especially for distributable or production files.

2. Debug Node.js with VS Code

A reliable Node.js workflow builds before launching and points VS Code at the emitted entry point. The exact module settings depend on whether the project uses ESM or CommonJS, but the source-map principles are the same.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch compiled TypeScript",
      "program": "${workspaceFolder}/dist/server.js",
      "preLaunchTask": "npm: build",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "sourceMaps": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

The important settings are the generated program, the outFiles pattern, and a build that runs before debugging. If the program is launched with a package script, make sure that script does not rebuild into another directory or start a second process that VS Code is not attached to.

For a process started outside VS Code, use an attach configuration and confirm that the inspector is enabled. Then check that the attached process loaded the same JavaScript and map files you inspected on disk. A stale process is a frequent reason for apparently ignored changes.

3. Debug browser code in Chrome DevTools

For browser debugging, the development server must serve both the generated code and its source-map information. Open DevTools, select the Sources panel, and verify that the original TypeScript files appear under the mapped source tree. Set a breakpoint there rather than in a copied bundle tab.

If the source is missing, inspect the generated JavaScript response and look for a source-map reference. With an external map, the browser must be able to request the referenced .map URL. Check the browser Network panel for a failed map request, an incorrect base path, or a response that is actually an HTML fallback page.

When using a local development server, also check workspace mapping. The path in the map may be a URL-style path, an absolute path from another machine, or a virtual module identifier. Modern bundlers often provide their own mapping conventions, so compare the file shown in DevTools with the project file on disk instead of assuming that equal filenames mean equal sources.

4. Check Vite and Webpack settings

Bundlers can create a second source-map layer after TypeScript has compiled the code. In Vite, development debugging is commonly handled by the development server, while production mapping is controlled through the build configuration. If you need an explicit setting, review the build.sourcemap option and confirm that the output is being served from the directory you expect.

In Webpack, review devtool. Development-friendly options differ in speed, output size, and source visibility. A setting that produces no usable mappings, or a production setting that intentionally hides the map, will change debugger behavior. Also verify that loaders preserve source maps between transformations; a loader that discards the previous map can leave the final bundle with incomplete locations.

For either bundler, remove old output before testing a configuration change when stale assets could be involved. Then make one small, recognizable code change and confirm that the debugger opens that exact source file.

5. Debug tests and child processes

Test runners may transform TypeScript in memory, write temporary files, or launch worker processes. Start by identifying the actual runner and transformation path. A Jest configuration using one transformer is not equivalent to a Vitest configuration using Vite, and neither necessarily matches a direct tsc build.

Use the runner's debug command or attach to the process it creates. If breakpoints work in the application but not in tests, compare the test runner's generated paths, source-map support, and worker behavior. A breakpoint in a test file may be registered before the transformed module is loaded, or the test may be executing a cached copy.

What to double-check

  1. One source and one output: Confirm that the debugger is running the build you just created, not a package copy, old development server, or globally installed command.
  2. Path roots: Inspect sourceRoot, rootDir, and outDir. A wrong root can create paths such as src/src/index.ts or point outside the workspace.
  3. Map references: For external maps, confirm that the generated JavaScript references the correct filename and that the map sits at the referenced location.
  4. Source names: Look at the map's sources array. It should identify the intended TypeScript files, not a temporary directory or a different checkout.
  5. Module format: Keep ESM and CommonJS assumptions consistent across TypeScript, Node.js, the bundler, and the debugger. Module mismatches can make the process launch a different file than expected.
  6. Path casing: A path that works on a case-insensitive filesystem may fail in a Linux CI environment when directory capitalization differs.
  7. Declarations versus runtime maps: Use declarationMap for navigation through library declarations, but use sourceMap for runtime breakpoints and stack traces.
  8. Generated files: Do not edit compiled JavaScript to fix a mapping problem. Change the compiler or bundler configuration and rebuild.

A useful diagnostic is to compare three paths: the file named by the runtime stack trace, the file represented in the map's sources list, and the file open in the editor. If those three do not describe the same source, focus on path mapping before changing breakpoint settings.

Common mistakes

  • Launching TypeScript directly without a compatible runtime: A debugger attached to a JavaScript runtime still needs a transformation and mapping strategy. Use a supported TypeScript runner or compile first.
  • Copying only JavaScript to a server: External maps are separate artifacts. If the map is needed for a private debugging workflow, copy it alongside the matching JavaScript or make the map available through the intended error-reporting system.
  • Publishing maps unintentionally: Source maps can reveal source text, file paths, and comments. Decide whether production maps should be public, private, hidden, or omitted, and verify the final artifact rather than relying only on a development setting.
  • Using a broad outFiles pattern: VS Code may match an old bundle or a dependency. Narrow the pattern to the output produced by the current project when multiple builds exist.
  • Changing several tools at once: Change one layer, rebuild, and test. Otherwise it is difficult to tell whether the compiler, bundler, runtime, or debugger fixed the issue.
  • Assuming a correct line means correct execution: Transpilation, minification, async code, and bundling can change stepping behavior. If the location is close but not exact, inspect the emitted code and map quality before assuming the debugger is broken.

When to revisit

Keep this checklist nearby whenever the project changes its build or runtime boundary. Revisit it before a planned development-workflow review, after changing TypeScript compiler options, or when moving between Vite, Webpack, a framework build, and a direct Node.js setup. It is also worth checking after switching between ESM and CommonJS, changing test runners, adding a worker or child process, or moving builds into containers and CI.

For CI-only failures, compare the generated artifact and source-map paths produced in CI with those produced locally. Record the command that builds the code, the directory it writes, the runtime entry point, and whether maps are copied or uploaded. This small inventory makes future tool changes easier to review.

Use this final action list after every source-map configuration change:

  1. Delete or isolate stale output.
  2. Run the exact build used by the debugger.
  3. Confirm the JavaScript, map, and source paths match.
  4. Launch or attach to the intended process.
  5. Set a breakpoint on a line that definitely executes.
  6. Step through one function and inspect a local variable.
  7. Check one thrown error or stack trace for a correct TypeScript location.
  8. Review whether the chosen map mode is safe for the artifact being distributed.

If all eight checks pass, the remaining issue is more likely to be application control flow, an optimized transformation, or debugger-specific behavior than a basic TypeScript source-map configuration error.

Related Topics

#TypeScript#Source Maps#VS Code#Node.js#Debugging#Vite
T

TypeScript.page Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.