DOCSEARCHbyAlgolia
Submit Docs

Ghostery Adblocker

repository·master·Indexed 21 days ago

https://github.com/ghostery/adblocker

An efficient, minimal JavaScript/TypeScript library for blocking ads, trackers, and annoyances. Compatible with uBlock Origin and Easylist, it provides specialized integrations for Node.js, Puppeteer, Electron, and WebExtensions via packages such as @ghostery/adblocker-content, @ghostery/adblocker-electron, @ghostery/adblocker-playwright, and @ghostery/adblocker-puppeteer.

Tokens
28K
Snippets
109
Records
129
Agent score
68%

What's inside ghostery-adblocker

  1. Overview of @ghostery/adblocker-content

    master
    The @ghostery/adblocker-content package is a high-performance, minimal JavaScript/TypeScript library designed for content blocking. It is compatible with uBlock Origin and Easylist rules. This package serves as a core component within the larger @ghostery/adblocker ecosystem, providing the logic necessary for content-based ad blocking across various environments including Node.js, Puppeteer, Electron, and WebExtensions.

  2. Overview of @ghostery/adblocker-extended-selectors

    master
    The @ghostery/adblocker-extended-selectors package provides efficient and minimal selector logic for adblocking. It is designed to be compatible with uBlock Origin and Easylist syntax. This package is a component of the larger @ghostery/adblocker ecosystem and is used by various integrations including Node.js, Puppeteer, Electron, and WebExtensions to handle advanced selector matching.

  3. Overview of Ghostery Adblocker environments

    master

    The Ghostery adblocker is a high-performance JavaScript/TypeScript library compatible with uBlock Origin and Easylist. It can be used in several specific environments:

    • Puppeteer: For headless browser automation.
    • Electron: For desktop applications.
    • WebExtension: For Chrome and Firefox browser extensions.
    • Standalone: As a pure JavaScript library in Node.js, React Native, or any other JS environment.

  4. Cache ElectronBlocker using Serialization

    master

    To improve startup performance and avoid re-fetching/re-parsing lists, you can serialize the ElectronBlocker instance to a byte-array and store it on disk. You can either use the built-in automatic caching via options or handle serialization manually.

    import { ElectronBlocker } from '@ghostery/adblocker-electron';
import fetch from 'cross-fetch';
import { promises as fs } from 'fs';

// Automatic caching via options
ElectronBlocker.fromPrebuiltAdsAndTracking(fetch, {
  path: 'engine.bin',
  read: fs.readFile,
  write: fs.writeFile,
}).then((blocker) => {
  blocker.enableBlockingInSession(session.defaultSession);
});

  5. Combine network filtering and cosmetics in a WebExtension

    master

    To achieve full ad-blocking capabilities (both network request filtering and cosmetic/element hiding), you must use both packages in tandem:

    1. Background Script: Set up @ghostery/adblocker-webextension to handle network filtering.
    2. Content Script: Use @ghostery/adblocker-webextension-cosmetics (via injectCosmetics()) to handle cosmetic injection in frames.

  6. Filter compatibility with Easylist and uBlock Origin

    master
    The library supports approximately 99% of all filters from the Easylist and uBlock Origin projects. For a detailed breakdown, refer to the compatibility matrix on the project's wiki.

  7. Use WebExtensionBlocker to block ads in a background page

    master

    To start blocking ads from your extension's background page, use WebExtensionBlocker.fromPrebuiltAdsAndTracking().

    Note for Chromium-based browsers: You must use a polyfill like webextension-polyfill to provide the browser object required by enableBlockingInBrowser().

    import { browser } from 'webextension-polyfill';
import { WebExtensionBlocker } from '@ghostery/adblocker-webextension';

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

  8. Cache PuppeteerBlocker using serialization

    master

    To improve performance and avoid re-fetching/re-parsing filters on every run, you can serialize the PuppeteerBlocker instance to a byte-array and store it on disk.

    Automatic Caching

    Pass a configuration object to the factory method containing path, read, and write functions (e.g., using fs.promises):

    import { promises as fs } from 'fs';

PuppeteerBlocker.fromPrebuiltAdsAndTracking(fetch, {
  path: 'engine.bin',
  read: fs.readFile,
  write: fs.writeFile,
}).then((blocker) => {
  blocker.enableBlockingInPage(page);
});

    Manual Serialization

    You can manually control the process using serialize() and deserialize():

    const buffer = blocker.serialize();
const restoredBlocker = PuppeteerBlocker.deserialize(buffer);
// `restoredBlocker` is deep-equal to `blocker`!
    import { PuppeteerBlocker } from '@ghostery/adblocker-puppeteer';
import fetch from 'cross-fetch';

// Manual approach
PuppeteerBlocker.fromPrebuiltAdsAndTracking(fetch).then((blocker) => {
  const buffer = blocker.serialize();
  const restoredBlocker = PuppeteerBlocker.deserialize(buffer);
});

  9. Run the Puppeteer Adblocker Example

    master

    To run the Puppeteer adblocking example, you can build the project and then start it using either CommonJS or ESM modules. This example demonstrates how to use @ghostery/adblocker-puppeteer to block ads within a Puppeteer browser instance.

    # Build the project
$ yarn build

# Start as a CommonJS module
$ yarn start:commonjs

# Or start as an ESM module
$ yarn start:esm

  10. Install @ghostery/adblocker-playwright

    master

    Install the Playwright adblocker package via npm to use it in your Playwright automation scripts.

    npm install --save @ghostery/adblocker-playwright

  11. Use @ghostery/adblocker-webextension-cosmetics in a content script

    master

    The @ghostery/adblocker-webextension-cosmetics package is a companion to @ghostery/adblocker-webextension. It is designed to be used within a content script to enable communication with the background script and to inject cosmetics (CSS/styling rules) into frames.

    To enable cosmetic filtering, import and call injectCosmetics() from your content script.

    import { injectCosmetics } from '@ghostery/adblocker-webextension-cosmetics';

injectCosmetics();