Hetzblocker in the Browser

This is the source code repository for the Hetzblocker browser extension, currently available for Firefox and Chrome. If you want to develop the extensions, this repository is the place to start.

If you would simply like to use and install the extension, the latest stable version can be found at one of the following links:

• Hetzblocker for Firefox
• Hetzblocker for Chrome

Hetzblocker Block-Lists

Hetzblocker uses two dedicated lists for blocking: a domain list, and a URL list.

Domain Block-List

Domain list entries are used for publishers and platforms whose business model or core behaviour is based on breaking The Rules.

The domain list can be found at src/js/common/domainlist.js. This list is used to block entire domains. This means that all pages within a domain are matched. Domain list entries are matched on the URL’s domain and top-level domain. This means that the entry 'exampledomain.de' will block 'www.exampledomain.de', 'media.exampledomain.de', and 'exampledomain.de'.

URL Block-List

Since it’s unpractical to block an entire blogging platform like Medium or WordPress if just one author is misbehaving, Hetzblocker also contains a URL block list. This second one is a list with full URLs to block. Blocking only works if the match is exact. This list can block YouTube channels, Twitter accounts, Medium authors, etc. Page list entries are matched on the URL’s sub-domain, domain, top-level domain, and path. The URL block list can be found at src/js/common/pagelist.js

Note: Query parameters are not taken into consideration. This means that the list entry 'http://site.tld/path' matches 'http://site.tld/path' and 'http://site.tld/path?foo=bar'. There are platforms that use query parameters for account or author differentiation, but those are few and far in between. If this case pops up, an implementation can be written.

Hetzblocker Development and Contributing

System Requirements

• Node.js, version 13 was tested, others might work.
• NPM, version 6 or higher. (NPM is usually included with Node.js)

Coding Standards

This is an extension that is planned for all platforms supporting the Webextension standard. The JavaScript has been written in ES6, and uses Gulp and Babel for building and transpilation.

Hetzblocker uses the JavaScript Standard Style for code formatting and code style. For other files, the project’s included Editor Config applies.

Testing

No untested code in production!^{1, 2, 3}

¹ In an ideal world, Hetzblocker would have full test coverage

² Also, in an ideal world Hetzblocker would not be needed.

³ The goal is high test coverage, but let’s keep it realistic and treat this on a case-by-case basis.

Project Setup

First, you need to install NPM modules using:

npm install

Build the extension

To create an unpacked extension for all browser templates, you can run:

npx gulp buildall

This will place the built, unpacked extensions into: build/extension/BROWSER/

You can then load these folders’ manifest.json files into your browser to test them.

Local Development of the extension

To run the build task, and watch for file changes, you can run:

npx gulp

This builds the entire extension, after which it starts file watchers for each sub-task.

Create a Distributable package

This task will create a versioned, zipped version of the browser extension, run:

npx gulp dist

The ZIP files will be placed in the folder dist/BROWSER/hetzblocker-VERSION.zip

Thanks

This extension is heavily inspired by autinerd’s hosts file, plus revengeday’s and rleh’s work on browser extensions.

Troubleshooting

VIPS compilation errors on Ubuntu during npm install

It can happen that on npm install an incorrect version of libvips is being installed. This dependency comes from the gulp-responsive package, and can cause libvips compilation errors.

The solution is to manually install libvips as follows: sudo apt install libvips42, and then running npm install again. This should fix the issue.

Sharp throws “Module did not self-register.” error

This has to do with a different version of Node being used for npm install as is used to execute gulp tasks.

Usually this is because there’s an old version of Node on you system, and your IDE is not set up to handle the correct on e for the project.

Make sure both installation and execution of the Node modules is done with the same Node version, and you should be fine.

For more info, check out: lovell/sharp#952