electron-web-blocker v1.0.5

Electron Web Blocker

Detects whether a URL should be blocked, such as advertisements, malware, or any other defined file of web addresses (e.g. from a hosts file). The default internal web address list file is obtained from StevenBlack's hosts file.

• Can be used generically by calling isBlacklisted("example.com"),
• Can take an Electron BrowserWindow or BrowserView as parameter of filter()

Getting Started

$ npm install electron-web-blocker

File format of web addresses

This module expects the following format:

example.com
subdomain.example.com
*.example.com

Hosts files which start with a local address (e.g. 0.0.0.0, 127.0.0.1) can also be used. The local addresses will not have a functional purpose, and are removed at initialization, along with the prefixes and suffixes ||, ^, ::, #, address=/, www., and whitespace and duplicate addresses.

init() (promise) (optional)

• path (string): a local or remote HTTP/HTTPS path to the web addresses/hosts file that overrides the internal hosts file; leave as an empty string ("") to disable the internal hosts file
• updateAfterSeconds (integer): update the web addresses file after a period of time in seconds
• updateNow (boolean): whether to update immediately on initialization
• blacklist (string, array): a custom blacklist in addition to the web addresses/hosts file, such as defined by user input
• whitelist (string, array): a custom whitelist that overrides the web addresses/hosts file and custom blacklist

list (whitelist, blacklist) (optional)

• .add() (string, array): add to the current list
• .remove() (string, array): remove from the current list
• .reset(): reset the list
• .get(): get the current list array

isBlacklisted(str):

• returns whether or not a url as str is blacklisted or not

filter() (optional)

• logger (function): a way to log blocked requests (e.g. console.log)
• onRequest (function): gets called like the original onRequest of a BrowserWindow or BrowserView instance.

Example

const webBlocker = require('electron-web-blocker');
const { BrowserWindow } = require('electron');

webBlocker.init({
	path: "hosts-url.ext/hosts",
	updateAfterSeconds: 3600,
	updateNow: true,
	blacklist: ["example.com"],
	whitelist: ["example.com"]
});

const mainWindow = new BrowserWindow({ width: 800, height: 600 });

// generic use
console.log(webBlocker.isBlacklisted("example.com")); // returns `true` or `false`

// electron use
webBlocker.filter(mainWindow, {
	logger: console.log,
	onRequest: (details, callback, shouldBeBlocked) => {
		// Execute your own onRequest function here...
	}
});

Research, design, programming, and testing takes time.

Please consider donating. Thank you.