@ghostery/adblocker-electron

Electron Adblocker

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

---

Getting Started

Install: npm install --save @ghostery/adblocker-electron.

Usage

For a complete example check-out: @ghostery/adblocker-electron-example.

Creating an instance of ElectronBlocker and start blocking ads!

import { ElectronBlocker } from '@ghostery/adblocker-electron';
import fetch from 'cross-fetch'; // required 'fetch'

ElectronBlocker.fromPrebuiltAdsAndTracking(fetch).then((blocker) => {
  blocker.enableBlockingInSession(session.defaultSession);
});

You are ready to block ads!

There are other ways you can create an instance of the blocking engine to start blocking ads.

If you already have filters locally:

import { ElectronBlocker } from '@ghostery/adblocker-electron';

const blocker = ElectronBlocker.parse(fs.readFileSync('easylist.txt', 'utf-8'));

Fetching lists from URLs:

import { ElectronBlocker } from '@ghostery/adblocker-electron';
import fetch from 'cross-fetch'; // required 'fetch'

const blocker = await ElectronBlocker.fromLists(fetch, [
  'https://easylist.to/easylist/easylist.txt'
]);

Use ready-made configs to block ads and optionally trackers:

import { ElectronBlocker } from '@ghostery/adblocker-electron';
import fetch from 'cross-fetch'; // required 'fetch'

let blocker = await ElectronBlocker.fromPrebuiltAdsOnly(fetch); // ads only
blocker = await ElectronBlocker.fromPrebuiltAdsAndTracking(fetch); // ads and tracking

Disabling Blocker in session

To stop blocking ads in a session:

blocker.disableBlockingInSession(session.defaultSession);

Caching Blocker using Serialization

To avoid having to create the same instance of ElectronBlocker all over again, you can serialize it to a byte-array which you can store on disk for faster loading.

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

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

Or you can do this manually to control the way caching is done:

import { ElectronBlocker } from '@ghostery/adblocker-electron';
import fetch from 'cross-fetch'; // required 'fetch'

ElectronBlocker.fromPrebuiltAdsAndTracking(fetch).then((blocker) => {
  const buffer = blocker.serialize();
  const restoredBlocker = ElectronBlocker.deserialize(buffer);
  // `restoredBlocker` is deep-equal to `blocker`!
});

Changelog

v2.0.1 (Mon Oct 21 2024)

:bug: Bug Fix

• @ghostery/adblocker-electron-preload, @ghostery/adblocker-electron
  • packages: adblocker-electron{-preload}: make use of executeJavaScript #4278 (@nullptropy)

:house: Internal

• @ghostery/adblocker
  • Update local assets #4377 ([e-mail] @ghostery-adblocker-bot[bot])
  • Update local assets #4374 ([e-mail] @ghostery-adblocker-bot[bot])

:memo: Documentation

• @ghostery/adblocker-webextension
  • Fixed a typo in the title #4373 (@philipp-classen)

:nut_and_bolt: Dependencies

• Build(deps-dev): Bump eslint from 9.12.0 to 9.13.0 #4380 (@dependabot[bot])
• Build(deps-dev): Bump @types/node from 22.7.6 to 22.7.7 #4379 (@dependabot[bot])
• Build(deps-dev): Bump @eslint/js from 9.12.0 to 9.13.0 #4378 (@dependabot[bot])
• Build(deps-dev): Bump typescript-eslint from 8.9.0 to 8.10.0 #4375 (@dependabot[bot])
• Build(deps): Bump tldts-experimental from 6.1.51 to 6.1.52 #4368 (@dependabot[bot])
• Build(deps): Bump electron from 33.0.0 to 33.0.1 #4369 (@dependabot[bot])
• Build(deps-dev): Bump @types/node from 22.7.5 to 22.7.6 #4371 (@dependabot[bot])
• Build(deps): Bump playwright from 1.48.0 to 1.48.1 #4372 (@dependabot[bot])
• @ghostery/adblocker-puppeteer
  • Build(deps): Bump puppeteer from 23.5.3 to 23.6.0 #4370 (@dependabot[bot])

Authors: 5

• @dependabot[bot]
• @ghostery-adblocker-bot[bot]
• @nullptropy
• Ghostery Adblocker Bot ([e-mail])
• Philipp Claßen (@philipp-classen)

---