Repository files navigation

AdGuard is a fast and lightweight ad blocking browser extension
that effectively blocks all types of ads and trackers.

AdGuard.com |Reddit |Twitter |Telegram

AdGuard is a fast and lightweight ad blocking browser extension that effectively blocks all types of ads and trackers on all web pages. We focus on advanced privacy protection features to not just block known trackers, but prevent web sites from building your shadow profile. Unlike its standalone counterparts (AG for Windows, Mac), the browser extension is completely free and open source. You can learn more aboutthe difference here.

AdGuard does not collect any information about you, and does not participate in any acceptable ads program. The only source of income we have is selling premium versions of our software, and we intend to keep it that way.

• Installation
  • Chrome and Chromium-based browsers
  • Firefox
  • Opera
  • Microsoft Edge
• Contribution
  • Translating AdGuard
  • Testing AdGuard
  • Reporting issues
  • Other options
• Development
  • Requirements
  • How to build
    • Tests and dev build
    • Linking with the developer build of tsurlfilter/tswebextension
    • Building the beta and release versions
    • Special building instructions for Firefox reviewers
    • Analyzing bundle size
    • Debug MV3 declarative rules
  • Linter
  • Update localizations
  • Bundle Size Monitoring
• Permissions required
• Auto-publish builds
• Minimum supported browser versions

You can get the latest available AdGuard Extension version from theChrome Web Store.

You can get the latest version of AdGuard Extension from theMozilla Add-ons website.

Opera is basically a Chromium browser, but it maintains its own add-ons store.You can get AdGuard Extensionfrom there.

The latest stable version of AdGuard browser extension is available inMicrosoft Store.

We are blessed to have a community that does not only love AdGuard, but alsogives back. A lot of people volunteer in various ways to make other users'experience with AdGuard better, and you can join them!

We, on our part, can only be happy to reward the most active members of thecommunity. So, what can you do?

If you want to help with AdGuard translations, please learn more abouttranslating our products here:https://adguard.com/kb/miscellaneous/contribute/translate/program/

You can get a beta version of AdGuard Browser Extension for any browser.All necessary information on this topic can be found on adedicated page on our website.

GitHub can be used to report a bug or to submit a feature request. To do so, gotothis pageand click theNew issue button.

Here is adedicated page for those whoare willing to contribute.

Ensure that the following software is installed on your computer:

• Node.js: v22 (you can install multiple versions usingnvm)
• pnpm: v10
• Git

Install local dependencies by running:

pnpm install

Running unit tests:

pnpmtest

Running integration tests:

pnpm test:integration<MODE># MODE can be 'dev', 'beta', 'release', same as build targets.

Running integration tests with enabling debug mode (page will be stopped aftertests execution) for one of them:

pnpm test:integration<MODE> [-d<TEST_ID>]# MODE can be 'dev', 'beta', 'release', same as build targets.# TEST_ID can be extracted from https://testcases.agrd.dev/data.json

Run the following command to build the dev version:

pnpm dev

This will create a build directory with unpacked extensions for all browsers:

build/dev/chromebuild/dev/edgebuild/dev/firefox-amobuild/dev/firefox-standalonebuild/dev/opera

To make a dev build for a specific browser, run:

pnpm dev<browser>

Where<browser> is one of the following:chrome,chrome-mv3,edge,opera,firefox-amo,firefox-standalone, like this:

pnpm dev chrome

To run dev build in watch mode, run:

pnpm dev --watch

Or for a specific browser:

pnpm dev<browser> --watch

Since version v4.0, AdGuard browser extension uses an open source librarytsurlfilter that implementsthe filtering engine.

While developing the browser extension it may be required to test the changestotsurlfilter. Here's what you need to do to link your local dev buildto the local dev build oftsurlfilter.

1. Clone and buildtsurlfilter libraries.

2. You have two options to link the packages:

   • Option 1: Link the packages globally:

     1. Go to thetsurlfilter/packages/tsurlfilter ortsurlfilter/packages/tswebextension directory.

     2. Run the following command:

        pnpm link --global

        This command will create a symlink to the package in the globalnode_modules directory.

     3. Once you have the packages linked globally, you can link them to the browser extension.Just run the following command in the root directory of the browser extension:

        pnpm link @adguard/tsurlfilter

   • Option 2: Link the packages by path:

     1. Just run the following command in the root directory of the browser extension:

        pnpm link<path-to-tsurlfilter/packages/tsurlfilter>

3. If you want to unlink the packages, just runpnpm unlink @adguard/tsurlfilterorpnpm unlink @adguard/tswebextension in the root directory of the browser extensionregardless of the linking option you chose.

   [!WARNING]pnpm will modify the lock file when linking packages. Seepnpm/pnpm#4219.

   [!NOTE]If you want to list linked packages, runpnpm list --depth 0 in the root directory of the browser extensionwhich will show you all dependencies. Linked packages have a version likelink:../path/to/package.

4. Build the browser extension in the watch mode:

   pnpm dev<browser> --watch --no-cache

   --no-cache flag is required to rebuild the extension on changes in the linked packages.

