README

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

You can use Userscripter to bootstrap 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 your browser/extension:

Check that the userscript works

Go to http://example.com. If you haven't modified anything, you should see a green background. You should also see the message [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. These repositories demonstrate how Userscripter is intended to be used:

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.
};

(Customizations in webpack.config.ts will take precedence over environment variables, because the latter only affect the return value of createWebpackConfig.)

Native browser extension

You can easily create a native browser extension from your userscript by including an object representation of manifest.json in the object passed to createWebpackConfig (example). If you do, manifest.json will 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

Usage no npm install needed!