Debugging TypeScript in WebStorm: Mapping IDE Breakpoints to Chrome

The Core Problem: Browser-IDE Disconnect

When developing complex TypeScript applications, debugging in the browser's DevTools often feels disconnected from the source code. You are forced to switch contexts between the IDE and the browser, and if your code is transpiled or bundled, the browser often displays a transformed version of your logic rather than the original TypeScript files. The goal is to move the debugging experience entirely into WebStorm, allowing you to pause execution and inspect variables directly within your source files.

How WebStorm Synchronizes with the Browser

WebStorm achieves this by utilizing the Chrome DevTools Protocol. When you launch a debug session, the IDE starts a browser instance with a remote debugging port enabled. This creates a bidirectional bridge: the IDE sends breakpoint locations to the browser, and the browser sends runtime state (variable values, call stacks) back to the IDE.

For this to work with TypeScript, the IDE relies on Source Maps. These are JSON files generated by your compiler (like tsc) or bundler (like Vite or Webpack) that tell the debugger exactly which line of the generated JavaScript corresponds to which line of the original TypeScript.

Configuring a JavaScript Debug Session

To move your debugging into the IDE, you must create a specific Run/Debug configuration. This example assumes you are running a local development server (e.g., localhost:5173) and using a modern browser like Chrome.

1. Navigate to Run > Edit Configurations.
2. Click the + icon and select JavaScript Debug.
3. Set the URL to the exact address of your local app (e.g., http://localhost:5173).
4. Give the configuration a name, such as "Frontend Debug".
5. Click OK.

Practical Verification Example

To verify the connection, follow this sequence:

// In your TypeScript file (e.g., app.ts)
function calculateTotal(price: number, tax: number) {
  const total = price + tax; // Set a breakpoint on this line
  return total;
}

1. Click the gutter next to the const total line to set a red breakpoint.
2. Select your "Frontend Debug" configuration from the top toolbar and click the Debug (bug) icon.
3. WebStorm will launch a new Chrome window. Perform the action in the UI that triggers calculateTotal.
4. The IDE should automatically bring the app.ts file to the foreground and highlight the line in blue.

Inspecting State

Once paused, use the Variables pane at the bottom of the IDE. You can right-click a variable to Set Value (changing the state of the running app in real-time) or use the Evaluate Expression (Alt+F8) tool to test logic without restarting the session.

Critical Limitations and Common Failures

The most common reason breakpoints are ignored (appearing as grey circles or "unbound breakpoints") is a failure in the source map chain.

Source Map Misconfiguration

If you are using Vite or Webpack, ensure your configuration explicitly enables source maps for development. For example, in a tsconfig.json, you must have:

{ "compilerOptions": { "sourceMap": true } }

Without this, WebStorm knows where the JavaScript is, but it has no map to find the corresponding TypeScript line.

Dynamic Code and Eval

The debugger cannot reliably map code generated via eval() or new Function(). If your framework uses heavy runtime code generation, breakpoints in those specific segments will likely be ignored.

Browser Instance Conflicts

WebStorm typically launches a fresh browser profile to ensure the remote debugging port is available. If you try to attach to an already open browser window that wasn't started with the --remote-debugging-port flag, the connection will fail.

Rollback and Cleanup

Since this operation only creates a configuration and launches a process, there is no permanent state change to your project files. To stop the session:

• Click the Stop (red square) button in the Debug tool window.
• Close the browser window launched by the IDE.