vite-plugin-monkey

7.1.9 verified Mon Apr 27 auth: no javascript

A Vite plugin for developing and building userscripts (.user.js) targeting Tampermonkey, Violentmonkey, Greasemonkey, and ScriptCat. Current stable version is 7.1.9, with frequent releases addressing edge cases and HMR improvements. Key differentiator: leverages Vite's fast dev server with hot reload for userscripts, supports TypeScript, CSS modules, and advanced GM_ API types. Requires Vite ^6.0.0 || ^7.0.0 as peer dependency.

Common errors

error Error: Cannot find module 'vite-plugin-monkey' ↓

cause Missing dependency or incorrect import path.

fix

Run 'npm install vite-plugin-monkey --save-dev' (or yarn/pnpm equivalent).

error TypeError: vitePluginMonkey is not a function ↓

cause Incorrect import: using named import instead of default import.

fix

Change to 'import vitePluginMonkey from 'vite-plugin-monkey''.

error [vite] Internal server error: Cannot read properties of null (reading 'head') ↓

cause document.head is null when run-at document-start and using an older version of the plugin.

fix

Upgrade vite-plugin-monkey to v7.1.5 or later, or modify the userscript to run at document-end.

Warnings

breaking vite-plugin-monkey v7 dropped support for Vite 5 and below. Requires Vite ^6.0.0 || ^7.0.0. ↓

fix Upgrade Vite to 6.x or 7.x, or stay on vite-plugin-monkey v6 if using Vite 5.

gotcha In HMR, styles might not update correctly if they are imported via CSS modules or injected dynamically. A full page reload or manual style reload may be needed. ↓

fix Use 'styleImport' feature (v7.1.0+) for better CSS injection support, or trigger a full reload after style changes.

gotcha When using 'run-at document-start', document.head may be null, leading to errors in style injection or script execution. ↓

fix Upgrade to v7.1.5 or later which fixes this issue.

deprecated The 'expose' function in client-side code is being replaced by a global injection pattern. Direct use of 'expose' may be removed in future versions. ↓

fix Use the global 'expose' provided by the plugin's inject script rather than importing it directly.

Install

npm install vite-plugin-monkey

yarn add vite-plugin-monkey

pnpm add vite-plugin-monkey

Imports

vitePluginMonkey

wrong

import { vitePluginMonkey } from 'vite-plugin-monkey'

correct

import vitePluginMonkey from 'vite-plugin-monkey'

Default export, not named. Use default import syntax.

defineConfig

wrong

import { defineConfig } from 'vite-plugin-monkey'

correct

import { defineConfig } from 'vite'

defineConfig is from Vite itself, not from this plugin.

expose
wrong
```
import { expose } from 'vite-plugin-monkey/dist/client'
```
correct
```
import { expose } from 'vite-plugin-monkey'
```
expose is a named export from the main entry, but recommended to use the global expose provided by the plugin's inject script.

Quickstart

Basic Vite config for a userscript that shows on example.com and uses GM_notification.

import { defineConfig } from 'vite';
import vitePluginMonkey from 'vite-plugin-monkey';

export default defineConfig({
  plugins: [
    vitePluginMonkey({
      entry: 'src/main.ts',
      userscript: {
        name: 'Hello World',
        namespace: 'https://example.com',
        version: '1.0.0',
        description: 'My first userscript',
        author: 'You',
        match: ['https://example.com/*'],
        grant: ['GM_notification'],
      },
      build: {
        fileName: 'hello.user.js',
      },
    }),
  ],
});