Before building the release version, you should manually download the necessaryresources that will be included into the build: filters and public suffix list.

pnpm resources

This command also checks if there are dangerous rules in the filters.Seedangerous rules

pnpm betapnpm release

You will need to put certificate.pem file to the./private/AdguardBrowserExtension directory. Thisbuild will create unpacked extensions and then pack them (crx for Chrome).

For testing purposes fordev command credentials taken from./tests/certificate-test.pem file.

WARNING: DO NOT USE TEST CREDENTIALS FOR PRODUCTION BUILDS, BECAUSE THEY ARE AVAILABLE IN PUBLIC.

You can useCrx CLIkeygento generate credentials forcrx builds, see the example below:

# Command will generate `key.pem` credential in the `./private/AdguardBrowserExtension` directorypnpm crx keygen ./private/AdguardBrowserExtension

1. To ensure that the extension is built in the same way, use the docker image:

   docker run --rm -it \    -v$(pwd):/workspace \    -w /workspace \    adguard/extension-builder:22.14--0.2--0

2. Inside the docker container, install the dependencies:

   pnpm install

3. To build theBETA version, run:

   pnpm beta firefox-standalone

4. Navigate to the build directory:

   cd ./build/beta

5. Compare the generatedfirefox-standalone.zip file with the uploaded one.

If you need to build theRELEASE version:

1. Run:

   pnpm release firefox

2. Navigate to the build directory:

   cd ./build/release

3. Compare the generatedfirefox.zip file with the uploaded one.

If you want to analyze the bundle size, run build with theANALYZE environment:

pnpm cross-env ANALYZE=true pnpm<build command>

So, for example, if you want to analyze the beta build for Chrome, run:

pnpm cross-env ANALYZE=true pnpm beta chrome

Or if you want to analyze all beta builds, run:

pnpm cross-env ANALYZE=true pnpm beta

Analyzer will generate reports to the./build/analyze-reports directory in the following format:

build/analyze-reports├──<browser-name>-<build-type>.html

If you want to debug MV3 declarative rules and check exactly which rules have been applied to requests, you can build and install the extension as described in the sections below. This will allow you to view the applied declarative rules in the filtering log.

Additionally, you can edit filters and rebuild DNR rulesets without rebuilding the entire extension, which may be useful for debugging purposes.

1. Ensure that you have installed all dependencies as described in theRequirements section.

   pnpm install

2. Run the following command in the terminal:

   pnpm dev chrome-mv3

3. The built extension will be located in the following directory:

   ./build/dev/chrome-mv3

1. Turn on developer mode:

   

2. ClickLoad unpacked:

   

3. Select the extension directory and clickSelect:

   

You can debug and update DNR rulesets without rebuilding the entire extension. There are two main workflows:

A. Automatic (recommended for most cases):

1. Build the extension (if not done yet):

   pnpm installpnpm dev chrome-mv3

2. Start watching for filter changes:

   pnpm debug-filters:watch

   • This will extract text filters to./build/dev/chrome-mv3/filters and watch for changes.
   • When you edit and save any filter file, DNR rulesets will be rebuilt automatically.

3. Reload the extension in your browser to apply new rulesets.

B. Manual (for advanced/manual control):

1. Build the extension (if not done yet):

   pnpm installpnpm dev chrome-mv3

2. Extract text filters:

   pnpm debug-filters:extract

3. Edit the text filters in./build/dev/chrome-mv3/filters as needed.

4. Convert filters to DNR rulesets:

   pnpm debug-filters:convert

5. Reload the extension in your browser to apply new rulesets.

Tip:

• To download the latest available text filters, run:

  pnpm debug-filters:load

If you see an exclamation mark in the filtering log, it means the assumed rule (calculated by the engine) and the applied rule (converted to DNR) are different. Otherwise, only the applied rule (in DNR and text ways) will be shown.

• Watch for changes and auto-convert:

  pnpm debug-filters:watch# Under the hood:pnpmexec dnr-rulesets watch \# Enable extended logging about rulesets, since it is optional - it can be removed    --debug \# Path to the extension manifest    ./build/dev/chrome-mv3/manifest.json \# Path to web-accessible-resources directory (needed for $redirect rules)# relative to the root directory of the extension (because they will be# loaded during runtime).    /web-accessible-resources/redirects

• Load latest text filters and metadata:

  pnpm debug-filters:load# Under the hood:pnpmexec dnr-rulesets load# This will load latest text filters with their metadata    --latest-filters# Destination path for text filters    ./build/dev/chrome-mv3/filters

• Manual conversion:

  pnpm debug-filters:convert# Under the hood:pnpmexec tsurlfilter convert \# Enable extended logging about rulesets    --debug \# Path to the directory with text filters    ./build/dev/chrome-mv3/filters \# Path to web-accessible-resources directory (needed for $redirect rules)# relative to the root directory of the extension (because they will be# loaded during runtime).    /web-accessible-resources/redirects \# Destination path for converted DNR rulesets    ./build/dev/chrome-mv3/filters/declarative

