How to Debug Chrome Extensions in Visual Studio Code: A Comprehensive Guide

Debugging is an essential skill for any developer, and browser extensions are no exception. Fortunately, Visual Studio Code provides an excellent debugging experience for Chrome extensions. By using the built-in debugger, you can easily set breakpoints, step through your code, and inspect variables and state. This makes tracking down bugs and understanding your extension‘s behavior much simpler compared to littering your code with console.log statements.

In this guide, we‘ll walk through the process of setting up and using the debugger for Chrome extension development in VS Code. Whether you‘re just getting started with extension development or looking to optimize your workflow, you‘ll be debugging like a pro in no time.

Installing the Debugger for Chrome Extension

The first step is to install the Debugger for Chrome extension in VS Code. You can do this from the Extensions view (Ctrl+Shift+X) by searching for "Debugger for Chrome" and clicking the Install button.

Once installed, you‘re ready to configure your debugging setup.

Configuring launch.json

To use the debugger, you need to create a launch.json file to tell VS Code how to start or attach to Chrome. From the Run view (Ctrl+Shift+D), click the "create a launch.json file" link to generate a default launch configuration.

There are two main ways to debug Chrome extensions:

1. Launch – starts a new instance of Chrome with your extension loaded
2. Attach – attaches to an existing Chrome instance that has remote debugging enabled

Here‘s an example launch.json configuration for both scenarios:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome with Extension",
      "url": "http://localhost:8080",
      "webRoot": "${workspaceFolder}",
      "runtimeArgs": [
        "--load-extension=${workspaceFolder}/path/to/extension"
      ]
    },
    {
      "type": "chrome",
      "request": "attach",
      "name": "Attach to Chrome",
      "port": 9222,
      "webRoot": "${workspaceFolder}"
    }
  ]
}

The "launch" configuration starts a new Chrome instance with the extension loaded from the specified path. You can set the initial URL to open and the webRoot for mapping URLs to files in your workspace.

The "attach" configuration attaches to an existing Chrome instance using remote debugging on port 9222. This requires launching Chrome separately with remote debugging enabled, which we‘ll cover next.

Enabling Remote Debugging in Chrome

To use the "attach" debugging configuration, you first need to start Chrome with remote debugging enabled.

On Windows, you can do this by right-clicking the Chrome shortcut and selecting Properties. In the Target field, append the –remote-debugging-port=9222 flag:

On macOS, open a terminal and run:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

On Linux, the command is similar:

google-chrome --remote-debugging-port=9222

Now when you launch Chrome, remote debugging will be enabled on port 9222.

Note that you should close any other running Chrome instances before starting one with remote debugging. Also be aware that terminating the debugging session will close this Chrome instance.

Debugging Your Extension

With your launch.json configured and Chrome running with remote debugging, you‘re ready to start debugging your extension.

Open your extension‘s source files in VS Code. Let‘s say you have a background script with a bug you want to investigate:

// background.js

chrome.browserAction.onClicked.addListener(function() {
  chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) {
    var activeTab = tabs[0];
    chrome.tabs.sendMessage(activeTab.id, { message: ‘clicked_browser_action‘ });
  });
});

chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  if (request.message === ‘open_new_tab‘) {
    chrome.tabs.create({ url: request.url }); // Buggy line
  }
});

To debug this code, set a breakpoint on the buggy line by clicking in the gutter to the left of the line number. You should see a red dot indicating the breakpoint is set.

Now switch to the Run view and select your desired launch configuration from the dropdown. Click the green play button to start debugging.

If you chose the "launch" configuration, a new Chrome instance should open with your extension loaded. If you chose "attach", make sure your remote debugging enabled Chrome instance is running.

Perform the action that triggers your buggy code, such as clicking the browser action icon. Chrome will pause execution on the breakpoint, and VS Code will jump to the debugger view.

From here, you can step through your code using the Debug actions pane. Hover over variables to see their current values, or expand the Scope sections to drill into objects and properties. The Debug Console lets you execute arbitrary JavaScript in the current context.

Once you‘ve identified the issue, you can edit your code directly in VS Code. Chrome will automatically reload your extension with the changes. Remove the breakpoint and click the Continue button to resume execution.

Tips and Troubleshooting

Here are a few tips to keep in mind when debugging Chrome extensions in VS Code:

• To debug content scripts, set breakpoints directly in the content script files. When the breakpoint is hit, execution will pause in VS Code.
• To debug popup pages, open the popup in Chrome and then open the Chrome DevTools (F12). Under the Sources tab, look for your extension‘s ID and open the popup script to set breakpoints.
• If your breakpoints aren‘t hitting, try reloading the extension in Chrome using the Extensions page‘s reload button. Also verify that your extension is loading properly and that scripts are being injected.
• If remote debugging stops working, restart your remote debugging enabled Chrome instance.
• The Network and Application tabs of the Chrome DevTools are great for debugging background requests and inspecting storage.

Conclusion

Debugging Chrome extensions in VS Code is a powerful way to understand and troubleshoot your extension‘s behavior. By following the steps in this guide, you can configure VS Code to launch or attach to Chrome, set breakpoints, and step through your code. You also learned some tips and tricks for common debugging scenarios.

While the debugger is a fantastic tool, remember that sometimes the best debugger is taking a step back and analyzing your code with fresh eyes. Try explaining the problem out loud, or take a break and come back to it later. With practice and experience, debugging will become second nature.

Now go forth and squash those extension bugs! Happy debugging!