Skip to content
A fast, pure-JavaScript content-blocking library
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bench Tldts experimental (#183) Jul 3, 2019
packages Bump @ampproject/rollup-plugin-closure-compiler from 0.9.0 to 0.10.0 (#… Jul 15, 2019
.dockerignore move to multi-packages repository using lerna (#181) Jul 3, 2019
.editorconfig Update comparison (#102) Feb 12, 2019
.eslintrc Benchmark framework + bug fixes (#31) Sep 25, 2018
.gitignore move to multi-packages repository using lerna (#181) Jul 3, 2019
.prettierrc.json Add support for $badfilter option (#127) Apr 23, 2019
.travis.yml Tldts experimental (#183) Jul 3, 2019
CHANGELOG.md allow the 'not' pseudoclass in cosmetic filters (#184) Jul 3, 2019
Dockerfile move to multi-packages repository using lerna (#181) Jul 3, 2019
LICENSE Add copyright notice in LICENSE and source files (#161) May 20, 2019
README.md move to multi-packages repository using lerna (#181) Jul 3, 2019
commitlint.config.js move to multi-packages repository using lerna (#181) Jul 3, 2019
jest.config.js Cosmetic bucket performance improvements + stabilizations (#163) May 29, 2019
lerna-lint.js docs: update package.json with list of contributors (#185) Jul 3, 2019
lerna.json move to multi-packages repository using lerna (#181) Jul 3, 2019
licenser.js move to multi-packages repository using lerna (#181) Jul 3, 2019
package.json docs: update package.json with list of contributors (#185) Jul 3, 2019
run_tests.sh Tldts experimental (#183) Jul 3, 2019
tsconfig.json move to multi-packages repository using lerna (#181) Jul 3, 2019
tslint.json move to multi-packages repository using lerna (#181) Jul 3, 2019
yarn.lock Bump @types/node from 12.6.3 to 12.6.6 (#199) Jul 17, 2019

README.md

Adblocker

Very fast and memory efficient, pure-JavaScript content-blocking library made by Cliqz.

This library is the building block technology used to power the adblockers from Ghostery and Cliqz on both desktop and mobile platforms. 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. 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

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.

Installation

Multiple specialized packages are available to satisfy different needs:

  • @cliqz/adblocker (core logic of content blocking)
  • @cliqz/adblocker-webextension
  • @cliqz/adblocker-puppeteer
  • @cliqz/adblocker-electron

Checkout detailed documentation for each of these packages in the packages directory.

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:

  1. fork and clone the repository: git clone git@github.com:<your remote>/adblocker.git
  2. bootstrap: npx lerna bootstrap
  3. 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!

Release Checklist

To publish a new version:

  1. Bump ENGINE_VERSION in engine.ts (to invalidate serialized versions)
  2. Create a new branch (e.g.: release-x.y.z)
  3. Update version in package.json
  4. Update CHANGELOG.md
  5. Create a release commit (e.g.: "Release vx.y.z")
  6. Create a PR for the release
  7. Merge and create a new Release on GitHub
  8. Travis takes care of the rest!

License

Mozilla Public License 2.0

You can’t perform that action at this time.