@cliqz/adblocker-webextension

@cliqz/adblocker-webextension

@cliqz/adblocker enhanced with convenient WebExtension wrapper

Features

• extremely efficient adblocker (both in memory usage and raw speed)
• pure JavaScript implementation
• first-class support for Node.js, WebExtension, Electron and Puppeteer.
• effectively blocks all types of ads and tracking
• supports cosmetics and scriptlet injection
• small and minimal (only 64KB minified and gzipped)
• support most filters: Easylist and uBlock Origin formats

The library provides all necessary building blocks to create a powerful and efficient content-blocker and gives full flexibility as to which lists should be used and how they should be fetched or updated. Being a pure JavaScript library it does not make any assumption regarding the environment it will run in (apart from the availability of a JavaScript engine) and is trivial to include in any new project. It can also be used as a building block for tooling.

For more details, check-out the following specialized guides:

• Node.js, @cliqz/adblocker
• Puppeteer, @cliqz/adblocker-puppeteer (demo)
• Electron, @cliqz/adblocker-electron (demo)

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();
});

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`!
});