AdGuard Extensions Libraries

Note: This package is developed in AdGuardSoftwareLimited/ext-tsurlfilter. The AdguardTeam/tsurlfilter repository is a public mirror.

This monorepo provides a full stack of TypeScript libraries for content blocking in browser extensions. It covers every layer — from filter list parsing and rule matching to browser extension integration and high-level extension APIs — and is used in AdGuard browser extensions and other projects.

Key Concepts

The libraries are organized in layers, each building on the previous one:

1. Parsing — css-tokenizer and agtree turn raw filter list text into structured tokens and AST nodes.
2. Matching — tsurlfilter takes parsed rules, builds lookup tables, and evaluates network requests and cosmetic rules against them.
3. Extension integration — tswebextension wraps the browser WebExtension API (both MV2 and MV3) to apply filtering decisions from the engine.
4. High-level API — adguard-api and adguard-api-mv3 add filter list management (downloading, caching, auto-updates) on top of tswebextension.

Supporting packages include logger (logging), dnr-rulesets (prebuilt Declarative Net Request rulesets for MV3), dnr-converter (converts adblock rules to DNR format), and eslint-plugin-logger-context (ESLint rule for logger call formatting).

Packages

Core Libraries

Package	Description
@adguard/tswebextension	Wraps the browser WebExtension API to integrate tsurlfilter into MV2 and MV3 extensions.
@adguard/tsurlfilter	Content blocking engine — parses AdGuard rules, matches requests, and applies filtering logic.
@adguard/agtree	Universal adblock filter list parser, converter, and validator producing a detailed AST.
@adguard/dnr-converter	Converts adblock-style filtering rules into rules compatible with the Declarative Net Request (DNR) API.
@adguard/dnr-rulesets	CLI and library for building and loading prebuilt AdGuard DNR rulesets for MV3 extensions.
@adguard/api	High-level filtering API for MV2 extensions — manages filter lists and delegates blocking to tswebextension.
@adguard/api-mv3	High-level filtering API for MV3 extensions — MV3 counterpart of @adguard/api.
@adguard/logger	Lightweight logging library with configurable levels and custom writers.
@adguard/css-tokenizer	Fast, spec-compliant CSS tokenizer for standard and Extended CSS.
@adguard/eslint-plugin-logger-context	ESLint plugin that enforces context tags in @adguard/logger calls.

Examples and Benchmarks

Package	Description
examples/adguard-api	Sample MV2 extension using @adguard/api.
examples/adguard-api-mv3	Sample MV3 extension using @adguard/api-mv3.
examples/tswebextension-mv2	Sample MV2 extension using @adguard/tswebextension directly.
examples/tswebextension-mv3	Sample MV3 extension using @adguard/tswebextension directly.
benchmarks	Benchmark docs — benchmarks themselves are co-located in each package as test/**/*.bench.ts.

Dependency Tree

graph TD
    css-tokenizer --> agtree
    css-tokenizer --> tsurlfilter
    agtree --> tsurlfilter
    agtree --> tswebextension
    agtree --> dnr-converter
    tsurlfilter --> tswebextension
    tsurlfilter --> dnr-rulesets
    logger --> tswebextension
    logger --> dnr-rulesets
    logger --> dnr-converter
    dnr-converter --> tswebextension
    dnr-converter --> dnr-rulesets
    tswebextension --> api
    tswebextension --> api-mv3

Loading

Documentation

See each package's README for installation and usage instructions.

• Development guide — environment setup, build commands, and contribution workflow
• LLM agent rules — project context for AI coding assistants
• Changelog per package — each package has its own CHANGELOG.md
• License