A Vite plugin for developing and building Tampermonkey, Greasemonkey and Violentmonkey userscripts.

• 🔥 Vite HMR
• 🔧 Configure Userscript header
• 🎨 Inject CSS from imports and SFC components (Vue, Svelte)
• 💨 All @grants in the header in dev mode
• 📝 Only used @grants in the production build
• 📦 Built-in types for Tampermonkey, Greasemonkey and Violentmonkey
• 📄 Virtual module with script metadata

Requires Vite 8 and Node >=22.

pnpm add vite-userscript-plugin -D

import { defineConfig } from 'vite'
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/'
        ]
      }
    })
  ]
})

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

Add types: Vite, one manager (tampermonkey, greasemonkey, or violentmonkey), and the virtual module.

src/vite-env.d.ts:

/// <reference types="vite/client" />
/// <reference types="vite-userscript-plugin/types/tampermonkey" />
/// <reference types="vite-userscript-plugin/virtual" />

Or tsconfig.json:

{
  "compilerOptions": {
    "types": [
      "vite/client",
      "vite-userscript-plugin/types/tampermonkey",
      "vite-userscript-plugin/virtual"
    ]
  }
}

Details: types/README.md.

vite prints /{fileName}.dev.user.js — install that URL once. HMR covers code and styles.

vite build writes {fileName}.user.js to dist/.

Pass an array of configs. Each item is one full script — no shared header.

See examples/multiple-entries.

CSS from imports and SFC <style> (Vue, Svelte) is collected and injected into the userscript.

import './style.css'

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.

Script metadata: import virtual:vite-userscript-plugin (name, version, file).

See examples/sourcemap.

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.

userscript(config) or userscript([config, config, …]). Options are not shared across the array.

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.

MIT © crashmax