{"id":13494998,"url":"https://github.com/AdguardTeam/AdguardBrowserExtension","last_synced_at":"2025-03-28T15:32:44.948Z","repository":{"id":28496023,"uuid":"32012345","full_name":"AdguardTeam/AdguardBrowserExtension","owner":"AdguardTeam","description":"AdGuard browser extension","archived":false,"fork":false,"pushed_at":"2024-10-29T10:20:38.000Z","size":496093,"stargazers_count":3087,"open_issues_count":377,"forks_count":329,"subscribers_count":145,"default_branch":"master","last_synced_at":"2024-10-29T11:49:59.322Z","etag":null,"topics":["adblock","adguard","chrome","firefox","javascript","open-source","privacy"],"latest_commit_sha":null,"homepage":"https://adguard.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AdguardTeam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-11T10:42:52.000Z","updated_at":"2024-10-28T17:29:01.000Z","dependencies_parsed_at":"2023-10-02T12:22:16.197Z","dependency_job_id":"21ad8edf-510e-4cc1-b9c0-4f0c9609fadd","html_url":"https://github.com/AdguardTeam/AdguardBrowserExtension","commit_stats":null,"previous_names":[],"tags_count":277,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FAdguardBrowserExtension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FAdguardBrowserExtension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FAdguardBrowserExtension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FAdguardBrowserExtension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdguardTeam","download_url":"https://codeload.github.com/AdguardTeam/AdguardBrowserExtension/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222058984,"owners_count":16924136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adblock","adguard","chrome","firefox","javascript","open-source","privacy"],"created_at":"2024-07-31T19:01:30.208Z","updated_at":"2025-03-28T15:32:44.942Z","avatar_url":"https://github.com/AdguardTeam.png","language":"TypeScript","readme":"\u0026nbsp;\n\u003cp align=\"center\"\u003e\n    \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.adguard.com/public/Adguard/Common/Logos/ext_dark.svg\" width=\"300px\" alt=\"AdGuard Browser Extension\" /\u003e\n        \u003cimg src=\"https://cdn.adguard.com/public/Adguard/Common/Logos/ext.svg\" width=\"300px\" alt=\"AdGuard Browser Extension\"/\u003e\n    \u003c/picture\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003eAd blocker with advanced privacy protection features\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n    AdGuard is a fast and lightweight ad blocking browser extension\u003cbr/\u003ethat effectively blocks all types of ads and trackers.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://adguard.com/\"\u003eAdGuard.com\u003c/a\u003e |\n    \u003ca href=\"https://reddit.com/r/Adguard\"\u003eReddit\u003c/a\u003e |\n    \u003ca href=\"https://twitter.com/AdGuard\"\u003eTwitter\u003c/a\u003e |\n    \u003ca href=\"https://t.me/adguard_en\"\u003eTelegram\u003c/a\u003e\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003ca href=\"https://github.com/AdguardTeam/AdguardBrowserExtension/releases\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/release/AdguardTeam/AdguardBrowserExtension/all.svg\" alt=\"Latest release\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://addons.mozilla.org/en-US/firefox/addon/adguard-adblocker/\"\u003e\n        \u003cimg src=\"https://img.shields.io/amo/v/adguard-adblocker?labelColor=orange\" alt=\"Mozilla Add-on Version\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.adguard.com/public/Adguard/Common/adguard_extension_settings_dark.png\" width=\"900px\" alt=\"AdGuard Browser Extension\" /\u003e\n        \u003cimg src=\"https://cdn.adguard.com/public/Adguard/Common/adguard_extension_settings_white.png\" width=\"900px\" alt=\"AdGuard Browser Extension\"/\u003e\n    \u003c/picture\u003e\n\u003c/p\u003e\n\nAdGuard 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 about [the difference](https://adguard.com/compare.html) here.\n\n\u003e 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.\n\n- [Installation](#installation)\n    - [Chrome and Chromium-based browsers](#installation-chrome)\n    - [Firefox](#installation-firefox)\n    - [Opera](#installation-opera)\n    - [Microsoft Edge](#installation-edge)\n- [Contribution](#contribution)\n    - [Translating AdGuard](#contribution-translating)\n    - [Testing AdGuard](#contribution-testing)\n    - [Reporting issues](#contribution-reporting)\n    - [Other options](#contribution-other)\n- [Development](#dev)\n    - [Requirements](#dev-requirements)\n    - [How to build](#dev-build)\n        - [Tests and dev build](#dev-tests-and-build)\n        - [Linking with the developer build of tsurlfilter/tswebextension](#dev-link)\n        - [Building the beta and release versions](#dev-beta-and-release)\n        - [Special building instructions for Firefox reviewers](#dev-for-firefox-reviewers)\n        - [Analyzing bundle size](#dev-bundle-size)\n        - [Debug MV3 declarative rules](#dev-debug-mv3)\n    - [Linter](#dev-linter)\n    - [Update localizations](#dev-localizations)\n- [Permissions required](#permissions-required)\n- [Auto-publish builds](#auto-publish-builds)\n- [Minimum supported browser versions](#browser-compatibility)\n\n## \u003ca name=\"installation\"\u003e\u003c/a\u003e Installation\n\n### \u003ca name=\"installation-chrome\"\u003e\u003c/a\u003e Chrome and Chromium-based browsers\n\nYou can get the latest available AdGuard Extension version from the\n[Chrome Web Store](https://agrd.io/extension_chrome).\n\n### \u003ca name=\"installation-firefox\"\u003e\u003c/a\u003e Firefox\n\nYou can get the latest version of AdGuard Extension from the\n[Mozilla Add-ons website](https://agrd.io/extension_firefox).\n\n### \u003ca name=\"installation-opera\"\u003e\u003c/a\u003e Opera\n\nOpera is basically a Chromium browser, but it maintains its own add-ons store.\nYou can get AdGuard Extension [from there](https://agrd.io/extension_opera).\n\n### \u003ca name=\"installation-edge\"\u003e\u003c/a\u003e Microsoft Edge\n\nThe latest stable version of AdGuard browser extension is available in\n[Microsoft Store](https://agrd.io/extension_edge).\n\n## \u003ca name=\"contribution\"\u003e\u003c/a\u003e Contribution\n\nWe are blessed to have a community that does not only love AdGuard, but also\ngives back. A lot of people volunteer in various ways to make other users'\nexperience with AdGuard better, and you can join them!\n\nWe, on our part, can only be happy to reward the most active members of the\ncommunity. So, what can you do?\n\n### \u003ca name=\"contribution-translating\"\u003e\u003c/a\u003e Translating AdGuard\n\nIf you want to help with AdGuard translations, please learn more about\ntranslating our products here: \u003chttps://adguard.com/kb/miscellaneous/contribute/translate/program/\u003e\n\n### \u003ca name=\"contribution-testing\"\u003e\u003c/a\u003e Testing AdGuard\n\nYou can get a beta version of AdGuard Browser Extension for any browser.\nAll necessary information on this topic can be found on a\n[dedicated page on our website](https://adguard.com/beta.html).\n\n### \u003ca name=\"contribution-reporting\"\u003e\u003c/a\u003e Reporting issues\n\nGitHub can be used to report a bug or to submit a feature request. To do so, go\nto [this page](https://github.com/AdguardTeam/AdguardBrowserExtension/issues)\nand click the *New issue* button.\n\n\u003e [!NOTE]\n\u003e For the filter-related issues (missed ads, false positives etc.) use\n\u003e the [dedicated repository](https://github.com/AdguardTeam/AdguardFilters).\n\n### \u003ca name=\"contribution-other\"\u003e\u003c/a\u003e Other options\n\nHere is a [dedicated page](https://adguard.com/contribute.html) for those who\nare willing to contribute.\n\n## \u003ca name=\"dev\"\u003e\u003c/a\u003e Development\n\n### \u003ca name=\"dev-requirements\"\u003e\u003c/a\u003e Requirements\n\n- [node.js LTS](https://nodejs.org/en/download/)\n- [pnpm v8](https://pnpm.io/installation)\n\n### \u003ca name=\"dev-build\"\u003e\u003c/a\u003e How to build\n\n#### \u003ca name=\"dev-tests-and-build\"\u003e\u003c/a\u003e Tests and dev build\n\nInstall local dependencies by running:\n\n```shell\npnpm install\n```\n\nRunning unit tests:\n\n```shell\npnpm test\n```\n\nRunning integration tests:\n\n```shell\npnpm test:integration \u003cMODE\u003e\n# MODE can be 'dev', 'beta', 'release', same as build targets.\n```\n\nRunning integration tests with enabling debug mode (page will be stopped after\ntests execution) for one of them:\n\n```shell\npnpm test:integration \u003cMODE\u003e [-d \u003cTEST_ID\u003e]\n# MODE can be 'dev', 'beta', 'release', same as build targets.\n# TEST_ID can be extracted from https://testcases.agrd.dev/data.json\n```\n\nRun the following command to build the dev version:\n\n```shell\npnpm dev\n```\n\nThis will create a build directory with unpacked extensions for all browsers:\n\n```shell\nbuild/dev/chrome\nbuild/dev/edge\nbuild/dev/firefox-amo\nbuild/dev/firefox-standalone\nbuild/dev/opera\n```\n\nTo make a dev build for a specific browser, run:\n\n```shell\npnpm dev \u003cbrowser\u003e\n```\n\nWhere `\u003cbrowser\u003e` is one of the following: `chrome`, `chrome-mv3`, `edge`, `opera`, `firefox`,\n`firefox-standalone`, like this:\n\n```shell\npnpm dev chrome\n```\n\nTo run dev build in watch mode, run:\n\n```shell\npnpm dev --watch\n```\n\nOr for a specific browser:\n\n```shell\npnpm dev \u003cbrowser\u003e --watch\n```\n\n#### \u003ca name=\"dev-link\"\u003e\u003c/a\u003e Linking with the developer build of tsurlfilter/tswebextension\n\nSince version v4.0, AdGuard browser extension uses an open source library\n[tsurlfilter] that implements\nthe filtering engine.\n\nWhile developing the browser extension it may be required to test the changes\nto `tsurlfilter`. Here's what you need to do to link your local dev build\nto the local dev build of `tsurlfilter`.\n\n1. Clone and build [tsurlfilter] libraries.\n\n1. You have two options to link the packages:\n\n    - **Option 1**: Link the packages globally:\n\n        1. Go to the `tsurlfilter/packages/tsurlfilter` or `tsurlfilter/packages/tswebextension` directory.\n\n        1. Run the following command:\n\n            ```shell\n            pnpm link --global\n            ```\n\n            This command will create a symlink to the package in the global `node_modules` directory.\n\n        1. Once you have the packages linked globally, you can link them to the browser extension.\n        Just run the following command in the root directory of the browser extension:\n\n            ```shell\n            pnpm link @adguard/tsurlfilter\n            ```\n\n    - **Option 2**: Link the packages by path:\n\n        1. Just run the following command in the root directory of the browser extension:\n\n            ```shell\n            pnpm link \u003cpath-to-tsurlfilter/packages/tsurlfilter\u003e\n            ```\n\n1. If you want to unlink the packages, just run `pnpm unlink @adguard/tsurlfilter`\nor `pnpm unlink @adguard/tswebextension` in the root directory of the browser extension\nregardless of the linking option you chose.\n\n    \u003e [!WARNING]\n    \u003e pnpm will modify the lock file when linking packages. See \u003chttps://github.com/pnpm/pnpm/issues/4219\u003e.\n\n    \u003e [!NOTE]\n    \u003e If you want to list linked packages, run `pnpm list --depth 0` in the root directory of the browser extension\n    \u003e which will show you all dependencies. Linked packages have a version like `link:../path/to/package`.\n\n1. Build the browser extension in the watch mode:\n\n    ```shell\n    pnpm dev \u003cbrowser\u003e --watch --no-cache\n    ```\n\n    `--no-cache` flag is required to rebuild the extension on changes in the linked packages.\n\n[tsurlfilter]: https://github.com/AdguardTeam/tsurlfilter\n\n#### \u003ca name=\"dev-beta-and-release\"\u003e\u003c/a\u003e Building the beta and release versions\n\nBefore building the release version, you should manually download the necessary\nresources that will be included into the build: filters and public suffix list.\n\n```shell\npnpm resources\n```\n\n\u003e [!TIP]\n\u003e Run `pnpm resources:mv3` to download resources for MV3 version.\n\nThis command also checks if there are dangerous rules in the filters.\nSee [dangerous rules](tools/resources/dangerous-rules/README.md)\n\n```shell\npnpm beta\npnpm release\n```\n\nYou will need to put certificate.pem file to the `./private` directory. This\nbuild will create unpacked extensions and then pack them (crx for Chrome).\n\n#### \u003ca name=\"dev-for-firefox-reviewers\"\u003e\u003c/a\u003e Special building instructions for Firefox reviewers\n\n1. Ensure you have installed Node.js and pnpm.\n\n1. To build the **BETA** version, run:\n\n    ```shell\n    pnpm beta firefox-standalone\n    ```\n\n1. Navigate to the build directory:\n\n    ```shell\n    cd ./build/beta\n    ```\n\n1. Compare the generated `firefox.zip` file with the uploaded one.\n\n#### \u003ca name=\"dev-bundle-size\"\u003e\u003c/a\u003e Analyzing bundle size\n\nIf you want to analyze the bundle size, run build with the `ANALYZE` environment:\n\n```shell\npnpm cross-env ANALYZE=true pnpm \u003cbuild command\u003e\n```\n\nSo, for example, if you want to analyze the beta build for Chrome, run:\n\n```shell\npnpm cross-env ANALYZE=true pnpm beta chrome\n```\n\nOr if you want to analyze all beta builds, run:\n\n```shell\npnpm cross-env ANALYZE=true pnpm beta\n```\n\nAnalyzer will generate reports to the `./build/analyze-reports` directory in the following format:\n\n```shell\nbuild/analyze-reports\n├── \u003cbrowser-name\u003e-\u003cbuild-type\u003e.html\n```\n\n#### \u003ca name=\"dev-debug-mv3\"\u003e\u003c/a\u003e Debug MV3 declarative rules\n\nIf you want to debug MV3 declarative rules and check exactly which rules has been applied for some requests, you can build extension in dev mode as described in the upper [How to build](#dev-build) section, but for specified branch, in which we develop MV3 version.\n\nThen install extension via developer mode, make requests and see applied declarative rules in the filtering log.\n\n##### How to build MV3 extension\n\n1. Switch to the `v5.0` branch:\n\n    ```shell\n    git checkout v5.0\n    ```\n\n1. Run the following command in the terminal:\n\n    ```shell\n    pnpm dev chrome-mv3\n    ```\n\n1. The built extension will be located in the directory:\n\n    ```shell\n    ./build/dev/chrome-mv3\n    ```\n\n##### How to install unpacked in the browser\n\n1. Turn on developer mode:\n\n    ![Developer mode](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/developer_mode.png)\n\n1. Click *Load unpacked*:\n\n    ![Load unpacked](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/load_unpacked.png)\n\n1. Select the extension directory and click `Select`:\n\n    ![Select](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/select.png)\n\nThat’s it!\n\n##### How to debug rules\n\n1. Find and modify the rule you need in the `./Extension/filters/chromium-mv3` directory in the `.txt` files.\n\n1. Convert the rules from txt to declarative form:\n\n    ```shell\n    pnpm convert-declarative\n    ```\n\n1. Build the extension again:\n\n    ```shell\n    pnpm dev chrome-mv3\n    ```\n\n1. Reload the extension in the browser:\n\n    ![Reload extension](https://cdn.adtidy.org/content/Kb/ad_blocker/browser_extension/reload_extension.png)\n\n1. If you see an ❗ mark - it means that assumed rule (which we calculated with our tsurlfilter engine, which performed applying rules in MV2) and actually applied rule (from which we converted to DNR rule) are not the same. And this can be a problem of conversion. \u003cbr/\u003e Otherwise, if assumed and applied rules are the same - only applied rule (in text and declarative ways) will be shown.\n\n### \u003ca name=\"dev-linter\"\u003e\u003c/a\u003e Linter\n\nDespite our code may not currently comply with new style configuration,\nplease, setup `eslint` in your editor to follow up with it `.eslintrc`\n\n### \u003ca name=\"dev-localizations\"\u003e\u003c/a\u003e Update localizations\n\nTo download and append localizations run:\n\n```shell\npnpm locales download\n```\n\nTo upload new phrases to crowdin you need the file with phrases\n`./Extension/_locales/en/messages.json`. Then run:\n\n```shell\npnpm locales upload\n```\n\nTo remove old messages from locale messages run:\n\n```shell\npnpm locales renew\n```\n\nTo validate translations run:\n\n```shell\npnpm locales validate\n```\n\nTo show locales info run:\n\n```shell\npnpm locales info\n```\n\n## \u003ca name=\"permissions-required\"\u003e\u003c/a\u003e Permissions required\n\n- `tabs`                          - this permission is required in order to get the URL of the options page tab\n- `webRequest`                    - this permission is necessary to apply complicated rules (cosmetic for instance), detecting and removing tracking cookies, counting blocked resources.\n- `cookies`                       - this permissions is required to delete cookies from requests or changing their lifetime.\n- `contextMenus`                  - this permission is required in order to create a context menu\n- `scripting`                     - this permission is required in order to inject assistant script only in the required pages\n- `storage`                       - this permission is required in order to save user settings, user rules and custom filters\n- `declarativeNetRequest`         - this permission is required in order to block, redirect and modify URL requests\n- `declarativeNetRequestFeedback` - this permission is required in order to create a log of the blocked, redirected or modified URL requests\n- `unlimitedStorage`              - this permission is required in order to save large filters\n- `webNavigation`                 - this permission is required in order to catch the moment for injecting scriptlets\n\n## \u003ca name=\"auto-publish-builds\"\u003e\u003c/a\u003e Auto-publish builds\n\nDue 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.\n\nThese 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.\n\nFinally, the new version of the extension will be published to the Chrome Web Store.\n\n## \u003ca name=\"browser-compatibility\"\u003e\u003c/a\u003e Minimum supported browser versions\n\n\u003c!-- NOTE: see MIN_SUPPORTED_VERSION in ./constants.ts --\u003e\n\n| Browser                     | Version |\n|---------------------------- |---------|\n| Chromium-based browsers MV2 | ✅ 106  |\n| Chromium-based browsers MV3 | ✅ 121  |\n| Firefox                     | ✅ 78   |\n| Firefox Mobile              | ✅ 113  |\n| Opera                       | ✅ 67   |\n| Edge Chromium               | ✅ 80   |\n| Edge Legacy                 | ❌      |\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAdguardTeam%2FAdguardBrowserExtension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAdguardTeam%2FAdguardBrowserExtension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAdguardTeam%2FAdguardBrowserExtension/lists"}