You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# whether to trigger a bell sound in the terminal when the build is finished - defaults to false if empty, invalid or unset
2
-
RING_BELL=false
3
-
4
-
# HTTP port of the dev server where the userscript will be served (when using `npm run watch`) - defaults to 8710 if empty, invalid (NaN or <1024) or unset
1
+
# HTTP port of the dev server where the userscript will be served (when using `npm run dev`) - defaults to 8710 if empty
5
2
DEV_SERVER_PORT=8710
6
3
7
-
# whether to log dev server requests to the console - defaults to false if empty, invalid or unset
8
-
DEV_SERVER_LOG=false
4
+
# Whether to trigger the bell sound in some terminals when the code has finished (re)compiling - default is false
Typescript ESM template for making [userscripts](https://en.wikipedia.org/wiki/Userscript) that supports importing and parsing 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.
5
+
Extensive Typescript ESNext template and boilerplate for [userscripts](https://en.wikipedia.org/wiki/Userscript).
6
+
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.
6
7
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.
8
+
Intended to be used in conjunction with a Git repo as a resource CDN and build versioning system for the userscript.
7
9
8
10
Like this template? Please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
9
11
@@ -24,26 +26,99 @@ Like this template? Please consider [supporting the development ❤️](https://
24
26
25
27
## First steps:
26
28
1. Copy `.env.template` to `.env` and change the values inside if needed
27
-
2.Inside `package.json`, update the properties `name`, `userscriptName`, `description`, `homepage`, `author`, `license` and `repository.url`
29
+
2.Search for `#REPLACE:` with your IDE in the entire project and replace all placeholders with your own values
28
30
3. Replace the icon at `assets/icon.png` with your own or use [Google's or DuckDuckGo's favicon API](https://codepen.io/djekl/pen/QWKNNjv) in the userscript header
29
31
4. Replace the LICENSE.txt file with your own license or remove it if you want your code to be "all rights reserved"
30
-
5. Modify the variables and userscript header inside `src/tools/post-build.ts` to whatever you need (see also [GM header reference](https://wiki.greasespot.net/Metadata_Block))
32
+
5. Modify the userscript header inside `src/tools/post-build.ts` to whatever you need (see also [GM header reference](https://wiki.greasespot.net/Metadata_Block))
31
33
6. The eslint configuration at `.eslintrc.cjs` is what I use, feel free to remove rules if there are too many or modify them to your preferences
32
-
7. Add your own initialization functions to `init()` and `onLoad()` inside the entrypoint file at `src/index.ts` (read the comments for more info)
33
-
8. Remove the example HTML, CSS and TS files
34
-
9. Refer to [commands](#commands) and [development](#development-tips-and-notes)
34
+
7. Add your own initialization functions to `init()` and `run()` inside the entrypoint file at `src/index.ts` (read the comments for more info)
35
+
8. Refer to the sections [project structure](#project-structure), [commands](#commands) and [development](#development-tips-and-notes) next
36
+
37
+
<br>
38
+
39
+
## Project structure:
40
+
-**`assets/`**
41
+
Contains all the assets that are used in the userscript, like images, stylesheets, and any other misc files.
42
+
-**`assets/require.json`**
43
+
Contains a list of all modules that should be loaded using the `@require` directive.
44
+
Props:
45
+
-`pkgName` (required) - The npm name of the package
46
+
-`baseUrl` - The base URL of the CDN to load from (defaults to `https://cdn.jsdelivr.net/npm/`)
47
+
-`path` - The path to the file inside the package (uses jsdelivr's standard path by default)
48
+
-**`assets/resources.json`**
49
+
Contains a list of all resources that should be loaded using the `@resource` directive.
50
+
This is useful for loading files like stylesheets, images, and other assets that should not be included in the code bundle, but loaded in and cached by the userscript extension.
51
+
The object's key is used with the `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.
52
+
If the path starts with a slash, it will be resolved relative to the root of the project (where the `package.json` file is located).
53
+
-**`src/`**
54
+
Contains all the source files for the userscript.
55
+
-**`src/tools/`**
56
+
Contains all scripts that are used in the build process.
57
+
-**`src/tools/post-build.ts`**
58
+
Contains the post-build script that is run after the userscript is built.
59
+
This script inserts the userscript header and other custom injections into the final userscript file.
60
+
If you need to modify userscript directives or add custom injections, this is the place to do it.
61
+
-**`src/tools/serve.ts`**
62
+
Contains the development server that serves the userscript on port 8710 (by default).
63
+
-**`src/index.ts`**
64
+
The entrypoint for the userscript. This is where you should call your own code from.
65
+
-**`src/config.ts`**
66
+
This file contains the DataStore instance that should be used to hold your userscript's configuration object.
67
+
The DataStore class is really powerful and does a lot of the heavy lifting for you. More instances can also be created to hold different types of data that should be persisted between sessions.
68
+
For more info, please read the [DataStore documentation.](https://github.com/Sv443-Network/UserUtils#datastore)
69
+
-**`src/constants.ts`**
70
+
Contains some constant variables that are used throughout the userscript's runtime code.
71
+
This is where arguments are injected into the userscript's runtime code by `tools/post-build.ts`
72
+
-**`src/declarations.d.ts`**
73
+
The declarations in this file allow you to import HTML and MD files directly in your code, using rollup plugins.
74
+
-**`src/observers.ts`**
75
+
This file should be filled up with many `SelectorObserver` instances. These observe a designated part of the DOM for changes.
76
+
With the function `addSelectorListener()`, you can then add a listener, given a specific CSS selector, that gets called when the selector has been found in the DOM.
77
+
For more info, please read the [SelectorObserver documentation.](https://github.com/Sv443-Network/UserUtils#selectorobserver)
78
+
-**`src/types.ts`**
79
+
Contains all generic TypeScript types that are used in multiple files.
80
+
-**`src/utils.ts`**
81
+
Contains utility functions that are used throughout the userscript's runtime code.
82
+
This is where you should put functions that are used in multiple places in your code.
83
+
Once it gets too big you should split it up into multiple files.
84
+
35
85
36
86
<br>
37
87
38
88
## Commands:
39
-
| Command | Description |
40
-
| --- | --- |
41
-
|`npm i`| Run once to install dependencies |
42
-
|`npm run lint`| Lints the userscript with ESLint |
43
-
|`npm run build-dev`| Builds the userscript in development mode (sourcemaps enabled) |
44
-
|`npm run build-prod`| Builds the userscript in production mode (optimized code, sourcemaps disabled) |
45
-
|`npm run dev`| Watches, rebuilds and serves the userscript so it can be updated live ([more info below](#development-tips-and-notes)) |
46
-
<!-- first column uses non-breaking space U+00A0 (' ') -->
89
+
-**`npm i`**
90
+
Run once to install dependencies
91
+
-**`npm run dev`**
92
+
This is the command you want to use to locally develop and test your script.
93
+
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](#development-tips-and-notes)).
94
+
Once it has finished building, a link will be printed to the console. Open it to install the userscript.
95
+
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.
96
+
-**`npm run build-prod`**
97
+
Builds the userscript for production for all host platforms (GitHub, GreasyFork and OpenUserJS) with their respective options already set.
98
+
Outputs the files using a suffix predefined in the `package.json` file.
99
+
Use this to build the userscript for distribution on all hosts.
100
+
-**`npm run build -- <arguments>`**
101
+
Builds the userscript with custom options
102
+
Arguments:
103
+
-`--config-mode=<value>` - The mode to build in. Can be either `production` or `development` (default)
104
+
-`--config-branch=<value>` - The GitHub branch to target. Can be any branch name, but should be `main` for production and `develop` for development (default)
105
+
-`--config-host=<value>` - The host to build for. Can be either `github` (default), `greasyfork` or `openuserjs`
106
+
-`--config-assetSource=<value>` - Where to get the resource files from. Can be either `local` or `github` (default)
107
+
-`--config-suffix=<value>` - Suffix to add just before the `.user.js` extension. Defaults to an empty string
108
+
109
+
Shorthand commands:
110
+
-`npm run build-prod-base` - Sets `--config-mode=production` and `--config-branch=main`
111
+
Used for building for production, targeting the main branch
112
+
-`npm run build-develop` - Sets `--config-mode=development`, `--config-branch=develop` and `--config-assetSource=github`
113
+
Used for building for experimental versions, targeting the develop branch
114
+
-**`npm run lint`**
115
+
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!
116
+
-**`npm run --silent invisible -- "<command>"`**
117
+
Runs the passed command as a detached child process without giving any console output.
118
+
Remove `--silent` to see npm's info and error messages.
119
+
-**`npm run node-ts -- <path>`**
120
+
Runs the TypeScript file at the given path using the regular node binary and the node-ts loader.
121
+
Also enables source map support and disables experimental warnings.
47
122
48
123
<br>
49
124
@@ -65,9 +140,8 @@ Like this template? Please consider [supporting the development ❤️](https://
65
140
Make sure to check out and follow their rules and guidelines before publishing.
66
141
- Use an IDE like [VS Code](https://code.visualstudio.com/) 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.
67
142
- If you are using VS Code, install the ESLint extension ([`dbaeumer.vscode-eslint`](https://marketplace.visualstudio.com/items?itemName=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`
68
-
- Try to get familiar with the [webpack config](https://webpack.js.org/configuration/) at `webpack.config.js`
69
-
In there you may add and configure webpack plugins and configure the build process.
70
-
- To see an example of how the code in `src/index.ts` will be packed in production mode, check out the file at [`dist/EXAMPLE.user.js`](./dist/EXAMPLE.user.js)
143
+
- Try to get familiar with the [rollup config](https://rollupjs.org/configuration-options/) at `rollup.config.mjs`
144
+
In there you may add and configure rollup plugins and configure the build process.
71
145
72
146
<br><br><br>
73
147
@@ -76,6 +150,6 @@ Like this template? Please consider [supporting the development ❤️](https://
76
150
Made with ❤️ by [Sv443](https://github.com/Sv443)
77
151
If you like this template, please consider [supporting me](https://github.com/sponsors/Sv443)
0 commit comments