Adblocker

Efficient, pure-Javascript, multi-platform adblocker library, by Cliqz.

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.

Getting Started

Using @cliqz/adblocker you can start blocking ads in only a few steps. Here is an example to block ads in a WebExtension (compatible with Chrome and Firefox):

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

Put this in your background code:

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

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

Congratulations, you are now blocking all ads!

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

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

Performance

To make sure content blocking can run at full-speed on a variety of devices (including low-end mobile phones), we built the library with performance in mind from the ground-up. From our recent performance study, we perform consistently better than popular alternatives in terms of: memory consumption, start from cache time, matching speed and size of cache.

Matching speed corresponds to the time it takes to decide if a network request should be blocked or allowed. It needs to be as fast as possible to not induce any significant over-head in the browser:

Memory usage is another very important dimension. Here is the memory used after initialization:

Cache size corresponds to the size in bytes of the Uint8Array returned by engine.serialize():

Another interesting metric is the time it takes to initialize the FiltersEngine instance from its serialized form. It is especially beneficial for mobile phones, because this serialized engine can be created backend-side and distributed through a CDN; which means clients do not have any cost to pay except downloading the file.

Supported Filters

The majority of the common filters are supported out of the box but some rare ones are not. To know more, check the compatibility matrix on the wiki.

Development

This project makes use of lerna and yarn workspaces (which is actually transparently used by lerna behind the scene most of the time). To get started:

fork and clone the repository: git clone git@github.com:<your remote>/adblocker.git
bootstrap: yarn bootrap
build packages: yarn bundle
start working on one of the sub-packages!

In case you have any question, feel free to open an issue or a pull request to get some help!

Who is using it?

This library is the building block technology used to power the adblockers from Ghostery and Cliqz on both desktop and mobile platforms. It is already running in production for millions of users and has been used successfully to satisfy the following use-cases:

Mobile-friendly adblocker for Android in multiple setups: react-native, WebExtension, etc. (ghostery and cliqz)
Ads and trackers blocker in Electron applications, Puppeteer headless browsers, Cliqz browser, WebExtensions (cliqz, ghostery and standalone)
Backend requests processing job in Node.js

The innovative algorithms and architecture designed and implemented in this project have been shown to be among the most efficient ways to implement ad-blockers and have been used in other projects to implement highly performant adblockers such as Brave.

Release Checklist

To publish a new version:

Bump ENGINE_VERSION in engine.ts (to invalidate serialized versions)
Create a new branch (e.g.: release-x.y.z)
Update version using lerna: npx lerna version --no-push --no-changelog --no-git-tag-version x.y.z
Update CHANGELOG.md
Create a release commit (e.g.: "Release vx.y.z")
Create a PR for the release
Merge and create a new Release on GitHub
Publish changes: npx lerna publish from-package

License

Mozilla Public License 2.0

sentialx/adblocker