Typescript ESM template for making userscripts that supports importing, parsing and minifying HTML, CSS, Markdown and misc. files directly in code, packing it all up with webpack 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.
Like this template? Please consider supporting the development ❤️
- Make sure Node.js and a userscript manager are installed (I recommend ViolentMonkey)
- Click here to create a repository on GitHub using this template
- Clone the repository you created
- Open a terminal in the root of the folder and use
npm ito install dependencies - Refer to first steps
- Copy
.env.templateto.envand change the values inside if needed - Inside
package.json, update the propertiesname,userscriptName,description,homepage,author,licenseandrepository.url - Replace the icon at
assets/icon.pngwith your own or use Google's or DuckDuckGo's favicon API in the userscript header - Replace the LICENSE.txt file with your own license or remove it if you want your code to be "all rights reserved"
- Modify the variables and userscript header inside
src/tools/post-build.tsto whatever you need (see also GM header reference) - The eslint configuration at
.eslintrc.cjsis what I use, feel free to remove rules if there are too many or modify them to your preferences - Add your own initialization functions to
init()andonLoad()inside the entrypoint file atsrc/index.ts(read the comments for more info) - Remove the example HTML, CSS and TS files
- Refer to commands and development
| Command | Description |
|---|---|
npm i |
Run once to install dependencies |
npm run lint |
Lints the userscript with ESLint |
npm run build-dev |
Builds the userscript in development mode (sourcemaps enabled) |
npm run build-prod |
Builds the userscript in production mode (optimized code, sourcemaps disabled) |
npm run dev |
Watches, rebuilds and serves the userscript so it can be updated live (more info below) |
- If you're using the ViolentMonkey extension (which I recommend), after running the command
npm run watch, you may open the URL shown in the console in your browser and select theTrack local fileoption in the installation dialog.
This makes it so the userscript automatically updates when the code changes (reloading the website is still necessary).
Note: the tab needs to stay open on Firefox or the script won't keep updating itself. - My library UserUtils is already included as a dependency. It offers lots of utilities for userscripts like registering listeners for when CSS selectors exist, intercepting events, managing persistent user configurations, modifying the DOM more easily, various math and array functions and more. You can find the full list of features and its documentation here.
- The final bundled userscript file in the
dist/folder should be committed and pushed to GitHub.
This way, the@downloadURLand@updateURLdirectives make it so the script is automatically updated from that same file.
For this to work properly, don't forget to bump the version inpackage.jsonbefore building, so that every user of your userscript may receive the update. - The name of the emitted bundle inside
dist/is bound touserscriptNameinpackage.json
You may want to hard-code it or create a separate property for it if the userscript name contains characters that aren't allowed in a file path. - If you want other people to use your userscript, I recommend publishing it to GreasyFork and/or OpenUserJS
Make sure to check out and follow their rules and guidelines before publishing. - Use an IDE like VS Code so Intellisense and Typescript can work together to give you really awesome code completion and warn you about potential runtime errors before you even build the code.
- If you are using VS Code, install the ESLint extension (
dbaeumer.vscode-eslint) and bind a hotkey for theESLint: Fix all auto-fixable problemscommand so you can quickly format the currently active file according to the rules in.eslintrc.cjs - Try to get familiar with the webpack config at
webpack.config.js
In there you may add and configure webpack plugins and configure the build process. - To see an example of how the code in
src/index.tswill be packed in production mode, check out the file atdist/EXAMPLE.user.js
Made with ❤️ by Sv443
If you like this template, please consider supporting me
© 2023 Sv443 - WTFPL license