Debugging Chrome Extensions
Tips and tricks for debugging browser extensions, including how to use the browser's developer tools and how to troubleshoot common issues.
Debugging browser extensions can be a daunting task. However, with a few basic tools and techniques, you can quickly diagnose and resolve many issues. In this tutorial, we'll explore how to debug a browser extension, including setting up the environment, using the browser's developer tools, and examining browser logs.
Setting up your Chrome Extension Environment
The first step in debugging a browser extension is ensuring you have the right environment set up. This includes downloading and installing the appropriate browser, along with the extension you're trying to debug. Additionally, you'll want to ensure the browser is up to date. If you’re using a framework like Plasmo, you’ll want to ensure you’re on the latest version.
Understanding Chrome Extension Components
Once the environment is set up, you can start debugging. However, you’ll quickly realize that your browser extension has multiple components, each with its own log, environment, and context.
Let’s learn how to debug with the components in mind!
How can I debug Chrome extension pages like new tab, options page, popup, or devtools?
Each extension page can be considered its own web page, with HTML, CSS, and JavaScript. Therefore, you should debug these pages just like a web page.
In all of these pages, you can right-click on an empty portion of the page and click “Inspect” which will open up your browser’s Developer Tools window.
In the example below, right-clicking on uBlock Origin’s popup window shows the Inspect button.
Clicking it opens the browser’s DevTools for that specific extension page, as seen below.
From here, you can investigate design issues by inspecting the HTML and CSS, see if there are any messages or errors in the Console, look at network requests and responses in the Network tab, and get a holistic picture of the page.
How can I debug my Chrome extension’s background service worker?
To open up your background service worker’s developer tools window, you must go to your chrome extensions dashboard. If you’re using a Chromium browser, typing “chrome://extensions” into your URL bar and pressing enter will take you there.
Find your extension, and click “service worker”
This will open the DevTools for your background service worker.
From here, the two most useful tabs will be the Console and Network tabs. When you print something out in your background service worker or when it encounters an error, you will see that in the Console tab. Any network requests will be visible in the Network tab of your service worker’s DevTools page.
How can I debug my Chrome extension’s content script?
Content scripts run in the context of an existing web page and can interact with the page’s DOM. To debug content scripts, you can open up the browser’s DevTools by right-clicking the web page the content script is running on and clicking “Inspect”. You can also use Option + ⌘ + J on macOS or Shift + CTRL + J on Windows/Linux.
From here, you can inspect the DOM to see the changes your content script has made, and investigate them to find bugs. On top of that, going to the Console or Network tab will show you errors, logs, and network requests that your content script has made.
🗣 Heads up - the Console and Network tab will also be filled with other content scripts’ activity and the web page’s activity as well as your own. You need to be mindful and make sure that you can distinguish your content script’s activity from the rest to have an effective debugging experience.
How do I debug my Chrome Extension’s performance?
A lot of times, Chrome Extensions can be resource intensive. Either because of memory leaks or because they weren’t built with performance in mind. If you’d like to debug your extension’s performance, the best way to do so is to open up the task manager.
With the Task Manager, you can see how much memory, CPU usage, and network traffic your extension uses.
The most powerful feature, however, is the fine-grained ability to see how many resources each individual service worker uses:
Easy Chrome Extension Debugging
In this article, we've explored how to debug a browser extension, including setting up the environment, using the browser's developer tools, and examining browser logs. We also discussed how to debug individual components like browser extension pages, background service workers, content scripts, and sandbox pages. Although there are a lot of moving parts, by following the steps in this post, you should be able to quickly diagnose and resolve many issues when debugging a browser extension.
Thanks for reading! We're Plasmo, a company on a mission to improve browser extension development for everyone. If you're a company looking to level up your browser extension, reach out, or sign up for Itero to get started.