Ghostery adblocker: a filter engine you embed instead of a browser extension you install

A library you embed, not an extension you install

The Ghostery adblocker is a JavaScript library for blocking ads, trackers and annoyances, with a strong focus on efficiency. The framing in the documentation is that it was designed with compatibility in mind and integrates with a list of environments: block ads in Puppeteer, block ads in Electron, block ads in Chrome and Firefox, or use it as a standalone JavaScript library in any environment supporting JavaScript, such as Node.js or React Native.

That last option is the one that matters for the design. This is not a browser extension with a settings page and a subscription updater. It is an engine, and the host is whatever you already have. A team that ships an Electron desktop app, or runs a headless browser for scraping or testing, or builds its own extension, gets ad and tracker blocking as a dependency rather than as a separate product.

The upstream is Ghostery, and the same library powers the adblockers from Ghostery and Cliqz on desktop and mobile, according to the documentation. The stated production use cases are a mobile-friendly adblocker in React Native, a WebExtension or a custom JavaScript context, an Electron application, Puppeteer headless browsers, the Cliqz browser, the Ghostery extension, and a standalone build. The documentation also lists batch request processing in Node.js and an HTML fuzzy keyword matcher among the things the library is used for.

The project is a TypeScript monorepo published under the `@ghostery` scope on npm, with the root package marked private and the workspace covering `packages/*`.

Four packages for four hosts

The package structure is the clearest way to understand the integration surface, and the repository lists four of them at the top of the readme.

`@ghostery/adblocker` is the core library for Node.js, React Native or any JavaScript environment, and it is where the filtering engine lives. `@ghostery/adblocker-puppeteer` wraps it for Puppeteer, giving a headless browser the ability to block requests as the page loads. `@ghostery/adblocker-electron` does the same for Electron applications, which is a different problem because an Electron app runs a browser process you do not own. `@ghostery/adblocker-webextension` is the WebExtension build, for a Chrome and Firefox compatible extension of your own.

The split is not arbitrary duplication. Each host has a different interception point: a Puppeteer page has a request interception hook, an Electron session has its own webRequest layer, and a WebExtension has the declarativeNetRequest and webRequest APIs. The core engine is shared, and the adapters deal with the plumbing.

For a user, the practical implication is that you pick the one package matching your host and you do not need to think about the others. There is also a set of example directories in the repository, for Puppeteer, for Electron, and for the WebExtension, which the readme links to as the reference for a working integration.

Two steps to a working WebExtension integration

The readme shows a Chrome and Firefox compatible WebExtension in two steps. The install is an npm dependency:

npm install --save @ghostery/adblocker-webextension

and the background script then enables blocking:

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

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

The shape of that snippet is the API design in miniature. The blocker is constructed asynchronously from a prebuilt bundle, `fromPrebuiltAdsAndTracking`, which means the filter data ships with the library rather than being fetched at runtime, and then a single call turns on blocking in the host environment.

That last detail is the one to think about carefully, because it decides how often your build is updated. A prebuilt bundle is convenient and deterministic, and it also means the filter lists are frozen at the version of the package you depend on. A product that wants its block list refreshed daily has to rebuild or repackage; the readme does not describe a subscription or update mechanism for the filter data, so the update cadence is something the integrating team has to define.

The same two step pattern applies to the other hosts. The Puppeteer and Electron packages have their own enable call, and the readme points to the example projects for each.

Filter compatibility, and where the performance argument comes from

An adblocker engine is only useful if it understands the filter syntax people actually publish, and the documentation's answer is a compatibility claim: the library supports 99 percent of all filters from the Easylist and uBlock Origin projects, with a compatibility matrix on the wiki for the details.

Ninety-nine percent is a good number and also an admission that something does not work. The matrix on the wiki is the place to check whether the filters your application depends on are in the unsupported remainder, and that check belongs in your evaluation rather than after deployment.

The efficiency story is argued by reference to an external study, the adblockers performance study on whotracks.me, and the readme says the algorithms and architecture in this project have been shown to be among the most efficient ways to implement adblockers. The same paragraph notes that the approach has been used in other projects to build highly performant adblockers, with Brave's adblock-rust given as the example.

The repository backs this with a `bench/` directory at the root and a `benchmark` dev dependency, so the performance claims are at least measurable by the project itself rather than asserted.

Building the monorepo with yarn 4 and lerna

