vite-userscript-plugin 1.11.0 → 2.1.0

package/README.md

@@ -1,146 +1,209 @@
 # vite-userscript-plugin
 
 [![npm](https://img.shields.io/npm/v/vite-userscript-plugin)](https://npmjs.com/vite-userscript-plugin)
-[![license](https://img.shields.io/github/license/crashmax-dev/vite-userscript-plugin)](./LICENCE)
-[![template](https://img.shields.io/github/package-json/v/crashmax-dev/vite-userscript-template?label=vite-userscript-template)](https://github.com/crashmax-dev/vite-userscript-template)
+[![license](https://img.shields.io/github/license/greasify/vite-userscript-plugin)](./LICENCE)
+[![template](https://img.shields.io/github/package-json/v/greasify/vite-userscript-template?label=vite-userscript-template)](https://github.com/greasify/vite-userscript-template)
 
-> ⚡️ A plugin for developing and building a Tampermonkey userscript based on [Vite](https://vitejs.dev).
-
-## Table of contents
-
-- [Features](#features)
-- [Install](#install)
-- [Setup config](#setup-config)
-- [Using style modules](#using-style-modules)
-- [Plugin configuration](#plugin-configuration)
+> A Vite plugin for developing and building Tampermonkey, Greasemonkey and Violentmonkey userscripts.
 
 ## Features
 
-- 🔥 Reloading page after changing any files.
-- 🔧 Configure Tampermonkey's Userscript header.
-- 💨 Import all [`grant`](https://www.tampermonkey.net/documentation.php#_grant)'s to the header by default in development mode.
-- 📝 Automatic addition of used [`grant`](https://www.tampermonkey.net/documentation.php#_grant)'s in the code when building for production.
-- 📦 Built-in Tampermonkey's TypeScript type definition.
+- 🔥 Vite HMR
+- 🔧 Configure Userscript header
+- 🎨 Inject CSS from imports and SFC components (Vue, Svelte)
+- 💨 All `@grant`s in the header in dev mode
+- 📝 Only used `@grant`s in the production build
+- 📦 Built-in types for Tampermonkey, Greasemonkey and Violentmonkey
+- 📄 Virtual module with script metadata
 
-## Install
+## Getting started
 
-```
-npm install vite-userscript-plugin -D
-```
-
-```
-yarn add vite-userscript-plugin -D
-```
+Requires **Vite 8** and Node `>=22`.
 
-```
+```bash
 pnpm add vite-userscript-plugin -D
 ```
 
-### Setup config
-
-```js
+```ts
 import { defineConfig } from 'vite'
-import Userscript from 'vite-userscript-plugin'
-import { name, version } from './package.json'
-
-export default defineConfig((config) => {
-  return {
-    plugins: [
-      Userscript({
-        entry: 'src/index.ts',
-        header: {
-          name,
-          version,
-          match: [
-            'https://example.com/',
-            'https://example.org/',
-            'https://example.edu/'
-          ]
-        },
-        server: {
-          port: 3000
-        }
-      })
-    ]
-  }
+import userscript from 'vite-userscript-plugin'
+import pkg from './package.json' with { type: 'json' }
+
+export default defineConfig({
+  plugins: [
+    userscript({
+      entry: 'src/index.ts',
+      header: {
+        name: pkg.name,
+        version: pkg.version,
+        match: [
+          'https://example.com/',
+          'https://example.org/'
+        ]
+      }
+    })
+  ]
 })
 ```
 
-### Setup NPM scripts
-
 ```json
-// package.json
 {
   "scripts": {
-    "dev": "vite build --watch --mode development",
+    "dev": "vite",
     "build": "vite build"
   }
 }
 ```
 
-### Setup TypeScript [types](https://www.typescriptlang.org/tsconfig#types)
+Add types: Vite, **one** manager (`tampermonkey`, `greasemonkey`, or `violentmonkey`), and the virtual module.
+
+`src/vite-env.d.ts`:
+
+```ts
+/// <reference types="vite/client" />
+/// <reference types="vite-userscript-plugin/types/tampermonkey" />
+/// <reference types="vite-userscript-plugin/virtual" />
+```
+
+Or `tsconfig.json`:
 
 ```json
-// tsconfig.json
 {
   "compilerOptions": {
     "types": [
-      "vite-userscript-plugin/types/tampermonkey"
+      "vite/client",
+      "vite-userscript-plugin/types/tampermonkey",
+      "vite-userscript-plugin/virtual"
     ]
   }
 }
 ```
 
-### Using style modules
+Details: [types/README.md](./types/README.md).
 
-```js
-import style from './style.css?raw'
+`vite` prints `/{fileName}.dev.user.js` — install that URL once. HMR covers code and styles.
 
-// inject style element
-const styleElement = GM_addStyle(style)
+`server.file: true` skips HMR. The same `vite` watch-builds `{fileName}.js` (headerless IIFE) and `{fileName}.proxy.user.js` with `@require file://` to that IIFE. Install the printed `/{fileName}.proxy.user.js` URL. See [examples/serve-file](./examples/serve-file).
 
-// remove style element
-styleElement.remove()
-```
+> [!IMPORTANT]
+> Changing `@match`, `@grant`, or `@name` needs a reinstall.
 
-## Plugin configuration
+`vite build` writes `{fileName}.user.js` to `dist/`. One-shot builds do not emit the proxy.
 
-```ts
-interface ServerConfig {
-  /**
-   * {@link https://github.com/sindresorhus/get-port}
-   */
-  port?: number;
-
-  /**
-   * @default false
-   */
-  open?: boolean;
-}
+## Multiple scripts
 
-interface UserscriptPluginConfig {
-  /**
-   * Path of userscript entry.
-   */
-  entry: string;
-
-  /**
-   * Userscript header config.
-   *
-   * @see https://www.tampermonkey.net/documentation.php
-   */
-  header: HeaderConfig;
-
-  /**
-   * Server config.
-   */
-  server?: ServerConfig;
-}
+Pass an array of configs. Each item is one full script — no shared `header`.
+
+See [examples/multiple-entries](./examples/multiple-entries).
+
+## Styles
+
+CSS from imports and SFC `<style>` (Vue, Svelte) is collected and injected into the userscript.
+
+```ts
+import './style.css'
 ```
 
+> [!NOTE]
+> Do not put userscript assets in `public/` — those URLs hit the host site and 404. Import the file so Vite inlines it.
+
+## HTML pages
+
+`index.html` is a normal Vite app next to the userscript. `vite` serves it at `/`. `vite build` writes it to `dist/` beside `{fileName}.user.js`.
+
+> [!WARNING]
+> Keep the page's `<script>` entries distinct from `entry`.
+
+Script metadata: import `virtual:vite-userscript-plugin` (`name`, `version`, `file`).
+
+See [examples/sourcemap](./examples/sourcemap).
+
+## Production
+
+`vite build` writes `{fileName}.user.js` and `{fileName}.meta.js`. `index.html` is written too, when present.
+
+Minify is off (`build.minify`). Sourcemaps are inlined into `.user.js` when `build.sourcemap` is on.
+
+See [examples/sourcemap](./examples/sourcemap).
+
+## Options
+
+`userscript(config)` or `userscript([config, config, …])`. Options are not shared across the array.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `entry` | — | Userscript entry. Required. |
+| `header` | — | Metablock. Required: `name`, `version`, `match`. |
+| `fileName` | sanitized `header.name` | Output base name (`{fileName}.user.js`). |
+| `server.open` | `false` | Open the install target when Vite starts. HMR: `.dev.user.js`. `file`: `.proxy.user.js` URL. |
+| `server.prefix` | `'server:'` | Prefix for `@name` in serve mode. `false` disables it. |
+| `server.file` | `false` | Watch-build `{fileName}.js` + `{fileName}.proxy.user.js` (`@require file://`). Install from the printed URL. No HMR. |
+| `cssInject` | `'auto'` | How production CSS is injected. `'auto'` uses `GM_addStyle` or a `<style>` node. |
+| `align` | `1` | Extra spaces after the longest `@key`. `false` — one space. |
+| `generate` | — | Rewrite the generated metablock. |
+| `autoMetaUrls` | `false` | Fill empty `updateURL` / `downloadURL` from `homepage` / `homepageURL` / `website` / `source`. |
+| `metaFile` | `true` | Emit `{fileName}.meta.js`. |
+
+Everything else on `header` follows the manager metablock (`@grant`, `@require`, `@connect`, …).
+
+In serve mode the header lists every grant. In production the plugin scans the bundle and writes only the grants in use. `grant: "none"` disables GM APIs and is never mixed with the scan.
+
+> [!WARNING]
+> Keep `metaFile: true` if you use `autoMetaUrls`. Otherwise `@updateURL` points at a file that is not emitted.
+
 ## Examples
 
-See the [examples](https://github.com/crashmax-dev/vite-userscript-plugin/tree/master/examples) folder.
+| Example | What it shows |
+| --- | --- |
+| [basic](./examples/basic) | Vanilla + SCSS. |
+| [react](./examples/react) | JSX, CSS, React refresh. |
+| [vue](./examples/vue) | SFC `<style>`, minify, sourcemap. |
+| [svelte](./examples/svelte) | SFC `<style>`. |
+| [multiple-entries](./examples/multiple-entries) | Two scripts. |
+| [sourcemap](./examples/sourcemap) | Inline map, HTML page, virtual module. |
+| [serve-file](./examples/serve-file) | `server.file`, install the proxy from the printed URL. |
+
+## FAQ
+
+### Scripts fail on Firefox because of CSP
+
+> [!WARNING]
+> The host page can block Vite modules from `localhost`. Use a CSP-disable extension, or a browser profile without the site CSP.
+>
+> https://github.com/Tampermonkey/tampermonkey/issues/952#issuecomment-638373937
+
+### HTTPS site, HTTP Vite — mixed content
+
+> [!WARNING]
+> `https://example.com` will not load `http://localhost:5173`. Serve Vite over HTTPS: [`vite-plugin-mkcert`](https://github.com/liuweiGL/vite-plugin-mkcert) before `userscript()`, or `server.https`.
+
+### `public/` assets 404 on the target site
+
+> [!NOTE]
+> Userscripts run on someone else’s origin. Import the file so Vite inlines it. `public/` only works for the `index.html` app on the Vite origin.
+
+### `@run-at document-start` feels late in dev
+
+> [!NOTE]
+> Serve injects `type="module"` (async). Production is a synchronous IIFE unless you use top-level `await`. `server.file` uses that IIFE in dev too.
+
+### `file://` `@require` is blocked
+
+> [!NOTE]
+> Tampermonkey must allow local file access (`@require` from `file://`). Violentmonkey polls the required file after you install `{fileName}.proxy.user.js` from the printed URL. HTTP `@require` and page auto-reload are not part of this mode.
+
+## Migration from v1
+
+| v1 | v2 |
+| --- | --- |
+| `vite build --watch` | `vite` (HMR) or `vite` + `server.file` |
+| `esbuildTransformOptions` | removed |
+| `server.port` | Vite `server.port` |
+| minify on by default | off; set `build.minify` |
+| `*.proxy.user.js` + `file://` | `server.file: true`, or HMR `.dev.user.js` |
+| Vite 3–7 | Vite 8 |
+| `scripts` + shared `header` | `userscript([config, config, …])` |
+| `ScriptOptions` | removed |
 
 ## License