README.md

Pupeteer Adblocker

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

---

Getting Started

Install: npm install --save @cliqz/adblocker-puppeteer.

Usage

For a complete example check-out: @cliqz/adblocker-puppeteer-example.

Creating an instance of PuppeteerBlocker and start blocking ads!

import puppeteer from 'puppeteer';
import { PuppeteerBlocker } from '@cliqz/adblocker-puppeteer';
import fetch from 'cross-fetch'; // required 'fetch'

const browser = await puppeteer.launch();
const page = await browser.newPage();

PuppeteerBlocker.fromPrebuiltAdsAndTracking(fetch).then((blocker) => {
  blocker.enableBlockingInPage(page);
});

You are ready to block ads!

By default, using the ad blocker disables the browser's built-in resource cache. Pass the cacheSafe option to enableBlockingInPage to enable the cache. Learn more in puppeteer's documentation. Be careful when using the cache. You may have problems loading some webpages.

PuppeteerBlocker.fromPrebuiltAdsAndTracking(fetch).then((blocker) => {
  blocker.enableBlockingInPage(page, { cacheSafe: true });
});

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

If you already have filters locally:

import { PuppeteerBlocker } from '@cliqz/adblocker-puppeteer';

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

Fetching lists from URLs:

import { PuppeteerBlocker } from '@cliqz/adblocker-puppeteer';
import fetch from 'cross-fetch'; // required 'fetch'

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

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

import { PuppeteerBlocker } from '@cliqz/adblocker-puppeteer';
import fetch from 'cross-fetch'; // required 'fetch'

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

Disabling Blocker in page

To stop blocking ads in a page:

await blocker.disableBlockingInPage(page);

Caching Blocker using Serialization

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

import puppeteer from 'puppeteer';
import { PuppeteerBlocker } from '@cliqz/adblocker-puppeteer';
import fetch from 'cross-fetch'; // required 'fetch'
import { promises as fs } from 'fs'; // used for caching

const browser = await puppeteer.launch();
const page = await browser.newPage();

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

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

import { PuppeteerBlocker } from '@cliqz/adblocker-puppeteer';
import fetch from 'cross-fetch'; // required 'fetch'

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