mjethani / adblocker

Efficient embeddable adblocker library

Adblocker

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

---

Cliqz' adblocker is a JavaScript library for blocking ads, trackers, and annoyances with a strong focus on efficiency. It was designed with compatibility in mind and integrates seamlessly with the following environments:

• Block ads in Puppeteer,
• Block ads in Electron,
• Block ads in Chrome and Firefox,
• Or as a standalone JavaScript library.

Getting Started

Cliqz' adblocker is the easiest and most efficient way to block ads and trackers in your project. Only a few lines of code are required to integrate smoothly with Puppeteer, Electron, a Chrome- and Firefox-compatible browser extension, or any environment supporting JavaScript (e.g. Node.js or React Native).

Here is how to do it in two steps for a Chrome- and Firefox-compatible WebExtension:

1. Install: npm install --save @cliqz/adblocker-webextension
2. Add the following in your background script:

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

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

Congratulations, you are now blocking all ads and trackers! 🎉

Compatibility

The library supports 99% of all filters from the Easylist and uBlock Origin projects. Check the compatibility matrix on the wiki for more details.

Contributing

This project makes use of lerna and yarn workspaces under the hood. Quickly get started with:

1. Fork and clone the repository,
2. Install dependencies: yarn bootstrap,
3. Build: yarn watch,
4. Test: yarn test,
5. Bundle: yarn bundle.

For 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 battle-tested to satisfy the following use-cases:

• Mobile-friendly adblocker in react-native, WebExtension, or custom JavaScript context: Ghostery and Cliqz.
• Ads and trackers blocker in Electron applications, Puppeteer headless browsers, Cliqz browser, WebExtensions (cliqz, ghostery and standalone).
• Batch requests processing in Node.js, HTML fuzzy keywork matcher, and more.

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.

Swag

Show the world you're using @cliqz/adblocker →

[![powered by Cliqz](https://img.shields.io/badge/cliqz-powered-blue?logo=cliqz)](https://github.com/cliqz-oss/adblocker)

Or HTML:

<a href="https://github.com/cliqz-oss/adblocker/" target="_blank" rel="noopener noreferrer">
    <img alt="powered by Cliqz" src="https://img.shields.io/badge/cliqz-powered-blue?logo=cliqz">
</a>

License

Mozilla Public License 2.0