Skip to content

Latest commit

 

History

History
111 lines (85 loc) · 6.81 KB

README.md

File metadata and controls

111 lines (85 loc) · 6.81 KB
Raw

Adblocker

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

Github Actions Build Status Github Actions Assets Status Blazing Fast npm version weekly downloads from npm
code style: prettier Follow Ghostery on Twitter Dependabot License Badge

The Ghostery 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:

Getting Started

The Ghostery 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 @ghostery/adblocker-webextension
  2. Add the following in your background script:
import { WebExtensionBlocker } from '@ghostery/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. Enable corepack: corepack enable,
  3. Install dependencies: yarn install --immutable,
  4. Build: yarn build,
  5. Test: yarn test,

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 for iOS.
  • Ads and trackers blocker in Electron applications, Puppeteer headless browsers, Cliqz browser, 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 ghostery/adblocker → powered by Ghostery

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

Or HTML:

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

License

Mozilla Public License 2.0