tampermonkey-scripts

A personal collection of Tampermonkey userscripts. Each script is self-contained under scripts/<name>/ with its own src/, tests, meta.json, and built dist/<name>.user.js.

Scripts

Script	What it does	Install
Masonry Image Gallery	View every image on any page as a Pinterest-style masonry wall, with lightbox + keyboard nav (Ctrl+Alt+G), plus single/batch/zip image downloads.	Install

Clicking Install with Tampermonkey enabled opens the install prompt directly; Tampermonkey then auto-updates the script when a new version is pushed.

Develop

Built with vite-plugin-monkey.

npm install              # one-time: dev deps (vite, vite-plugin-monkey, vitest, playwright)
npm run build            # build every script -> scripts/<name>/dist/<name>.user.js
npm run build <name>     # build just one script
npm run dev <name>       # hot-reload dev server for one script (see below)
npm test                 # vitest unit tests across all scripts
npm run test:e2e         # playwright e2e (build first)

Hot-reload dev loop

npm run dev <name> starts a vite dev server for that script. It prints an Install URL — open it once with Tampermonkey to install a tiny proxy userscript that loads your locally-served code. After that, every edit to src/ live-updates in the browser, no rebuild or re-paste. Stop the server and run npm run build <name> for the final committed artifact.

Add a new script

1. Create scripts/<name>/ with:
   • meta.json — userscript metadata (see below).
   • vite.config.js — copy an existing one; it reads meta.json, so usually no edits beyond the path are needed.
   • src/main.js — entry point; import the rest of src/ from here.
   • test/ — optional *.test.js (vitest) and *.spec.js (playwright e2e).
   • README.md — what it does + install.
2. npm run build <name> produces scripts/<name>/dist/<name>.user.js.
3. Add a row to the table above.

meta.json

vite.config.js feeds this file to vite-plugin-monkey, which renders the ==UserScript== header and auto-fills @namespace, @downloadURL, and @updateURL from the repo coordinates in vite.config.js. version here is the single source of truth — bump it and push the rebuilt dist/ to ship an update.

{
  "name": "Masonry Image Gallery",
  "slug": "masonry-image-gallery",
  "version": "1.1.0",
  "description": "…",
  "author": "kouxing2000",
  "match": ["*://*/*"],
  "grant": ["GM_registerMenuCommand", "GM_getValue", "GM_setValue"],
  "runAt": "document-idle",
  "noframes": true
}

Supported keys: name, slug, version, description, author, match[], include[], grant[], require[], runAt, noframes.

Shipping an update

1. Bump version in the script's meta.json.
2. npm run build <name> and commit the changed dist/<name>.user.js.
3. Push to main. Tampermonkey picks up the new version via @updateURL.

License

MIT