The contributing instructions are short and reflect a workspace setup that has been modernised recently. The project uses lerna and yarn workspaces under the hood, and the manifest pins `[email protected]` as the package manager.

The sequence is:

corepack enable
yarn install --immutable
yarn build
yarn test

Step one forks and clones the repository, step two enables corepack so the pinned Yarn version is used, step three installs dependencies with the immutable flag so the lockfile cannot drift, and then the build and test scripts run across the workspaces.

The root scripts show how the monorepo is wired. `build` runs `lerna run build`, `test` runs `yarn workspaces foreach -A run test`, `lint` runs the lint script in parallel across packages, and `clean` tears down both the package outputs and the lerna state. Formatting is prettier over the TypeScript sources with separate check and write scripts, and the eslint configuration is a flat config file, `eslint.config.js`, which is the modern style.

The release path is `auto shipit -v`, and the repository also carries a `CHANGELOG.md`, a `.mocharc.json` for the test runner configuration, and a `lgtm.yml` from the earlier code scanning era.

Where the Ghostery adblocker is the wrong tool

The boundaries are clear once you understand that this is an engine with a specific host in mind.

The first is scope. It blocks requests that match filters. It does not, on its own, stop first-party tracking, does not fingerprint, does not isolate your browsing, and does not clean up the pages of a site that has already served you a tracker through a first-party script. An adblocker is a filter list applied to requests, and a product that promises privacy has to build the rest.

The second is that it does not manage filter subscriptions. The prebuilt bundle approach is the right one for a library, and it means the update cadence of your block list is a decision your team has to make and schedule, not something the library does for you. A product shipping to millions of users has to build that pipeline.

The third is the host list. There are packages for Node.js, Puppeteer, Electron and WebExtension, and there is no Safari package in the repository. An application targeting Safari's extension model has to use the WebExtension package and hope the APIs line up, and the readme does not claim Safari support.

The fourth is the licence, and it is worth reading rather than assuming. The project is MPL-2.0, the Mozilla Public License 2.0, which is file level copyleft rather than the permissive terms most of your application code carries. If you modify the library's own files, those modified files must stay available under the same licence when you distribute them. If you only call the library and never touch its source, the obligation does not reach your code. That distinction matters, and it is the kind of thing to check with whoever owns your licence compliance, not with this article.

The fifth is the Electron and Puppeteer caveat. Those adapters work by intercepting requests in a browser you partly control, and the documentation does not describe what happens on the requests an application makes outside the browser session, such as a Node.js fetch in the main process.

MPL-2.0, a busy release line, and a library with a public user list

The licence is the Mozilla Public License 2.0, with the licence file at the repository root and the readme stating it plainly. The manifest agrees, with `"license": "MPL-2.0"`.

The release cadence is regular and the version numbers are high for a library that started as an internal component. v2.18.2 was published on 2026-08-05, and both v2.20.0 and v2.20.1 on 2026-10-09, with the last push to the repository on 2026-10-19. Patch releases within a day of each other are the pattern of a project that ships the filter data alongside the code, which is consistent with the prebuilt bundle design.

The user list in the readme is the kind of detail that usually matters more than a badge. The library is described as the building block technology behind the adblockers from Ghostery and Cliqz on desktop and mobile, already running in production for millions of users, and as the basis for specific named products, including a React Native based Ghostery for iOS, an Electron desktop application, Puppeteer based headless browsers, the Cliqz browser, the Ghostery extension, and a standalone build.

The one piece of the readme that is purely marketing is the badge section at the end, which shows how to display a powered by Ghostery badge. It is harmless, but it is the only part of this file you can skip when you are deciding whether the engine fits.

Editorial conclusion

Ghostery adblocker fits a team shipping a privacy feature inside a product it controls, whether that product is an Electron app, a headless browser pipeline, a browser extension of its own, or a React Native application. It does not fit a user who wants a personal ad blocker, since the work of building one is all on them, and it is the wrong tool for a team that needs to filter arbitrary HTML in bulk as a library call, where the batch processing support is a use case rather than a documented API. Before you adopt it, check the compatibility matrix on the wiki against the filters you rely on, and read the MPL-2.0 file, since the licence is file level copyleft rather than the permissive terms most application code carries.

Frequently asked questions

Official sources

1. ghostery/adblocker on GitHub
2. License: MPL-2.0
3. Project website
4. README
5. Releases