{"id":13496235,"url":"https://github.com/firefox-devtools/vscode-firefox-debug","last_synced_at":"2025-05-15T03:05:04.914Z","repository":{"id":6915878,"uuid":"53211165","full_name":"firefox-devtools/vscode-firefox-debug","owner":"firefox-devtools","description":"VS Code Debug Adapter for Firefox","archived":false,"fork":false,"pushed_at":"2025-02-28T16:23:37.000Z","size":3251,"stargazers_count":416,"open_issues_count":73,"forks_count":68,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-14T03:02:04.175Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://marketplace.visualstudio.com/items?itemName=firefox-devtools.vscode-firefox-debug","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firefox-devtools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-03-05T16:33:37.000Z","updated_at":"2025-04-12T04:23:37.000Z","dependencies_parsed_at":"2024-01-07T21:06:38.283Z","dependency_job_id":"a58de9ba-40bf-4b0a-a03a-c7eb276ed0f8","html_url":"https://github.com/firefox-devtools/vscode-firefox-debug","commit_stats":{"total_commits":934,"total_committers":12,"mean_commits":77.83333333333333,"dds":"0.023554603854389677","last_synced_commit":"328492f6ea8a063861a0ad98e5c6a76f3645f305"},"previous_names":[],"tags_count":125,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefox-devtools%2Fvscode-firefox-debug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefox-devtools%2Fvscode-firefox-debug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefox-devtools%2Fvscode-firefox-debug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefox-devtools%2Fvscode-firefox-debug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firefox-devtools","download_url":"https://codeload.github.com/firefox-devtools/vscode-firefox-debug/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264730,"owners_count":22041788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T19:01:44.269Z","updated_at":"2025-05-15T03:05:04.880Z","avatar_url":"https://github.com/firefox-devtools.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n    \u003cimg src=\"https://github.com/firefox-devtools/vscode-firefox-debug/blob/master/icon.png?raw=true\" alt=\"logo\" width=\"200\"\u003e\n  \u003cbr\u003e\n  VS Code Debugger for Firefox\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003eDebug your JavaScript code running in Firefox from VS Code.\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://marketplace.visualstudio.com/items?itemName=firefox-devtools.vscode-firefox-debug\"\u003e\u003cimg src=\"https://vsmarketplacebadges.dev/version/firefox-devtools.vscode-firefox-debug.png?label=Debugger%20for%20Firefox\" alt=\"Marketplace badge\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nA VS Code extension to debug web applications and extensions running in the [Mozilla Firefox browser](https://www.mozilla.org/en-US/firefox/developer/?utm_medium=vscode_extension\u0026utm_source=devtools). [📦 Install from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=firefox-devtools.vscode-firefox-debug).\n\n### Supported features\n\n* Pause [breakpoints](https://code.visualstudio.com/docs/editor/debugging#_breakpoints), including advanced [conditional](https://code.visualstudio.com/docs/editor/debugging#_conditional-breakpoints) and [inline](https://code.visualstudio.com/docs/editor/debugging#_inline-breakpoints) modes\n* Pause on object property changes with [Data breakpoints](https://code.visualstudio.com/docs/editor/debugging#_data-breakpoints)\n* Inject logging during debugging using [logpoints](https://code.visualstudio.com/docs/editor/debugging#_logpoints)\n* Debugging eval scripts, script tags, and scripts that are added dynamically and/or source mapped\n* *Variables* pane for inspecting and setting values\n* *Watch* pane for evaluating and watching expressions\n* *Console* for logging and REPL\n* Debugging Firefox extensions\n* Debugging Web Workers\n* Compatible with [remote development](https://code.visualstudio.com/docs/remote/remote-overview)\n\n## Getting Started\n\nYou can use this extension in **launch** or **attach** mode.\n\nIn **launch** mode it will start an instance of Firefox navigated to the start page of your application\nand 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\nyou 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](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox).\n\nIn **attach** mode the extension connects to a running instance of Firefox (which must be manually\nconfigured to allow remote debugging - see [below](#attach)).\n\nTo configure these modes you must create a file `.vscode/launch.json` in the root directory of your\nproject. You can do so manually or let VS Code create an example configuration for you by clicking \nthe gear icon at the top of the Debug pane.\n\nFinally, if `.vscode/launch.json` already exists in your project, you can open it and add a \nconfiguration snippet to it using the *\"Add Configuration\"* button in the lower right corner of the\neditor.\n\n### Launch\nHere's an example configuration for launching Firefox navigated to the local file `index.html` \nin the root directory of your project:\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Launch index.html\",\n            \"type\": \"firefox\",\n            \"request\": \"launch\",\n            \"reAttach\": true,\n            \"file\": \"${workspaceFolder}/index.html\"\n        }\n    ]\n}\n```\n\nYou may want (or need) to debug your application running on a Webserver (especially if it interacts\nwith server-side components like Webservices). In this case replace the `file` property in your\n`launch` configuration with a `url` and a `webRoot` property. These properties are used to map\nurls to local files:\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Launch localhost\",\n            \"type\": \"firefox\",\n            \"request\": \"launch\",\n            \"reAttach\": true,\n            \"url\": \"http://localhost/index.html\",\n            \"webRoot\": \"${workspaceFolder}\"\n        }\n    ]\n}\n```\nThe `url` property may point to a file or a directory, if it points to a directory it must end with\na trailing `/` (e.g. `http://localhost/my-app/`).\nYou may omit the `webRoot` property if you specify the `pathMappings` manually. For example, the\nabove configuration would be equivalent to\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Launch localhost\",\n            \"type\": \"firefox\",\n            \"request\": \"launch\",\n            \"reAttach\": true,\n            \"url\": \"http://localhost/index.html\",\n            \"pathMappings\": [{\n                \"url\": \"http://localhost\",\n                \"path\": \"${workspaceFolder}\"\n            }]\n        }\n    ]\n}\n```\nSetting the `pathMappings` manually becomes necessary if the `url` points to a file or resource in a\nsubdirectory of your project, e.g. `http://localhost/login/index.html`.\n\n### Attach\nTo use attach mode, you have to launch Firefox manually from a terminal with remote debugging enabled.\nNote that if you don't use Firefox Developer Edition, you must first configure Firefox to allow\nremote debugging. To do this, open the Developer Tools Settings and check the checkboxes labeled\n\"Enable browser chrome and add-on debugging toolboxes\" and \"Enable remote debugging\"\n(as described [here](https://developer.mozilla.org/en-US/docs/Tools/Remote_Debugging/Debugging_Firefox_Desktop#Enable_remote_debugging)).\nAlternatively you can set the following values in `about:config`:\n\nPreference Name                       | Value   | Comment\n--------------------------------------|---------|---------\n`devtools.debugger.remote-enabled`    | `true`  | Required\n`devtools.chrome.enabled`             | `true`  | Required\n`devtools.debugger.prompt-connection` | `false` | Recommended\n`devtools.debugger.force-local`       | `false` | Set this only if you want to attach VS Code to Firefox running on a different machine (using the `host` property in the `attach` configuration)\n\nThen close Firefox and start it from a terminal like this:\n\n__Windows__\n\n`\"C:\\Program Files\\Mozilla Firefox\\firefox.exe\" -start-debugger-server`\n\n(This syntax is for a regular command prompt (cmd.exe), not PowerShell!)\n\n__OS X__\n\n`/Applications/Firefox.app/Contents/MacOS/firefox -start-debugger-server`\n\n__Linux__\n\n`firefox -start-debugger-server`\n\nNavigate to your web application and use this `launch.json` configuration to attach to Firefox:\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Launch index.html\",\n            \"type\": \"firefox\",\n            \"request\": \"attach\"\n        }\n    ]\n}\n```\n\nIf your application is running on a Webserver, you need to add the `url` and `webRoot` properties\nto the configuration (as in the second `launch` configuration example above).\n\n### Skipping (\"blackboxing\") files\nYou can tell the debugger to ignore certain files while debugging: When a file is ignored, the\ndebugger won't break in that file and will skip it when you're stepping through your code. This is\nthe same as \"black boxing\" scripts in the Firefox Developer Tools.\n\nThere are two ways to enable this feature:\n* You can enable/disable this for single files while debugging by choosing \"Toggle skipping this file\"\n  from the context menu of a frame in the call stack.\n* You can use the `skipFiles` configuration property, which takes an array of glob patterns\n  specifying the files to be ignored.\n  If the URL of a file can't be mapped to a local file path, the URL will be matched against these\n  glob patterns, otherwise the local file path will be matched.\n  Examples for glob patterns:\n  * `\"${workspaceFolder}/skipThis.js\"` - will skip the file `skipThis.js` in the root folder of your project\n  * `\"**/skipThis.js\"` - will skip files called `skipThis.js` in any folder\n  * `\"**/node_modules/**\"` - will skip all files in `node_modules` folders anywhere in the project\n  * `\"http?(s):/**\"` - will skip files that could not be mapped to local files\n  * `\"**/google.com/**\"` - will skip files containing `/google.com/` in their url, in particular\n    all files from the domain `google.com` (that could not be mapped to local files)\n\n### Path mapping\nThe debug adapter needs to map the URLs of javascript files (as seen by Firefox) to local file paths\n(as seen by VS Code). It creates a set of default path mappings from the configuration that work\nfor most projects. However, depending on the setup of your project, they may not work for you,\nresulting in breakpoints being shown in gray (and Firefox not breaking on them) even after Firefox\nhas loaded the corresponding file. In this case, you will have to define them manually using the\n`pathMappings` configuration property.\n\nThe easiest way to do this is through the Path Mapping Wizard: when you try to set a breakpoint \nduring a debug session in a file that couldn't be mapped to a URL, the debug adapter will offer to\nautomatically create a path mapping for you. If you click \"Yes\" it will analyze the URLs loaded by\nFirefox and try to find a path mapping that maps this file and as many other workspace files as\npossible to URLs loaded by Firefox and it will add this mapping to your debug configuration.\nNote that this path mapping is just a guess, so you should check if it looks plausible to you.\nYou can also call the Path Mapping Wizard from the command palette during a debug session.\n\nYou can look at the Firefox URLs and how they are mapped to paths in the Loaded Scripts Explorer,\nwhich appears at the bottom of the debug side bar of VS Code during a debug session.\nBy choosing \"Map to local file\" or \"Map to local directory\" from the context menu of a file or\na directory, you can pick the corresponding local file or directory and a path mapping will\nautomatically be added to your configuration.\n\nIf you specify more than one mapping, the first mappings in the list will take precedence over\nsubsequent ones and all of them will take precedence over the default mappings.\n\nThe most common source of path mapping problems is webpack because the URLs that it generates\ndepend on its configuration and different URL styles are in use. If your configuration contains a\n`webroot` property, the following mappings will be added by default in order to support most webpack\nsetups:\n```\n{ \"url\": \"webpack:///~/\", \"path\": \"${webRoot}/node_modules/\" }\n{ \"url\": \"webpack:///./~/\", \"path\": \"${webRoot}/node_modules/\" }\n{ \"url\": \"webpack:///./\", \"path\": \"${webRoot}/\" }\n{ \"url\": \"webpack:///src/\", \"path\": \"${webRoot}/src/\" }\n{ \"url\": \"webpack:///node_modules/\", \"path\": \"${webRoot}/node_modules/\" }\n{ \"url\": \"webpack:///webpack\", \"path\": null }\n{ \"url\": \"webpack:///(webpack)\", \"path\": null }\n{ \"url\": \"webpack:///pages/\", \"path\": \"${webRoot}/pages/\" }\n{ \"url\": \"webpack://[name]_[chunkhash]/node_modules/\", \"path\": \"${webRoot}/node_modules/\" }\n{ \"url\": \"webpack://[name]_[chunkhash]/\", \"path\": null }\n{ \"url\": \"webpack:///\", \"path\": \"\" }\n```\n\nWhen the `path` argument of a mapping is set to `null`, the corresponding URLs are prevented from\nbeing mapped to local files. In the webpack mappings shown above this is used to specify that\nURLs starting with `webpack:///webpack` or `webpack:///(webpack)` do not correspond to files in\nyour workspace (because they are dynamically generated by webpack). It could also be used for URLs\nthat dynamically generate their content on the server (e.g. PHP scripts) or if the content on the\nserver is different from the local file content. For these URLs the debugger will show the content\nfetched from the server instead of the local file content.\n\nYou can also use `*` as a wildcard in the `url` of a pathMapping. It will match any number of\narbitrary characters except `/`.\n\n### Debugging WebExtensions\nHere's an example configuration for WebExtension debugging:\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Launch WebExtension\",\n            \"type\": \"firefox\",\n            \"request\": \"launch\",\n            \"reAttach\": true,\n            \"addonPath\": \"${workspaceFolder}\"\n        }\n    ]\n}\n```\nThe `addonPath` property must be the absolute path to the directory containing `manifest.json`.\n\nYou can reload your WebExtension using the command \"Firefox: Reload add-on\" (`extension.firefox.reloadAddon`)\nfrom the VS Code command palette.\nThe WebExtension will also be reloaded when you restart the debugging session, unless you have set\n`reloadOnAttach` to `false`.\nYou can also use the `reloadOnChange` property to let VS Code reload your WebExtension automatically\nwhenever you change a file.\n\nYou can enable/disable/toggle popup auto-hide using the commands \"Firefox: Enable/Disable/Toggle\npopup auto-hide\" (`extension.firefox.enablePopupAutohide` / `disablePopupAutohide` / `togglePopupAutohide`).\n\n### Further optional configuration properties\n* `reAttach`: If you set this option to `true` in a `launch` configuration, Firefox won't be \n  terminated at the end of your debugging session and the debugger will re-attach to it at the\n  start of your next debugging session.\n* `reloadOnAttach`: This flag controls whether the web page(s) should be automatically reloaded\n  after attaching to Firefox. The default is to reload in a `launch` configuration with the\n  `reAttach` flag set to `true` and to not reload in an `attach` configuration.\n* `reloadOnChange`: Automatically reload the Firefox tabs or your WebExtension whenever files change.\n  You can specify single files, directories or glob patterns to watch for file changes and\n  additionally specify files to be ignored. Since watching files consumes system resources,\n  make sure that you are not watching more files than necessary.\n  The following example will watch all javascript files in your workspace except those under\n  `node_modules`:\n  ```json\n    \"reloadOnChange\": {\n        \"watch\": [ \"${workspaceFolder}/**/*.js\" ],\n        \"ignore\": [ \"${workspaceFolder}/node_modules/**\" ]\n    }\n  ```\n  By default, the reloading will be \"debounced\": the debug adapter will wait until the last file\n  change was 100 milliseconds ago before reloading. This is useful if your project uses a build\n  system that generates multiple files - without debouncing, each file would trigger a separate\n  reload. You can use `reloadOnChange.debounce` to change the debounce time span or to disable\n  debouncing (by setting it to `0` or `false`).\n\n  Instead of string arrays, you can also use a single string for `watch` and `ignore` and if you\n  don't need to specify `ignore` or `debounce`, you can specify the `watch` value directly, e.g.\n  ```json\n  \"reloadOnChange\": \"${workspaceFolder}/lib/*.js\"\n  ```\n* `tabFilter`: Only attach to Firefox tabs with matching URLs. You can specify one or more URLs to\n  include and/or URLs to exclude and the URLs can contain `*` wildcards.\n  By default, a `tabFilter` is constructed from the `url` in your `launch` or `attach` configuration\n  by replacing the last path segment with `*`. For example, if your configuration contains\n  `\"url\": \"http://localhost:3000/app/index.html\"`, the default `tabFilter` will be\n  `\"http://localhost:3000/app/*\"`.\n* `clearConsoleOnReload`: Clear the debug console in VS Code when the page is reloaded in Firefox.\n* `tmpDir`: The path of the directory to use for temporary files\n* `profileDir`, `profile`: You can specify a Firefox profile directory or the name of a profile\n  created with the Firefox profile manager. The extension will create a copy of this profile in the\n  system's temporary directory and modify the settings in this copy to allow remote debugging.\n  You can also override these properties in your settings (see below). The default profile names\n  used by Firefox are `default`, `dev-edition-default` and `default-nightly` for the stable,\n  developer and nightly editions, respectively.\n* `keepProfileChanges`: Use the specified profile directly instead of creating a temporary copy.\n  Since this profile will be permanently modified for debugging, you should only use this option\n  with a dedicated debugging profile. You can also override this property in your settings (see below).\n* `port`: Firefox uses port 6000 for the debugger protocol by default. If you want to use a different\n  port, you can set it with this property. You can also override this property in your settings\n  (see below).\n* `timeout`: The timeout in seconds for the adapter to connect to Firefox after launching it.\n* `firefoxExecutable`: The absolute path to the Firefox executable or the name of a Firefox edition\n  (`stable`, `developer` or `nightly`) to look for in its default installation path. If not specified,\n  this extension will look for both stable and developer editions of Firefox; if both are available,\n  it will use the developer edition. You can also override this property in your settings (see below).\n* `firefoxArgs`: An array of additional arguments used when launching Firefox (`launch` configuration only).\n  You can also override this property in your settings (see below).\n* `host`: If you want to debug with Firefox running on a different machine, you can specify the \n  device's address using this property (`attach` configuration only).\n* `log`: Configures diagnostic logging for this extension. This may be useful for troubleshooting\n  (see below for examples).\n* `showConsoleCallLocation`: Set this option to `true` to append the source location of `console`\n  calls to their output\n* `preferences`: Set additional Firefox preferences in the debugging profile\n* `popupAutohideButton`: Show a button in the status bar for toggling popup auto-hide\n  (enabled by default when debugging a WebExtension)\n* `liftAccessorsFromPrototypes`: If there are accessor properties (getters and setters) defined\n  on an object's prototype chain, you can \"lift\" them so they are displayed on the object itself.\n  This is usually necessary in order to execute the getters, because otherwise they would be\n  executed with `this` set to the object's prototype instead of the object itself. This property\n  lets you set the number of prototype levels that should be scanned for accessor properties to lift.\n  Note that this will slow the debugger down, so it's set to `0` by default.\n* `pathMappingIndex`: The name of the directory index file configured in the webserver, defaults\n  to `index.html`. This will be appended to all URLs pointing to a directory (i.e. URLs ending\n  with `/`) before trying to map them to file paths.\n* `suggestPathMappingWizard`: Suggest using the Path Mapping Wizard when you try to set a\n  breakpoint in an unmapped source during a debug session. You may want to turn this off if some\n  of the sources in your project are loaded on-demand (e.g. if you create multiple bundles with\n  webpack and some of these bundles are only loaded as needed).\n* `enableCRAWorkaround`: Enable a workaround for facebook/create-react-app#6074: Adding/removing\n  breakpoints doesn't work for sources that were changed after the dev-server was started\n\n### Overriding configuration properties in your settings\nYou can override some of the `launch.json` configuration properties in your user, workspace or\nfolder settings. This can be useful to make machine-specific changes to your launch configuration\nwithout sharing them with other users.\n\nThis setting                 | overrides this `launch.json` property\n-----------------------------|-------------------------------------\n`firefox.executable`         | `firefoxExecutable`\n`firefox.args`               | `firefoxArgs`\n`firefox.profileDir`         | `profileDir`\n`firefox.profile`            | `profile`\n`firefox.keepProfileChanges` | `keepProfileChanges`\n`firefox.port`               | `port`\n\n### Diagnostic logging\nThe following example for the `log` property will write all log messages to the file `log.txt` in\nyour workspace:\n```json\n...\n    \"log\": {\n        \"fileName\": \"${workspaceFolder}/log.txt\",\n        \"fileLevel\": {\n            \"default\": \"Debug\"\n        }\n    }\n...\n```\n\nThis example will write all messages about conversions from URLs to paths and all error messages\nto the VS Code console:\n```json\n...\n    \"log\": {\n        \"consoleLevel\": {\n            \"PathConversion\": \"Debug\",\n            \"default\": \"Error\"\n        }\n    }\n...\n```\n \n## Troubleshooting\n* Breakpoints that should get hit immediately after the javascript file is loaded may not work the\n  first time: You will have to click \"Reload\" in Firefox for the debugger to stop at such a\n  breakpoint. This is a weakness of the Firefox debug protocol: VS Code can't tell Firefox about\n  breakpoints in a file before the execution of that file starts.\n* If your breakpoints remain unverified after launching the debugger (i.e. they appear gray instead\n  of red), the conversion between file paths and urls may not work. The messages from the \n  `PathConversion` logger may contain clues how to fix your configuration. Have a look at the \n  \"Diagnostic Logging\" section for an example how to enable this logger.\n* If you think you've found a bug in this adapter please [file a bug report](https://github.com/firefox-devtools/vscode-firefox-debug/issues).\n  It may be helpful if you create a log file (as described in the \"Diagnostic Logging\" section) and\n  attach it to the bug report.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirefox-devtools%2Fvscode-firefox-debug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirefox-devtools%2Fvscode-firefox-debug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirefox-devtools%2Fvscode-firefox-debug/lists"}