Brave's adblock-lists: the filter list staging ground behind the browser's blocking

What this repo actually holds

Brave's adblock-lists is not a filter list engine or a blocking library. It is a container for additional filter lists that Brave ships on top of the community-maintained EasyList, EasyPrivacy, and uBlock Origin lists. The README is explicit that Brave uses those upstream lists by default, and this repo collects lists beyond them. Over time it has grown to include privacy-related lists, not just adblock filter lists. The repository layout shows directories like brave-lists, with files such as brave-social.txt, which are raw text filter lists. If you are looking for the code that downloads or packages these lists, it is not here; that lives in brave-core-crx-packager. The repo is a source of truth for list content, not for distribution logic.

The pipeline from this repo to a browser tab

The README describes a multi-step pipeline. A list in this repo is fetched by the brave-core-crx-packager, which packages it into a CRX component. The Brave browser client then downloads and registers that component. For adblock filter lists, the CRX packager reads from a separate list catalog in the adblock-resources repository, not from this repo directly. That catalog lists every active filter list on Brave and points to raw file URLs like https://raw.githubusercontent.com/brave/adblock-lists/master/brave-lists/brave-social.txt. So the flow is: edit this repo, update the list catalog in adblock-resources, update the packager, then update brave-core to know about the new component. This is a deliberate separation of concerns, but it means a single list change can require commits in four repositories.

Two paths for adding a new list

The README distinguishes between non-adblock lists and adblock filter lists, and each has a different process. For a non-adblock list, the default recommendation is to create a new CRX component. That requires changes in the packager and in brave-core, with a guide at docs/ship_a_file_to_all_clients.md. There is an alternative: add the list to an existing component if that component already has brave-core support. The README explicitly says this is not usually recommended and that most new lists need their own dedicated component. For adblock filter lists, the process is different: you add a source entry to the existing component in the adblock-resources list catalog, using the raw file URL. This means the barrier to entry is lower for adblock lists that fit into an existing component, but higher for anything that needs a new component.

What testing exists, and what does not

The README only mentions testing for two specific files: debounce.json and clean-urls.json. If you modify those, you are directed to a wiki page in the brave-browser repository about testing new rules locally. There is no mention of automated tests, CI, or linting for the filter lists in this repo. For a project whose entire purpose is to feed blocking rules into a browser, the lack of a visible test harness is a real gap. You can verify the syntax of a filter list only by running it through the browser's adblock engine, which is not documented here. This is a limitation if you are contributing a new list and want confidence that it will not break existing blocking behavior.

The dependency on adblock-resources and the packager

This repo is not self-contained. The README points to adblock-resources for accompanying resources needed by filter lists, and to brave-core-crx-packager for the backend logic. If you add a new list here, you will need changes in the packager. The list catalog in adblock-resources is the authoritative registry of what ships, and it lives outside this repo. This means that a change to a list in this repo does not automatically reach users. The practical consequence is that contributors must understand the CRX packaging model and the component system in brave-core. The README tries to help by linking to a comprehensive guide, but the guide is in the brave-core docs, not here. For an external contributor, that is a steep onboarding curve.

Licence and maintenance cost

The repository is licensed under MPL-2.0. That is a weak copyleft licence that allows use in proprietary software as long as modifications to the MPL-licensed files are made available under the same licence. For a filter list, this is a reasonable choice because the lists themselves are data, not code, and MPL-2.0 is permissive enough for most integration scenarios. Maintenance cost is not documented in the repo. The repository has no published GitHub releases, so you cannot gauge how frequently lists are updated. The README does not mention a contribution workflow beyond the adding-new-list sections. The maintenance burden is likely concentrated in the packager and the catalog, not in the list files themselves, because every new list triggers changes in those external repos.

Alternatives and when to choose them

The obvious alternative is to rely directly on upstream filter lists like EasyList, EasyPrivacy, and uBlock Origin's uAssets. That is exactly what Brave does as a baseline. This repo exists only for the extra lists that Brave maintains on top. If you are building a browser or an adblock extension and you need additional lists beyond the community ones, you have two options: maintain your own repo like this one, or contribute your rules upstream to EasyList or uAssets. The difference is control versus reach. Contributing upstream means your rules benefit every user of those lists, but you lose the ability to ship Brave-specific rules that may not be appropriate for the general public. This repo is the choice for rules that are specific to Brave's product decisions, such as the brave-social.txt list. For general rules, upstream is the better path.

Editorial conclusion

Adopt this repo if you are a Brave engineer or a contributor who wants to add a new filter list to the browser and are prepared to touch the crx-packager and the list catalog. Do not adopt it if you expect a standalone, self-contained filter list project; this repo is only the source of raw lists, and shipping them requires coordination across at least three other repositories. Before you start, verify which component your list should join, read the ship_a_file_to_all_clients guide, and check the adblock-resources list catalog to see whether your list is already covered. The repo's value is in its role as the upstream source for Brave's default blocking, not as a general-purpose adblock list collection.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases