This article is starter of an anatomy series for dissecting AdBlock/AdBlockPlus/uBlockOrigin source code and learn how they work. First let’s start from running and debugging AdBlock locally.
Note that this article is for eyeo owned browser extension AdBlock and AdBlockPlus.
Source code
Luckily, AdBlock main source entry is using NX monorepo, where we can easily see the dependency graph within the repo below.
However, there are many core features are not within the monorepo, here is a list of important ones:
- @eyeo/webext-ad-filtering-solution: most important core adblocking features shared across extensions.
- @eyeo/snippets: eyeo developed special content scripts for element hiding and behavioral intercepting. This repo reflects everything from eyeo official developer document.
- Filter list: eyeo developed filter list mostly leveraging @eyeo/snippets for enhanced blocking.
- @adblockinc/rules: an npm package for retrieving, storing and providing filter lists from various sources for use in AdBlock and Adblock Plus.
Installation
Now let’s download the main source code and install packages:
git clone https://gitlab.com/eyeo/extensions/extensions.git
cd extensions
npm installIn often case if you are using Apple silicon chips, you will often see node-gyp errors like below:
> npm ERR! gyp ERR! stack Error: `gyp` failed with exit code: 1The extensions repo provides some potential fixes, but below commends worked for me:
python3 -m pip install setuptools
brew install pkg-config cairo pango libpng jpeg giflib librsvgBuild extension
Simply run below to build both AdBlock and AdBlockPlus extension:
npm run buildAdd extensions to Chrome
- Go to chrome://extensions/.
- At the top right, turn on Developer mode.
- Click Load unpacked.
- Find and select the app or extension folder.
- e.g. for Chrome AdBlockPlus with Manifest V2, it is located inside
/extensions/host/adblockplus/dist/devenv/chrome-mv2
- e.g. for Chrome AdBlockPlus with Manifest V2, it is located inside
Now you should be able to see the extension being added and enabled.
Debugging @eyeo/webext-ad-filtering-solution
In a lot of cases, the feature you are looking for is mostly in webext-ad-filtering-solution package. This package can be loaded as extension standalone.
Installation
git clone https://gitlab.com/eyeo/adblockplus/abc/webext-ad-filtering-solution.git
cd extensions
npm installBuild and run in watch mode
You can simply do npm run build, but I found it convenient to use watch mode:
npx webpack --watchThe built extensions can be found under dist folder
- performance-mv2 for Manifest V2
- performance-mv3 for Manifest V3
Simply add desired extension to Chrome in dev mode for debugging.
Debugging background script
Let’s go to sdk/background/index.js and add some logging:
...
export async function start(addonInfo) {
console.log("start extension");
...
}
...Then go to chrome://extensions/ and click on Inspect views -> background page (Service worker for Manifest V3 version) under eyeo's WebExtension Ad-Filtering Solution Test Extension.
You should be able to see start extension log under Console tab. You can try reload extension if not seeing the log.
Debugging content script
Let’s go to sdk/content/index.js and add some logging:
...
async function initContentFeatures() {
console.log("initContentFeatures");
...
}
...Open a new tab and go to any page, then open console and you should be able to see initContentFeatures log.