Home

Awesome

:rotating_light: Important

This extension has been deprecated as Visual Studio Code now has a bundled JavaScript Debugger that covers the same functionality. It is a debugger that debugs Node.js, Chrome, Edge, WebView2, VS Code extensions, and more. You can safely un-install this extension and you will still be able to have the functionality you need.

Please file any issues you encounter in that repository.


<h1 align="center"> <br> <img src="https://github.com/Microsoft/vscode-chrome-debug/blob/master/images/icon.png?raw=true" alt="logo" width="200"> <br> VS Code - Debugger for Chrome <br> <br> </h1> <h4 align="center">Debug your JavaScript code running in Google Chrome from VS Code.</h4> <p align="center"> <a href="https://vscode.visualstudio.com/1e32b5a6-a974-467b-9d5f-f47e49589c5e/_build/definition?definitionId=9"><img src="https://vscode.visualstudio.com/_apis/public/build/definitions/1e32b5a6-a974-467b-9d5f-f47e49589c5e/9/badge" alt="vsts"></a> <a href="https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome"><img src="https://vsmarketplacebadge.apphb.com/version/msjsdiag.debugger-for-chrome.svg?label=Debugger%20for%20Chrome" alt="Marketplace bagde"></a> <a href="https://gitter.im/Microsoft/vscode-chrome-debug?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Microsoft/vscode-chrome-debug.svg" alt="Release"></a> </p>

A VS Code extension to debug your JavaScript code in the Google Chrome browser, or other targets that support the Chrome DevTools Protocol.

Demo

Supported features

Unsupported scenarios

Getting Started

  1. Install the extension
  2. Open the folder containing the project you want to work on.

Using the debugger

When your launch config is set up, you can debug your project. Pick a launch config from the dropdown on the Debug pane in Code. Press the play button or F5 to start.

Configuration

The extension operates in two modes - it can launch an instance of Chrome navigated to your app, or it can attach to a running instance of Chrome. Both modes requires you to be serving your web application from local web server, which is started from either a VS Code task or from your command-line. Using the url parameter you simply tell VS Code which URL to either open or launch in Chrome.

Just like when using the Node debugger, you configure these modes with a .vscode/launch.json file in the root directory of your project. You can create this file manually, or Code will create one for you if you try to run your project, and it doesn't exist yet.

Tip: See recipes for debugging different frameworks here: https://github.com/Microsoft/vscode-recipes

Launch

Two example launch.json configs with "request": "launch". You must specify either file or url to launch Chrome against a local file or a url. If you use a url, set webRoot to the directory that files are served from. This can be either an absolute path or a path using ${workspaceFolder} (the folder open in Code). webRoot is used to resolve urls (like "http://localhost/app.js") to a file on disk (like /Users/me/project/app.js), so be careful that it's set correctly.

{
    "version": "0.1.0",
    "configurations": [
        {
            "name": "Launch localhost",
            "type": "chrome",
            "request": "launch",
            "url": "http://localhost/mypage.html",
            "webRoot": "${workspaceFolder}/wwwroot"
        },
        {
            "name": "Launch index.html",
            "type": "chrome",
            "request": "launch",
            "file": "${workspaceFolder}/index.html"
        },
    ]
}

If you want to use a different installation of Chrome, you can also set the runtimeExecutable field with a path to the Chrome app.

Attach

With "request": "attach", you must launch Chrome with remote debugging enabled in order for the extension to attach to it. Here's how to do that:

Windows

macOS

Linux

If you have another instance of Chrome running and don't want to restart it, you can run the new instance under a separate user profile with the --user-data-dir option. Example: --user-data-dir=/tmp/chrome-debug. This is the same as using the userDataDir option in a launch-type config.

Launch Chrome and navigate to your page.

An example launch.json file for an "attach" config.

{
    "version": "0.1.0",
    "configurations": [
        {
            "name": "Attach to url with files served from ./out",
            "type": "chrome",
            "request": "attach",
            "port": 9222,
            "url": "<url of the open browser tab to connect to>",
            "webRoot": "${workspaceFolder}/out"
        }
    ]
}

Chrome user profile note (Cannot connect to the target: connect ECONNREFUSED)

Normally, if Chrome is already running when you start debugging with a launch config, then the new instance won't start in remote debugging mode. So by default, the extension launches Chrome with a separate user profile in a temp folder. Use the userDataDir launch config field to override or disable this. If you are using the runtimeExecutable field, this isn't enabled by default, but you can forcibly enable it with "userDataDir": true.

If you are using an attach config, make sure you close other running instances of Chrome before launching a new one with --remote-debugging-port. Or, use a new profile with the --user-data-dir flag yourself.

For other troubleshooting tips for this error, see below.

Errors from chrome-error://chromewebdata

If you see errors with a location like chrome-error://chromewebdata/ in the error stack, these errors are not from the extension or from your app - they are usually a sign that Chrome was not able to load your app.

When you see these errors, first check whether Chrome was able to load your app. Does Chrome say "This site can't be reached" or something similar? You must start your own server to run your app. Double-check that your server is running, and that the url and port are configured correctly.

Other targets

You can also theoretically attach to other targets that support the same Chrome Debugging protocol, such as Electron or Cordova. These aren't officially supported, but should work with basically the same steps. You can use a launch config by setting "runtimeExecutable" to a program or script to launch, or an attach config to attach to a process that's already running. If Code can't find the target, you can always verify that it is actually available by navigating to http://localhost:<port>/json in a browser. If you get a response with a bunch of JSON, and can find your target page in that JSON, then the target should be available to this extension.

Examples

See our wiki page for some configured example apps: Examples

