bsdmylove / darkreader

Dark Reader Chrome and Firefox extension

Dark Reader analyzes web pages and aims to reduce eyestrain while browsing the web.

Dark Reader

Dark Reader is an open-source MIT-licensed browser extension designed to analyze web pages. Dark Reader will generate a dark mode that aims to reduce the eyestrain of the user. Dark Reader is feature-rich and is customizable in many ways throughout the UI.

Questions

Most questions can be answered by reading the help page. If the help page doesn't answer your question, open up a new discussion.

How to contribute

Read more about contributing to Dark Reader in CONTRIBUTING.md.

Building for use

Dark Reader build script requires a JavaScript runtime, either NodeJS or Deno. We recommend using NodeJS, Deno support is experimental.

Building with NodeJS

You can install the extension from a file. Install Node.js (we recommend LTS or higher, but any version at or above 15 will work). Download the source code (or check out from git). Open the terminal in the root folder and run:

• npm install
• npm run build or npm run build [-- flags]

This will create a build/release/darkreader-chrome.zip file for use in a Chromium-based browser and a build/release/darkreader-firefox.xpi file for use in Firefox.

You can customize build process by passing flags to build script. To see all flags, run npm run build -- --help.

Building with Deno

You can build Dark Reader with alternative runtime called Deno. For this run deno:bootstrap script (e.g., via npm run deno:bootstrap or manually copy the command from package.json). Then run the same commands described above.

Please note that if you encounter error Too many open files (os error 24), then you should use the newer version of Deno (preferably built from source or canary).

Bundling with official Firefox store signatures (experimental)

Prior to publication, extension stores provide digital signatures for extensions. These digital signatures certify the integrity of the archive (that extension bundle did not get corrupted or bit-rotted) and that extension store performed very basic extension validation.

Dark Reader repository contains these digital signatures and you can add them to the extension bundle. The following will build Dark Reader for Firefox version 4.9.63:

npm run build -- --firefox --version=4.9.63

Please note that only Firefox Add-ons store signatures are present in the repositiry right now. Also, due to NodeJS and TypeScript version compatibility, one might have to first check out the old revision (commit), then build the extension files, then check out the recent commit and create the bundle (by running only signature and zip steps).

Using Dark Reader for a website

You can use Dark Reader to enable dark mode on your website!

• Install the package from NPM (npm install darkreader)
• or build from the source code (npm run api)
• or include the script via a CDN such as unpkg or jsDelivr

Then you can use the following code to control Dark Reader's API:

DarkReader.enable({
    brightness: 100,
    contrast: 90,
    sepia: 10
});

DarkReader.disable();

// Enable when the system color scheme is dark.
DarkReader.auto({
    brightness: 100,
    contrast: 90,
    sepia: 10
});

// Stop watching for the system color scheme.
DarkReader.auto(false);

// Get the generated CSS of Dark Reader returned as a string.
const CSS = await DarkReader.exportGeneratedCSS();

// Check if Dark Reader is enabled.
const isEnabled = DarkReader.isEnabled();

... or if you are using ES modules:

import {
    enable as enableDarkMode,
    disable as disableDarkMode,
    auto as followSystemColorScheme,
    exportGeneratedCSS as collectCSS,
    isEnabled as isDarkReaderEnabled
} from 'darkreader';

enableDarkMode({
    brightness: 100,
    contrast: 90,
    sepia: 10,
});

disableDarkMode();

followSystemColorScheme();

const CSS = await collectCSS();

const isEnabled = isDarkReaderEnabled();

Be aware that Dark Reader will add the chrome object onto the window object. These are to stub certain functions that the code will use. They originate from the webextension-api.

Site fixes

Automatically syncing the site fixes to every Dark Reader user was disabled because the GitHub team does not allow using GitHub as a CDN. The storage of these files would be expensive, and making requests to other resources would look suspicious. Each new release of Dark Reader will include these changes.

However, this can be enabled using the following steps:

• Click on the Dark Reader icon.
• Click on the Dev tools button (in the bottom-right corner).
• Click on the Preview new design button.
• Enable the Synchronize site fixes setting under Settings -> Manage settings.

To force a synchronization of the sites fixes (when the corresponding setting is enabled), perform the following steps:

• Click on the Dark Reader icon.
• Click on the Dev tools button (in the bottom-right corner).
• Click on the Reset button. This will remove any custom site fixes you may have.

Enable Dark Reader for restricted websites on Firefox

By default, Dark Reader does not work on some websites due to security restrictions enforced by Mozilla.

The following instructions will guide you on how to bypass those restrictions.

Proceed with caution. This exposes you to a security risk if you do not know what you are doing.

These settings will apply to all extensions, and not just Dark Reader.

Step 1: change Dark Reader's settings.

• Click on the Dark Reader icon.
• Click on the Dev tools button (in the bottom-right corner).
• Click on the Preview new design button.
• Enable the Enable on restricted pages setting under Settings -> Advanced.

Step 2: change Firefox's settings.

• Type about:config in the address bar and press Enter. A warning page may appear. Click Accept the Risk and Continue to proceed.
• Search for and set extensions.webextensions.restrictedDomains to an empty value.
• Create [e-mail] with boolean as type and set its value to true.
• Set privacy.resistFingerprinting.block_mozAddonManager to true.
• Restart Firefox.

Contributors

Thank you to all our contributors! Dark Reader exists thanks to you.

Backers

Thank you to all our generous backers! Support Dark Reader by becoming a backer.

Sponsors

Does your company use Dark Reader? Please ask your manager or the marketing team if your company would be interested in supporting our project. Your support will allow the maintainers to dedicate more time to maintenance and creating new features for everyone. Also, your company's logo will show on GitHub. Who doesn't want a little extra exposure? Here's the info.

Thank you to all our wonderful sponsors!