Home

Awesome

<h1 align="center"> <br> <img src="https://github.com/firefox-devtools/vscode-firefox-debug/blob/master/icon.png?raw=true" alt="logo" width="200"> <br> VS Code Debugger for Firefox <br> <br> </h1> <h4 align="center">Debug your JavaScript code running in Firefox from VS Code.</h4> <p align="center"> <a href="https://marketplace.visualstudio.com/items?itemName=firefox-devtools.vscode-firefox-debug"><img src="https://vsmarketplacebadges.dev/version/firefox-devtools.vscode-firefox-debug.png?label=Debugger%20for%20Firefox" alt="Marketplace badge"></a> </p>

A VS Code extension to debug web applications and extensions running in the Mozilla Firefox browser. 📦 Install from VS Code Marketplace.

Supported features

Getting Started

You can use this extension in launch or attach mode.

In launch mode it will start an instance of Firefox navigated to the start page of your application and terminate it when you stop debugging. You can also set the reAttach option in your launch configuration to true, in this case Firefox won't be terminated at the end of your debugging session and the debugger will re-attach to it when you start the next debugging session - this is a lot faster than restarting Firefox every time. reAttach also works for WebExtension debugging: in this case, the WebExtension is (re-)installed as a temporary add-on.

In attach mode the extension connects to a running instance of Firefox (which must be manually configured to allow remote debugging - see below).

To configure these modes you must create a file .vscode/launch.json in the root directory of your project. You can do so manually or let VS Code create an example configuration for you by clicking the gear icon at the top of the Debug pane.

Finally, if .vscode/launch.json already exists in your project, you can open it and add a configuration snippet to it using the "Add Configuration" button in the lower right corner of the editor.

Launch

Here's an example configuration for launching Firefox navigated to the local file index.html in the root directory of your project:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch index.html",
            "type": "firefox",
            "request": "launch",
            "reAttach": true,
            "file": "${workspaceFolder}/index.html"
        }
    ]
}

You may want (or need) to debug your application running on a Webserver (especially if it interacts with server-side components like Webservices). In this case replace the file property in your launch configuration with a url and a webRoot property. These properties are used to map urls to local files:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch localhost",
            "type": "firefox",
            "request": "launch",
            "reAttach": true,
            "url": "http://localhost/index.html",
            "webRoot": "${workspaceFolder}"
        }
    ]
}

The url property may point to a file or a directory, if it points to a directory it must end with a trailing / (e.g. http://localhost/my-app/). You may omit the webRoot property if you specify the pathMappings manually. For example, the above configuration would be equivalent to

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch localhost",
            "type": "firefox",
            "request": "launch",
            "reAttach": true,
            "url": "http://localhost/index.html",
            "pathMappings": [{
                "url": "http://localhost",
                "path": "${workspaceFolder}"
            }]
        }
    ]
}

Setting the pathMappings manually becomes necessary if the url points to a file or resource in a subdirectory of your project, e.g. http://localhost/login/index.html.

Attach

To use attach mode, you have to launch Firefox manually from a terminal with remote debugging enabled. Note that if you don't use Firefox Developer Edition, you must first configure Firefox to allow remote debugging. To do this, open the Developer Tools Settings and check the checkboxes labeled "Enable browser chrome and add-on debugging toolboxes" and "Enable remote debugging" (as described here). Alternatively you can set the following values in about:config:

Preference NameValueComment
devtools.debugger.remote-enabledtrueRequired
devtools.chrome.enabledtrueRequired
devtools.debugger.prompt-connectionfalseRecommended
devtools.debugger.force-localfalseSet this only if you want to attach VS Code to Firefox running on a different machine (using the host property in the attach configuration)

Then close Firefox and start it from a terminal like this:

Windows

"C:\Program Files\Mozilla Firefox\firefox.exe" -start-debugger-server

(This syntax is for a regular command prompt (cmd.exe), not PowerShell!)

OS X

/Applications/Firefox.app/Contents/MacOS/firefox -start-debugger-server

Linux

firefox -start-debugger-server

Navigate to your web application and use this launch.json configuration to attach to Firefox:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch index.html",
            "type": "firefox",
            "request": "attach"
        }
    ]
}

If your application is running on a Webserver, you need to add the url and webRoot properties to the configuration (as in the second launch configuration example above).

Skipping ("blackboxing") files

You can tell the debugger to ignore certain files while debugging: When a file is ignored, the debugger won't break in that file and will skip it when you're stepping through your code. This is the same as "black boxing" scripts in the Firefox Developer Tools.

There are two ways to enable this feature:

Path mapping

