Template for making Userscripts in TypeScript with various utilities like directly importing and parsing HTML, Markdown and CSS and packing it with rollup
WTFPL License
Extensive Typescript ESNext template and boilerplate for userscripts. Supports importing and parsing HTML and Markdown files directly in code, packing it all up with rollup and applying custom injections for the userscript header and more. It also offers ESLint to lint and auto-fix the code and GitHub Actions with ESLint to lint the code in pull requests and CodeQL to check it for vulnerabilities on every push. Requires a Git repo to be used as the asset CDN and for the build versioning system of the userscript. Supports distribution on GitHub, GreasyFork and OpenUserJS out of the box.
Like this template? Please consider supporting the development ❤️
npm i
to install dependencies.env.template
to .env
and change the values inside if needed#REPLACE:
with your IDE in the entire project and replace all placeholders with your own valuesassets/icon.png
with your own or use Google's or DuckDuckGo's favicon API in the userscript header (see step 5)license
field of package.json
too!)src/tools/post-build.ts
to whatever you need (see also GM header reference).eslintrc.cjs
is what I use, feel free to remove rules if there are too many or modify them to your preferencesinit()
and run()
inside the entrypoint file at src/index.ts
(read the comments for more info)assets/
assets/require.json
@require
directive.pkgName
(required) - The npm name of the packagebaseUrl
- The base URL of the CDN to load from (defaults to https://cdn.jsdelivr.net/npm/
)path
- The path to the file inside the package (uses jsdelivr's standard path by default)link
- Set this to true
if you have linked this package locally using npm link
and want to explicitly have the latest code included in the bundle.assets/resources.json
@resource
directive.getResourceUrl()
function in src/utils.ts
to get the URL of the resource. The value is the path to the file inside the assets/
folder.package.json
file is located).src/
src/tools/
src/tools/post-build.ts
src/tools/serve.ts
src/index.ts
src/config.ts
src/constants.ts
tools/post-build.ts
src/declarations.d.ts
src/observers.ts
SelectorObserver
instances. These observe a designated part of the DOM for changes.addSelectorListener()
, you can then add a listener, given a specific CSS selector, that gets called when the selector has been found in the DOM.src/types.ts
src/utils.ts
npm i
Run once to install dependencies
npm run dev
This is the command you want to use to locally develop and test your script.
It watches for any changes, then rebuilds and serves the userscript on port 8710, so it can be updated live if set up correctly in the userscript manager (see development tips).
Once it has finished building, a link will be printed to the console. Open it to install the userscript.
You can also configure request logging and more in .env
and src/tools/serve.ts
, just make sure to restart the dev server after changing anything.
npm run build-prod
Builds the userscript for production for all host platforms (GitHub, GreasyFork and OpenUserJS) with their respective options already set.
Outputs the files using a suffix predefined in the package.json
file.
Use this to build the userscript for distribution on all hosts.
npm run build -- <arguments>
Builds the userscript with custom options
Arguments:
--config-mode=<value>
- The mode to build in. Can be either production
or development
(default)--config-branch=<value>
- The GitHub branch to target. Can be any branch name, but should be main
for production and develop
for development (default)--config-host=<value>
- The host to build for. Can be either github
(default), greasyfork
or openuserjs
--config-assetSource=<value>
- Where to get the resource files from. Can be either local
or github
(default)--config-suffix=<value>
- Suffix to add just before the .user.js
extension. Defaults to an empty stringShorthand commands:
npm run build-prod-base
- Sets --config-mode=production
and --config-branch=main
npm run build-develop
- Sets --config-mode=development
, --config-branch=develop
and --config-assetSource=github
npm run lint
Builds the userscript with the TypeScript compiler and lints it with ESLint. Doesn't verify all of the functionality of the script, only syntax and TypeScript errors!
npm run --silent invisible -- "<command>"
Runs the passed command as a detached child process without giving any console output.
Remove --silent
to see npm's info and error messages.
npm run node-ts -- <path>
Runs the TypeScript file at the given path using the regular node binary and the node-ts loader.
Also enables source map support and disables experimental warnings.
npm run watch
, you may open the URL shown in the console in your browser and select the Track local file
option in the installation dialog.require.json
, as long as they are hosted on a CDN and expose a global variable.@require
directive and will be exempt from minification rules on platforms like GreasyFork.dist/
folder should be committed and pushed to GitHub.@downloadURL
and @updateURL
directives make it so the script is automatically updated from that same file.package.json
before building, so that every user of your userscript may receive the update.dist/
is bound to userscriptName
in package.json
dbaeumer.vscode-eslint
) and bind a hotkey for the ESLint: Fix all auto-fixable problems
command so you can quickly format the currently active file according to the rules in .eslintrc.cjs
rollup.config.mjs
Made with ❤️ by Sv443 If you like this template, please consider supporting me
© 2024 Sv443 - WTFPL license