Home

Awesome

Userscript Proxy

Join the chat at https://gitter.im/eBay/userscript-proxy

Ever tried to run userscripts on your iOS device or your Android phone? For iOS, it's not possible, and for Android it's an exercise in frustration.

Userscript Proxy allows you to run userscripts on mobile devices. Userscripts are snippets of JavaScript and CSS code that are added to a particular web page, to change the way it looks or the way it behaves. Tampermonkey and Greasemonkey are browser extensions that allow you to install userscripts into web pages, but they only work properly in desktop browsers – they don't support iOS at all, and the version for Android is tied to an old browser that doesn't work very well anymore.

Instead of running userscripts directly in the browser, Userscript Proxy is an HTTP proxy server that transparently injects scripts and stylesheets (userscripts) into existing sites. We use this tool to quickly generate research stimuli for user testing: we write JavaScript scripts and CSS stylesheets that alter our existing sites according to new designs. This makes it much easier for our developers when we want to test out a simple change: we can run our changes on top of the existing site.

With Userscript Proxy, you can set up a collection of scripts, run multiple scripts at once, and specify which hosts and URLs to inject each script into. You can think of it as Tampermonkey or Greasemonkey running inside of a proxy server.

How it works

Userscript Proxy generates a proxy PAC file that specifies which web hosts have URLs that need to be altered, and directs all requests to those hosts to Userscript Proxy's proxy server. The proxy server then adds userscripts to the HTML file that is served from each URL that matches. Scripts and stylesheets are added inline to the proxied page, so they run with the same permissions as a script running directly on the website.

Userscript Proxy uses the http-mitm-proxy npm module for the core proxy functionality.

Installing

Userscript Proxy is a Node.js application. The proxy can be used as a command-line application or as a Node module. Install as a command-line application unless you want to include the proxy in software you're writing.

Installing as stand-alone command-line application

npm install -g userscript-proxy

Running with example files

To run Userscript Proxy, you need a configuration file (config.json) and userscripts, which are JavaScript and CSS files. You can get a feel for how it works with the example files on this page. Clone this repository to your computer or download the ZIP file from the GitHub page, open a Terminal window and navigate to the examples directory, then run:

userscript-proxy config.json

See "Using the proxy server" below to set it up on your devices.

Running on the command line

In general, run Userscript Proxy as follows:

userscript-proxy <config_file> [options]

--loadScript set   Start the proxy with the given set of userscripts active (defined in the config file)
--staticDir dir    Path to directory of static files to serve at /static
--proxyPort port   Port for HTTP proxy server (default 8888)
--pacPort port     Port to serve PAC and other static files (default 8080)
--limitHosts       Only proxy hosts in the currently-selected userscript set
                   (see "Notes" section for more details)
--addPac file      Path to existing PAC file to add proxy rules to
                   (see "Notes" section for more details)
--proxyIndex file  Path to proxy index HTML file
--auth             Enable proxy authentication (experimental; see "Notes" section)

Installing as an npm module

npm install --save userscript-proxy

Add the following code to your script:

var proxy = require('userscript-proxy');
proxy(config, id, options);

{
  'loadScript': 'userscriptSetId',   // Start the proxy with the given set of userscripts active (defined in config)
  'staticDir': './path/to/static',   // Path to directory of static files to serve at /static
  'proxyPort': 8888,                 // Port for HTTP proxy server (default 8888)
  'pacPort': 8080,                   // Port to serve PAC and other static files (default 8080)
  'limitHosts': false,               // Only proxy hosts in the currently-selected userscript set
                                     // (see "Notes" section for more details)
  'addPac': pacFileString,           // Add proxy rules to the beginning of an existing PAC file (as string)
                                     // (see "Notes" section for more details)
  'proxyIndex': indexFileString,     // Proxy index HTML file (as string)
  'auth': false                      // Enable proxy authentication (experimental; see "Notes" section)
}

Using the proxy server

Creating userscripts

Userscript Proxy doesn't have a graphical interface like Tampermonkey to install scripts, but don't get scared off – you just need to add the scripts to an easy configuration file.

See the examples directory for a sample config.json file and sample scripts. You can run the samples directly by opening a Terminal window in the examples directory and running userscript-proxy config.json

Userscripts are defined in a JavaScript object, defined below.

{
  "userscripts": [
    {
      "title": "Title of userscript",
      "id": "userscriptId",
      "match": [
        {"host": "example.com", "url": "/"},
        {"host": "example.com", "url": "/index.html"}
      ],
      "scripts": [
        "./scripts/userscript.js"
      ],
      "styles": [
        "./styles/userscript.css"
      ]
    },
    ...
  ],
  "userscriptSets": [
    {
      "title": "Title of userscript set",
      "id": "userscriptSetId",
      "password": "pass",
      "userscripts": ["userscriptId", ...]
    },
    ...
  ]
}

Adding proxy information to your userscripts

All instances of the following static keys will be replaced with their corresponding dynamic values in userscripts.

Usage Notes

Implementation Notes

Acknowledgements

License

Copyright (c) 2018 eBay Inc.

Use of this source code is governed by a MIT-style license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.