Other optional launch config fields

Skip files / Blackboxing / Ignore files

You can use the skipFiles property to ignore/blackbox specific files while debugging. For example, if you set "skipFiles": ["jquery.js"], then you will skip any file named 'jquery.js' when stepping through your code. You also won't break on exceptions thrown from 'jquery.js'. This works the same as "blackboxing scripts" in Chrome DevTools.

The supported formats are:

Page refreshing

This debugger also enables you to refresh your target by simply hitting the restart button in the debugger UI. Additionally you can map the refresh action to your favorite keyboard shortcut by adding the following key mapping to Key Bindings:

{
    "key": "ctrl+r",
    "command": "workbench.action.debug.restart",
    "when": "inDebugMode"
}

Read more here https://github.com/Microsoft/vscode-chrome-debug-core/issues/91#issuecomment-265027348

Sourcemaps

The debugger uses sourcemaps to let you debug with your original sources, but sometimes the sourcemaps aren't generated properly and overrides are needed. In the config we support sourceMapPathOverrides, a mapping of source paths from the sourcemap, to the locations of these sources on disk. Useful when the sourcemap isn't accurate or can't be fixed in the build process.

The left hand side of the mapping is a pattern that can contain a wildcard, and will be tested against the sourceRoot + sources entry in the source map. If it matches, the source file will be resolved to the path on the right hand side, which should be an absolute path to the source file on disk.

A few mappings are applied by default, corresponding to some common default configs for Webpack and Meteor:

// Note: These are the mappings that are included by default out of the box, with examples of how they could be resolved in different scenarios. These are not mappings that would make sense together in one project.
// webRoot = /Users/me/project
"sourceMapPathOverrides": {
    "webpack:///./~/*": "${webRoot}/node_modules/*",       // Example: "webpack:///./~/querystring/index.js" -> "/Users/me/project/node_modules/querystring/index.js"
    "webpack:///./*":   "${webRoot}/*",                    // Example: "webpack:///./src/app.js" -> "/Users/me/project/src/app.js",
    "webpack:///*":     "*",                               // Example: "webpack:///project/app.ts" -> "/project/app.ts"
    "webpack:///src/*": "${webRoot}/*",                    // Example: "webpack:///src/app.js" -> "/Users/me/project/app.js"
    "meteor://💻app/*": "${webRoot}/*"                    // Example: "meteor://💻app/main.ts" -> "/Users/me/project/main.ts"
}

If you set sourceMapPathOverrides in your launch config, that will override these defaults. ${workspaceFolder} and ${webRoot} can be used here. If you aren't sure what the left side should be, you can use the .scripts command (details below). You can also use the trace option to see the contents of the sourcemap, or look at the paths of the sources in Chrome DevTools, or open your .js.map file and check the values manually.

Ionic/gulp-sourcemaps note

Ionic and gulp-sourcemaps output a sourceRoot of "/source/" by default. If you can't fix this via your build config, I suggest this setting:

"sourceMapPathOverrides": {
    "/source/*": "${workspaceFolder}/*"
}

Usage with remote VS Code extensions

This extension can be used with the VS Code Remote Extensions to debug an app in a local Chrome window. Here's an example workflow using the Remote - SSH extension:

There are a couple caveats to this workflow:

If you have any other issues, please open an issue.

Troubleshooting

My breakpoints aren't hit. What's wrong?

If your breakpoints aren't hit, it's most likely a sourcemapping issue or because you are having breakpoints in immediately executed code. If you for example have a breakpoint in a render function that runs on page load, sometimes our debugger might not be attached to Chrome before the code has been executed. This means that you will have to refresh the page in Chrome after we have attached from VS Code to hit your breakpoint.

Alternatively, we have an experimental "break-on-load" configuration option which will make this timing issue more transparent. It landed in https://github.com/microsoft/vscode-chrome-debug-core/pull/241.

If you have a sourcemapping issue, please see https://github.com/Microsoft/vscode-chrome-debug#sourcemaps

Cannot connect to the target: connect ECONNREFUSED 127.0.0.1:9222

This message means that the extension can't attach to Chrome, because Chrome wasn't launched in debug mode. Here are some things to try:

General things to try if you're having issues:

The .scripts command

This feature is extremely useful for understanding how the extension maps files in your workspace to files running in Chrome. You can enter .scripts in the Debug Console to see a listing of all scripts loaded in the runtime, their sourcemap information, and how they are mapped to files on disk. The format is like this:

› <The exact URL for a script, reported by Chrome> (<The local path that has been inferred for this script, using webRoot, if applicable>)
    - <The exact source path from the sourcemap> (<The local path inferred for the source, using sourceMapPathOverrides, or webRoot, etc, if applicable>)

Example:

.scripts
› eval://43
› http://localhost:8080/index.html (/Users/me/project/wwwroot/index.html)
› http://localhost:8080/out/test1.js (/Users/me/project/wwwroot/out/test1.js)
    - /src/test1a.ts (/Users/me/project/wwwroot/src/test1a.ts)
    - /src/test1b.ts (/Users/me/project/wwwroot/src/test1b.ts)
    - /src/test1c.ts (/Users/me/project/wwwroot/src/test1c.ts)
› http://localhost:8080/out/test2.js (/Users/me/project/wwwroot/out/test2.js)
    - /src/test2.ts (/Users/me/project/wwwroot/src/test2.ts)

If the paths of your source files show as not being resolved correctly here, you may have to change sourceMapPathOverrides or webRoot to help the debugger resolve them to real paths on disk.

If you are wondering what a script is, for example, that 'eval' script, you can also use .scripts to get its contents: .scripts eval://43.


This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.