Home

Awesome

Extensions libraries

badge-open-issues badge-closed-issues badge-license

This mono-repository contains a collection of TypeScript libraries which are used in AdGuard browser extensions and other projects.

Packages

The following packages are available in this repository:

Package NameDescription
css-tokenizerA fast, spec-compliant CSS tokenizer for standard and Extended CSS.
agtreeUniversal adblock filter list parser which produces a detailed AST.
tsurlfilterA library that enforces AdGuard's blocking rules logic.
tswebextensionWraps the web extension API for use with tsurlfilter.
adguard-apiManages filter lists and ad filtering via tswebextension.
examples/manifest-v2Example using Manifest V2.
examples/manifest-v3Example using Manifest V3.
examples/tswebextension-exampleExample for tswebextension.
examples/tswebextension-mv3Example for tswebextension using Manifest V3.

Detailed information on each package is available in the ./packages directory.

Development

Prerequisites

Ensure that the following software is installed on your computer:

[!NOTE] For development, our team uses macOS and Linux. It may be possible that some commands not work on Windows, so if you are using Windows, we recommend using WSL or a virtual machine.

Environment Setup

Install dependencies with pnpm: pnpm install.

[!NOTE] pnpm currently doesn't support installing per package dev dependencies (see https://github.com/pnpm/pnpm/issues/6300).

[!NOTE] If you want to use another linked packages in monorepo workspace, link it in root folder.

This repository uses pnpm workspaces and Lerna to manage multiple packages in a single repository.

Development Commands

[!NOTE] You can find Lerna commands in the following link: Lerna Commands.

Linking packages from this monorepo to another projects

pnpm has a nested structure for packages, which is not compatible with the classic yarn, because yarn using a flat structure, but you can force pnpm to use a flat structure too by setting the --shamefully-hoist flag.

For example, if you want to link the tswebextension package from this monorepo to the browser extension project which are using yarn, you can follow these steps:

  1. Install packages in this monorepo with pnpm install --shamefully-hoist.
  2. Go to the tswebextension package directory: cd packages/tswebextension, and run yarn link.
  3. Go to the browser extension project directory: cd /path/to/browser-extension, and run yarn link @adguard/tswebextension. This way, the browser extension project will use the linked package from this monorepo, instead of the published one from the npm registry.

If the other project are using pnpm, you can use pnpm link to connect the packages locally. For more details, please check the pnpm documentation.

Notice about zod package versions

Within this monorepo, zod is utilized for data validation. There are instances where a zod schema is exported from one package for use in another. However, this can potentially lead to issues if the zod versions across these packages differ. For more context, refer to this issue. To prevent this problem, it is required to maintain uniformity by using the same zod version across all packages in the monorepo.

Sample extensions

Source code of sample extensions can be found in ./packages/examples directory.

You can build them using the following commands:

To test if this extension works correctly you can use the following test pages:

Test pages:

VSCode Workspace

If you're using Visual Studio Code for development, it may be easier to work with the monorepo if you use the workspace functionality. To do this, create a tsurlfilter.code-workspace file in the monorepo root directory.

jest.runMode and jest.enable would be useful to those that use Jest plugin.

{
    "folders": [
        { "path": "packages/tsurlfilter" },
        { "path": "packages/tswebextension" },
        { "path": "packages/agtree" },
        { "path": "packages/css-tokenizer" },
        { "path": "packages/adguard-api" },
        { "path": "packages/examples/adguard-api" },
        { "path": "packages/examples/tswebextension-mv2" },
        { "path": "packages/examples/tswebextension-mv3" }
    ],
    "settings": {
        "jest.runMode": "on-demand",
        "jest.enable": true
    }
}