Userscripter

Create userscripts in a breeze!

• Safe, declarative DOM operations and stylesheets
• Straightforward preference management
• TypeScript constants in SASS code
• Build as native browser extension (optional)
• Metadata validation
• Static typing

Getting started

Prerequisites

• Node.js with npm is required.
• If you are using Windows, you may need to install and use Git Bash, Linux Subsystem or similar to be able to build.

Create a new userscript

npm install --global userscripter
cd path/to/my-new-userscript
userscripter init

If everything went well, an src directory should have been created, along with some other files like package.json and webpack.config.ts. You should now be able to build the userscript:

npm install
npm run build

The compiled userscript should be saved as dist/bootstrapped-userscript.user.js.

Install the userscript

Userscripts are usually installed through a browser extension, for example Violentmonkey (Firefox, Chrome). Please refer to the documentation for the one you use:

• Install a local script - Violentmonkey
• Greasemonkey Manual:Installing Scripts
• How to install new scripts to Tampermonkey

Check that the userscript works

Go to http://example.com. If you haven't modified anything, you should see a green background and [Bootstrapped Userscript] Bootstrapped Userscript 0.1.0 in the developer console.

How to write a userscript

A userscript typically consists primarily of DOM operations and stylesheets. It can also have user-facing preferences. Check out these repositories for examples:

• Example Userscript is a basic userscript featuring operations, stylesheets, preferences and a preferences menu.
• Better SweClockers is a large, full-fledged, real-world userscript.

Build options

The buildConfig property of the object passed to createWebpackConfig controls how the userscript is built (see e.g. webpack.config.ts in the example repo).

You can override certain options on the command line using environment variables:

USERSCRIPTER_MODE=production USERSCRIPTER_VERBOSE=true npm run build

(With USERSCRIPTER_VERBOSE=true, all available environment variables are listed.)

You can also customize the object returned from createWebpackConfig in webpack.config.ts:

import { createWebpackConfig } from 'userscripter/build';

const webpackConfig = createWebpackConfig({
    // …
});

export default {
    ...webpackConfig,
    resolve: {
        ...webpackConfig.resolve,
        alias: {
            ...webpackConfig.resolve?.alias,
            "react": "preact/compat", // Adding an alias here.
        },
    },
    // Other properties (e.g. 'stats') could be added/overridden here.
};

Such customizations will take precedence over environment variables.

Native browser extension

To create a native browser extension from your userscript, include a manifest in the object passed to createWebpackConfig (example). manifest.json will then be created alongside the compiled .user.js file. You can then use web-ext to build the native extension:

npm install -g web-ext
cd dist
web-ext build