The debug adapter needs to map the URLs of javascript files (as seen by Firefox) to local file paths (as seen by VS Code). It creates a set of default path mappings from the configuration that work for most projects. However, depending on the setup of your project, they may not work for you, resulting in breakpoints being shown in gray (and Firefox not breaking on them) even after Firefox has loaded the corresponding file. In this case, you will have to define them manually using the pathMappings configuration property.

The easiest way to do this is through the Path Mapping Wizard: when you try to set a breakpoint during a debug session in a file that couldn't be mapped to a URL, the debug adapter will offer to automatically create a path mapping for you. If you click "Yes" it will analyze the URLs loaded by Firefox and try to find a path mapping that maps this file and as many other workspace files as possible to URLs loaded by Firefox and it will add this mapping to your debug configuration. Note that this path mapping is just a guess, so you should check if it looks plausible to you. You can also call the Path Mapping Wizard from the command palette during a debug session.

You can look at the Firefox URLs and how they are mapped to paths in the Loaded Scripts Explorer, which appears at the bottom of the debug side bar of VS Code during a debug session. By choosing "Map to local file" or "Map to local directory" from the context menu of a file or a directory, you can pick the corresponding local file or directory and a path mapping will automatically be added to your configuration.

If you specify more than one mapping, the first mappings in the list will take precedence over subsequent ones and all of them will take precedence over the default mappings.

The most common source of path mapping problems is webpack because the URLs that it generates depend on its configuration and different URL styles are in use. If your configuration contains a webroot property, the following mappings will be added by default in order to support most webpack setups:

{ "url": "webpack:///~/", "path": "${webRoot}/node_modules/" }
{ "url": "webpack:///./~/", "path": "${webRoot}/node_modules/" }
{ "url": "webpack:///./", "path": "${webRoot}/" }
{ "url": "webpack:///src/", "path": "${webRoot}/src/" }
{ "url": "webpack:///node_modules/", "path": "${webRoot}/node_modules/" }
{ "url": "webpack:///webpack", "path": null }
{ "url": "webpack:///(webpack)", "path": null }
{ "url": "webpack:///pages/", "path": "${webRoot}/pages/" }
{ "url": "webpack://[name]_[chunkhash]/node_modules/", "path": "${webRoot}/node_modules/" }
{ "url": "webpack://[name]_[chunkhash]/", "path": null }
{ "url": "webpack:///", "path": "" }

When the path argument of a mapping is set to null, the corresponding URLs are prevented from being mapped to local files. In the webpack mappings shown above this is used to specify that URLs starting with webpack:///webpack or webpack:///(webpack) do not correspond to files in your workspace (because they are dynamically generated by webpack). It could also be used for URLs that dynamically generate their content on the server (e.g. PHP scripts) or if the content on the server is different from the local file content. For these URLs the debugger will show the content fetched from the server instead of the local file content.

You can also use * as a wildcard in the url of a pathMapping. It will match any number of arbitrary characters except /.

Debugging WebExtensions

Here's an example configuration for WebExtension debugging:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch WebExtension",
            "type": "firefox",
            "request": "launch",
            "reAttach": true,
            "addonPath": "${workspaceFolder}"
        }
    ]
}

The addonPath property must be the absolute path to the directory containing manifest.json.

You can reload your WebExtension using the command "Firefox: Reload add-on" (extension.firefox.reloadAddon) from the VS Code command palette. The WebExtension will also be reloaded when you restart the debugging session, unless you have set reloadOnAttach to false. You can also use the reloadOnChange property to let VS Code reload your WebExtension automatically whenever you change a file.

You can enable/disable/toggle popup auto-hide using the commands "Firefox: Enable/Disable/Toggle popup auto-hide" (extension.firefox.enablePopupAutohide / disablePopupAutohide / togglePopupAutohide).

Further optional configuration properties

Overriding configuration properties in your settings

You can override some of the launch.json configuration properties in your user, workspace or folder settings. This can be useful to make machine-specific changes to your launch configuration without sharing them with other users.

This settingoverrides this launch.json property
firefox.executablefirefoxExecutable
firefox.argsfirefoxArgs
firefox.profileDirprofileDir
firefox.profileprofile
firefox.keepProfileChangeskeepProfileChanges
firefox.portport

Diagnostic logging

The following example for the log property will write all log messages to the file log.txt in your workspace:

...
    "log": {
        "fileName": "${workspaceFolder}/log.txt",
        "fileLevel": {
            "default": "Debug"
        }
    }
...

This example will write all messages about conversions from URLs to paths and all error messages to the VS Code console:

...
    "log": {
        "consoleLevel": {
            "PathConversion": "Debug",
            "default": "Error"
        }
    }
...

Troubleshooting