userscripter

    1.5.0 • Public • Published

    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

    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:

    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

    Install

    npm i userscripter

    DownloadsWeekly Downloads

    10

    Version

    1.5.0

    License

    MIT

    Unpacked Size

    96.8 kB

    Total Files

    73

    Last publish

    Collaborators

    • avatar