@cliqz/adblocker-webextension

WebExtenstion Adblocker

Efficient · Minimal · JavaScript · TypeScript · uBlock Origin- and Easylist-compatible
Node.js · Puppeteer · Electron · WebExtension

---

Getting Started

Install: npm install --save @cliqz/adblocker-webextension.

Usage

For a complete example check-out: @cliqz/adblocker-webextension-example.

Creating an instance of WebExtensionBlocker and start blocking ads!

From the background page of your extension:

import { WebExtensionBlocker } from '@cliqz/adblocker-webextension';

WebExtensionBlocker.fromPrebuiltAdsAndTracking().then((blocker) => {
  blocker.enableBlockingInBrowser(browser);
});

On Chromium-based browsers you will need a polyfill such as webextension-polyfill to get this working:

import { browser } from 'webextension-polyfill-ts';
import { WebExtensionBlocker } from '@cliqz/adblocker-webextension';

WebExtensionBlocker.fromPrebuiltAdsAndTracking().then((blocker) => {
  blocker.enableBlockingInBrowser(browser);
});

You are ready to block ads!

There are other ways you can create an instance of the blocking engine to start blocking ads.

If you already have filters locally:

import { WebExtensionBlocker } from '@cliqz/adblocker-webextension';

const blocker = WebExtensionBlocker.parse(fs.readFileSync('easylist.txt', 'utf-8'));

Fetching lists from URLs:

import { WebExtensionBlocker } from '@cliqz/adblocker-webextension';

const blocker = await WebExtensionBlocker.fromLists(fetch, [
  'https://easylist.to/easylist/easylist.txt'
]);

Use ready-made configs to block ads and optionally trackers:

import { WebExtensionBlocker } from '@cliqz/adblocker-webextension';

let blocker = await WebExtensionBlocker.fromPrebuiltAdsOnly(); // ads only
blocker = await WebExtensionBlocker.fromPrebuiltAdsAndTracking(); // ads and tracking

Disabling Blocker in extension

To stop blocking ads:

blocker.disableBlockingInBrowser();

Caching Blocker using Serialization

To avoid having to create the same instance of WebExtensionBlocker all over again, you can serialize it to a byte-array which you can store on disk for faster loading.

import { WebExtensionBlocker } from '@cliqz/adblocker-webextension';

WebExtensionBlocker.fromPrebuiltAdsAndTracking().then((blocker) => {
  const buffer = blocker.serialize();
  const restoredBlocker = WebExtensionBlocker.deserialize(buffer);
  // `restoredBlocker` is deep-equal to `blocker`!
});

Changelog

v1.28.1 (Mon Jul 15 2024)

:bug: Bug Fix

• @cliqz/adblocker-content, @cliqz/adblocker-electron-preload, @cliqz/adblocker-electron, @cliqz/adblocker-extended-selectors, @cliqz/adblocker-playwright, @cliqz/adblocker-puppeteer, @cliqz/adblocker-webextension-cosmetics, @cliqz/adblocker-webextension, @cliqz/adblocker
  • Simplify build with tshy #4079 (@chrmod @seia-soto)

:nut_and_bolt: Dependencies

• Build(deps-dev): Bump @remusao/auto-config from 1.1.2 to 1.2.0 #4083 (@dependabot[bot])
• Build(deps-dev): Bump @eslint/js from 9.6.0 to 9.7.0 #4089 (@dependabot[bot])
• Build(deps-dev): Bump prettier from 3.3.2 to 3.3.3 #4090 (@dependabot[bot])
• Build(deps-dev): Bump typescript-eslint from 8.0.0-alpha.41 to 8.0.0-alpha.44 #4091 (@dependabot[bot])

Authors: 3

• @dependabot[bot]
• HoJeong Go (@seia-soto)
• Krzysztof Modras (@chrmod)

---