Reddit Enhancement Suite
Reddit Enhancement Suite (RES) is a suite of modules that enhances your Reddit browsing experience.
For general documentation, visit the Reddit Enhancement Suite Wiki.
Hi there! Thanks for checking out RES on GitHub. A few important notes:
RES is licensed under GPLv3, which means you're technically free to do whatever you wish in terms of redistribution as long as you maintain GPLv3 licensing. However, I ask out of courtesy that should you choose to release your own, separate distribution of RES, you please name it something else entirely. Unfortunately, I have run into problems in the past with people redistributing under the same name, and causing me tech support headaches.
I ask that you please do not distribute your own binaries of RES (e.g. with bugfixes, etc). The version numbers in RES are important references for tech support so that we can replicate bugs that users report using the same version they are, and when you distribute your own - you run the risk of polluting/confusing that. In addition, if a user overwrites his/her extension with your distributed copy, it may not properly retain their RES settings/data depending on the developer ID used, etc.
I can't stop you from doing any of this. I'm just asking out of courtesy because I already spend a great deal of time providing tech support and chasing down bugs, and it's much harder when people think I'm the support guy for a separate branch of code.
Steve Sobel email@example.com
Thinking about contributing to RES? Awesome! We just ask that you follow a few simple guidelines:
RES has grown quite large, so we do have to pick and choose what features we should add. Code bloat is always a concern, and RES is already rather hefty. If you're unsure if your feature would appeal to a wide audience, please post about it on /r/Enhancement or contact @honestbleeps directly to ask.
There are a few features we have made a conscious choice not to add to RES, so make sure whatever you'd like to contribute isn't on that list.
It would be greatly appreciated if you could stick to a few style guidelines:
- please use tabs for indentation
- please use spaces in your
if (foo === bar), not
- please use single quotes
'and not double quotes
- please comment your code!
- please consider using
npm run lint(see below) to verify your code style
If you're adding new modules or hosts, see below.
Top level files and folders
README.md: YOU ARE HERE, unless you're browsing on GitHub
gulpfile.babel.js: build script
package.json: package info, dependencies
lib/: all RES code
lib/core/: core RES code
lib/modules/: RES modules
lib/vendor/: RES vendor libraries
chrome/: Chrome-specific RES files
firefox/: Firefox-specific RES files
safari/: Safari-specific RES files
dist/: build output
**/__tests__: unit tests
background.js: the "background page" for RES, necessary for Chrome extensions
manifest.json: the project manifest
index.js: this is Firefox's sort of "background page" for RES, like what Chrome has, but just a JS file
package.json: the project manifest for the Firefox add-on
background-safari.html: the "background page" for RES, necessary for Safari extensions
Info.plist: the project manifest
Building development versions of the extension
First time installation:
- Install node.js (version 4+).
- Install Python 2 (not version 3).
- Navigate to your RES folder.
Once done, you can build the extension by running
npm start. This will also start a watch task that will rebuild RES when you make changes (see Advanced Usage for more details).
To load the extension into your browser, see the sections below.
Details and advanced usage
lib/vendor/) will be compiled with Babel.
npm start [-- <browsers>] will clean
dist/, then build RES (dev mode), and start a watch task that will rebuild RES when you make changes. Only changed files will be rebuilt.
npm run once [-- <browsers>] will clean
dist/, then build RES (dev mode) a single time.
npm run build [-- <browsers>] will clean
dist/, then build RES (release mode). Each build output will be compressed to a .zip file in
<browsers> is a comma-separated list of browsers to target, e.g.
chrome,firefox,safari,node. By default, all will be targeted.
npm run add-module -- module.js will add
module.js, a new module, to the manifest for each browser.
npm run add-host -- hostname.js will add
hostname.js, a new media host, to the manifest for each browser.
Note: You will need to install Ruby and run
npm run external-deps before using
npm run lint.
npm test will run unit tests (in
Building in Chrome
- Go to
Menu->Tools->Extensionsand tick the
Load unpacked extensionand point it to the
dist/chromefolder. Make sure you only have one RES version running at a time.
- Any time you make changes to the script, you must go back to the
Building in Firefox
- Install jpm using
npm install -g jpm
- Navigate to
dist/firefoxand run the command
jpm run, which should launch a new Firefox browser using a temporary profile with only RES installed.
Building in Safari (assumes Mac)
- Open the
Preferencesby going to
⌘,, then go to
Advancedand check the checkbox for
Show Develop menu in menu bar.
- Navigate to
Develop->Show Extension Builderto open the extensions builder. Add a new extension by pressing the
+in the bottom left and choosing
- Navigate to the
dist/RES.safariextensionfolder for RES and select it.
If you are using Safari 9+, you should be able to install the extension without enrolling in the Apple Developer Program; however, the extension will be auto-uninstalled when you quit Safari.
If you use an older version of Safari or find the auto-uninstall annoying, you need to purchase a proper certificate by signing up for the Apple Developer Program (currently $99/yr).
Accessing nightly builds
In addition to building your own version of RES, you can download older (or current) builds of RES for testing purposes.
All that is asked is that you have at least one previous contribution to RES.
Adding new files
lib/modules/example.js for an example.
Create a new
.js file in
npm run add-module to add the file to the browsers' manifests.
Inline image viewer hosts
lib/modules/hosts/example.js for an example.
Create a new
.js file in
npm run add-host to add the file to the browsers' manifests.
Create a new Sass partial under
lib/css/ (with a leading underscore, e.g.
_myPartial.scss). Import the file in
@import 'modules/myPartial';—do not include the underscore or file extension). You do not need to add it to any browser manifests.
Body classes will be automatically added for boolean and enum options with the property
bodyClass: true, in the form
.res-moduleId-optionKey for boolean options (only when they're enabled), and
.res-moduleId-optionKey-optionValue for enums.
This is the preferred way to create optional CSS; do not use
addCSS() unless absolutely necessary (i.e. variable color, size, etc.).