Create userscripts in a breeze!
npm install userscripterCreate 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
* 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.
``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.
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_
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.
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.
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.
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.web-ext
You can then use [][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