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

$3

* 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.

$3

``bash
cd path/to/my-new-userscript
npx tiged@2.12.7 https://github.com/SimonAlling/userscripter/bootstrap#master
`

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:

`bash
npm ci
npm run build
`

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

$3

Userscripts are usually installed through a browser extension, for example Violentmonkey ([Firefox][violentmonkey-firefox], [Chrome][violentmonkey-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_

$3

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][example-userscript] is a basic userscript featuring [operations][example-userscript-operations], [stylesheets][example-userscript-stylesheets], [preferences][example-userscript-preferences] and a [preferences menu][example-userscript-preferences-menu].
* [Better SweClockers][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][example-userscript-webpack-config]).

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

`bash
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:

`typescript
import { createWebpackConfig } from 'userscripter/build-time';

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][webextension] from your userscript, include a [manifest][manifest-json] in the object passed to createWebpackConfig ([example][example-userscript-webpack-config]).
manifest.json will then be created alongside the compiled .user.js file.
You can then use [web-ext][web-ext] to build the native extension:

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

[violentmonkey-firefox]: https://addons.mozilla.org/en-US/firefox/addon/violentmonkey/
[violentmonkey-chrome]: https://chrome.google.com/webstore/detail/violentmonkey/jinjaccalgkegednnccohejagnlnfdag
[better-sweclockers]: https://github.com/SimonAlling/better-sweclockers
[example-userscript]: https://github.com/SimonAlling/example-userscript
[example-userscript-operations]: https://github.com/SimonAlling/example-userscript/blob/master/src/operations.ts
[example-userscript-stylesheets]: https://github.com/SimonAlling/example-userscript/blob/master/src/stylesheets.ts
[example-userscript-preferences]: https://github.com/SimonAlling/example-userscript/blob/master/src/preferences.ts
[example-userscript-preferences-menu]: https://github.com/SimonAlling/example-userscript/blob/master/src/preferences-menu.tsx
[example-userscript-webpack-config]: https://github.com/SimonAlling/example-userscript/blob/master/webpack.config.ts
[webextension]: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions
[manifest-json]: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json
[web-ext]: https://www.npmjs.com/package/web-ext