• Extract text filters from DNR rulesets:

  pnpm debug-filters:extract# Under the hood:pnpmexec tsurlfilter extract-filters \# Path to the directory with DNR rulesets    ./build/dev/chrome-mv3/filters/declarative \# Path to save extracted text filters    ./build/dev/chrome-mv3/filters

For all command options, use--help, e.g.:

pnpmexec dnr-rulesets watch --helppnpmexec tsurlfilter convert --help

Despite our code may not currently comply with new style configuration,please, setupeslint in your editor to follow up with it.eslintrc

To download and append localizations run:

pnpm locales download

To upload new phrases to crowdin you need the file with phrases./Extension/_locales/en/messages.json. Then run:

pnpm locales upload

To remove old messages from locale messages run:

pnpm locales renew

To validate translations run:

pnpm locales validate

To show locales info run:

pnpm locales info

The browser extension project includes a comprehensive bundle size monitoring system, located intools/bundle-size. This system helps ensure that our extension bundles remain within defined size limits, and that any significant increases are reviewed and justified.

• Tracks and compares bundle sizes across different build types (beta,release, etc.) and browser targets (chrome,chrome-mv3,edge, etc.)
• Detects significant size increases using configurable thresholds (default: 10%)
• Ensures Chrome MV3 bundle stays under the 30MB limit
• Checks for duplicate package versions usingpnpm
• Stores historical size data in.bundle-sizes.json
• Designed for CI/CD integration (Bamboo)
• For Firefox targets (AMO and Standalone) only, every individual.js file is checked to ensure it does not exceed the 4MB limit imposed by the Firefox Add-ons Store. If any.js file is larger than 4MB, the check fails and the offending files are reported.

• On each beta or release build, the system compares the current bundle sizes to the reference values in.bundle-sizes.json.
• If any size exceeds the configured threshold, or additionally check for 30MB limit for Chrome MV3 target or 4MB limit for Firefox targets - the check fails.
• Duplicate package versions are detected and reported.

We have defined size limits in the project.

1. When we build thebeta orrelease version, the build process checks if we’re exceeding those limits.
2. If we exceed the limits, the developer should investigate the cause and decide whether the size increase is acceptable.
3. If the new sizes are justified, the developer updates the size values in the package and creates a commit.
4. We then review and approve any changes to the sizes as part of the PR process.

1. Run the build for the desired environment (e.g.,pnpm beta orpnpm release).

2. If the build fails due to bundle size limits, investigate the cause (e.g., new dependencies, large assets).

3. If the increase is justified, update the reference sizes by running:

   pnpm update-bundle-size<buildEnv> [targetBrowser]# Example: pnpm update-bundle-size release chrome-mv3# Or: pnpm update-bundle-size beta firefox-amo# Or: pnpm update-bundle-size dev

4. Commit the updated.bundle-sizes.json file and include justification in your PR.

5. The changes will be reviewed and approved as part of the PR process.

To check bundle sizes locally, use:

pnpm check-bundle-size<buildEnv> [targetBrowser]# Example: pnpm check-bundle-size release chrome-mv3# Or: pnpm check-bundle-size beta firefox-amo# Or: pnpm check-bundle-size dev

For CLI help on parameters, use:

pnpm check-bundle-size --helppnpm update-bundle-size --help

You can override the default threshold for significant bundle size increases using the--threshold option:

pnpm check-bundle-size<buildEnv> [targetBrowser] --threshold 5# orpnpm check-bundle-size release chrome-mv3 --threshold=20# orpnpm check-bundle-size beta

• --threshold <number>: Sets the allowed percentage increase in bundle size before the check fails. Default: 10%.

This is useful for temporarily relaxing or tightening the allowed size delta for a specific check/build.

• tabs - this permission is required in order to get the URL of the options page tab
• webRequest - this permission is necessary to apply complicated rules (cosmetic for instance), detecting and removing tracking cookies, counting blocked resources.
• cookies - this permissions is required to delete cookies from requests or changing their lifetime.
• contextMenus - this permission is required in order to create a context menu
• scripting - this permission is required in order to inject assistant script only in the required pages
• storage - this permission is required in order to save user settings, user rules and custom filters
• declarativeNetRequest - this permission is required in order to block, redirect and modify URL requests
• declarativeNetRequestFeedback - this permission is required in order to create a log of the blocked, redirected or modified URL requests
• unlimitedStorage - this permission is required in order to save large filters
• webNavigation - this permission is required in order to catch the moment for injecting scriptlets
• userScripts - this permission is required to let the user subscribe to custom filter lists and evaluate rules from these lists

Due to the transition from MV2 to MV3, we cannot update our filters remotely. To keep the filters as fresh as possible, we have configured automated tasks in our CI plans. These tasks will build a new version of the extension with only the updated@adguard/dnr-rulesets package, which contains new static rulesets.

These automated tasks will run all necessary checks: unit tests, translation checks, and linter. After that, they will update resources, including filters and local script rules, create a build, and run integration tests to ensure the update is safe.

Finally, the new version of the extension will be published to the Chrome Web Store.