An out-of-the-box template simplifying userscript development with auto-rebuilds on file changes, seamless WebDAV integration for extension syncing, semantic commit-based versioning, and a robust CI/CD pipeline for automated releases.
- UserScript Template
Click the Use this template > Create a new repository
button to create a new
repository based on this template.
git clone <YOUR REPOSITORY URL>/userscript-template.git
This project uses pnpm as package manager, you can install it by running:
npm install -g pnpm
or directly install it:
curl -fsSL https://get.pnpm.io/install.sh | sh -
Then install dependencies by running:
pnpm install
This template will read informations in package.json
to generate the script
header, so you have to adjust the informations in package.json
to fit your
script.
The following fields are recommended to be filled first:
Field | Required | Description |
---|---|---|
name |
Yes | The name of the script. |
description |
Yes | The description of the script. |
author.name |
Yes | The author of the script, fill your name there. |
homepage |
No | This will be the namespace and the homepage of the script. |
The script will read the user-script-meta
field in package.json
as the base
of the script header, then read above fields as an alternative value if empty.
It will take the key as the header field name, and take the value as the header
field value. So you can add any field you want to the user-script-meta
field.
For more detail, you can see webpack.config.js.
The version here will be auto updated by semantic commit message when you pushes
commits to main
branch, by supporting of
standard-version
.
If you're not familiar with semantic commit message, you can see Conventional Commits for more detail.
pnpm dev
For more detail, you can see 1. Start the dev server.
You could follows any one step in Sync with extension.
All done! Open src/index.ts
and start editing.
To start a development WebDAV server and auto rebuild the script on file changes, run:
pnpm dev
There are some environment variables you can use to customize the dev server:
PORT
: The port of fake WebDAV server, default is9000
.HOST
: The host of fake WebDAV server, default is0.0.0.0
.UUID
: The uuid of the scipt. This will force the script to use this UUID instead of detected or generated one. If not set, it will be a default value "12345678-1234-1234-123456789012", and it will be auto updated by matching the title of the script with thename
got frompackage.json
when the extension sync.DEBUG
: Enable debug mode, default isfalse
.
For example, if you want to change the port to 8080
, you can run:
PORT=8080 pnpm dev
pnpm build
The built script will be in dist
folder.
There are two way to setup the sync. To use the auto sync feature, you have to start the dev server first.
pnpm dev
You can see 5. Start the dev server with pnpm dev for more detail.
This is the easiest way to sync the script with extension. You can add a loader
script to your extension, then use @require
to import the script.
e.g. Create a new script with the following content:
// ==UserScript==
// @name Import script from url
// @description A proxy script to import script from url
// @version 0.0.1
// @namespace localhost
// @match *://*/*
// @require http://localhost:9000/bundle.user.js
// @grant none
// ==/UserScript==
Then the script will be loaded by this script. You may now browse the website and you'll find it works.
If you're using this way, you might have to check the script header.
Note that if you use this way, the external script will be cached by the extension. You can either manually clear the cached script in extension or set the external script update time to always.
Manual clear the cached script in extension:
e.g. For Tampermonkey, you can go to Externals > Requires
in script editor and
click Delete
button.
Set the external script update time to always:
e.g. For Tampermonkey, you can go to Settings > Externals
in extension
Settings and set Update Interval
to Always
.
After you start the dev server, you can install the script to extension.
The console output should hint you the link to install the script like this:
WebDAV server is listening on http://0.0.0.0:9000
You can install current script from: http://0.0.0.0:9000/bundle.user.js
Or if this is the first time you start this dev server, you should be able to install the script from the link below:
http://localhost:9000/bundle.user.js
Then you can setup the WebDAV sync in extension.
For Tampermonkey, you can follow the steps below:
- Go to
Tampermonkey > Settings > General > Config Mode
and set asAdvanced
. - Fill
URL
inUserscript Sync
withhttp://localhost:8080/
. - Check
Enable Userscript Sync
inUserscript Sync
. - Click
Save
.
Then you can click the "Run now" button to start sync.
The script's UUID is generated by your extension when you install the script. So you have to install the script first, then you can find the UUID.
To find the UUID, you can click the script and open the built-in editor, then you'll see the UUID in the URL.
e.g.
chrome-extension://dhdgffkkebhmkfjojejmpbldmpobfkfo/options.html#nav=ac6c73b7-55ec-446e-884c-7cab2087278c+editor
For example above, ac6c73b7-55ec-446e-884c-7cab2087278c
is the UUID.
Or you can then click the "Settings" tab, there will be a "UUID" field in "Details" section.