vite-plugin-monkey: build and develop userscripts for Tampermonkey and similar engines with Vite

vite-plugin-monkey closes the gap between npm packages and the single-file userscript format

Userscripts run inside browser extension engines like Tampermonkey and Violentmonkey, and they come with a structural constraint: the entire script must be a single file with a metadata block at the top. That metadata block controls which pages the script runs on, which permissions it requests through `@grant`, and which external libraries it loads through `@require`. Standard Vite projects split code across modules and bundle dependencies, which does not fit that format without help.

vite-plugin-monkey solves this by taking Vite's build output and producing a valid `.user.js` file complete with the metadata block. During development, it uses Vite's dev server so that frameworks like Vue, React and Svelte work as they would in any Vite project. TypeScript and the full Vite feature set are supported in the same way.

The plugin covers four named userscript engines: Tampermonkey, Violentmonkey, Greasemonkey and ScriptCat. The feature list also describes support for "other userscript engines," without naming them.

Creating a project with `pnpm create monkey` and choosing from 14 templates

The fastest way to start is the `create-monkey` scaffolding tool. Running it creates a new project directory with one of the available templates.

pnpm create monkey
# npm create monkey
# yarn create monkey

14 templates are available, split into JavaScript and TypeScript variants. The JavaScript set covers empty, vanilla (JS plus CSS), vue, react, preact, svelte and solid. Each has a TypeScript equivalent: empty-ts, vanilla-ts, vue-ts, react-ts, preact-ts, svelte-ts and solid-ts.

Choosing a framework template sets up the corresponding Vite framework plugin alongside vite-plugin-monkey. For a project that only needs TypeScript without a framework, the empty-ts template is the minimal starting point. For a project that does not need TypeScript or a framework at all, the empty template is the baseline.

The documentation lives at vite-plugin-monkey.pages.dev, which the README lists as the location for the Getting Started guide and the full configuration reference.

Installing into an existing Vite project and the plugin ordering requirement

For a project already using Vite, the plugin is added as a development dependency.

pnpm add -D vite-plugin-monkey
# npm i -D vite-plugin-monkey
# yarn add -D vite-plugin-monkey

One configuration constraint applies: vite-plugin-monkey must be added as the last item in the Vite plugin list. The README states this directly and links to the Getting Started guide for the basic configuration. Placing it earlier in the list means other plugins may process the output in ways that vite-plugin-monkey cannot then correct, so the order is not interchangeable.

The basic configuration requires adding the metadata block fields such as the script name, namespace and match patterns as options inside the plugin configuration. The full list of configuration options is in the documentation rather than in the README.

npm packages become @require CDN entries in the metadata block, not bundled code

One of the more useful features for a userscript with external dependencies is the handling of `@require` and `@resource` entries. A userscript engine loads external scripts by fetching URLs listed under `@require` in the metadata block. vite-plugin-monkey can convert npm dependencies into these CDN-backed `@require` entries instead of bundling them into the script body.

The practical effect is a smaller output file, since the dependency is fetched once by the engine and cached, rather than included inline. The trade-off is that the script depends on the CDN being available and serving the expected version at the URL in the `@require` line. The README describes this as loading external dependencies through `@require` entries.

Similarly, `@resource` entries load external files such as CSS or data files. Those resources are fetched by the engine and accessed through the GM APIs that retrieve resource text or resource URLs.

@grant entries are detected automatically from GM API usage in the source code

Writing a userscript by hand requires adding a `@grant` entry to the metadata block for each GM API the script calls. Omitting a `@grant` declaration causes the engine to block that API call, and the failure is not always obvious at a glance.

vite-plugin-monkey removes that manual step. It analyzes the source code, collects the GM APIs the code uses, and writes the `@grant` entries into the metadata block automatically. The feature description states this clearly: "Collect the GM APIs used by the code and configure `@grant` automatically."

The complementary feature is the ESM import path for GM APIs with type hints. Instead of calling GM APIs as globals, the code imports them as named exports, and TypeScript can provide autocompletion and type checking on those imports. The type hints make it easier to discover which GM API calls are available for a given engine, since the types reflect the engine's actual API surface rather than a generic approximation.

Top-level await and dynamic imports work in the single-file output

Standard userscripts run as immediately-invoked scripts without native module support, which means top-level await and dynamic imports have not historically been straightforward to use. vite-plugin-monkey lists both as supported features in the single userscript file output.

Hot module replacement is also supported during development, with a visible caveat. When the userscript's metadata changes, the plugin opens the development userscript in the default browser rather than applying HMR inline. This is the expected behavior because the metadata block controls the engine's behavior, and a metadata change requires the engine to re-read the script. For code changes that do not touch the metadata, standard HMR applies as it would in any Vite project.

Vite preview mode is also integrated: when Vite preview is run, the built userscript opens automatically. That gives a way to verify the final output file in the engine before distribution.

The last push was on 2026-09-16, and v8.1.1 shipped on 2026-08-30.

Writing a userscript without Vite: when the direct approach is enough

The alternative to vite-plugin-monkey is writing a userscript directly, without a build step. Tampermonkey, Violentmonkey and the other engines have built-in editors that handle syntax highlighting and save the script directly to the engine. For a script that does not use a front-end framework, does not need TypeScript, and is short enough to maintain in one file without a bundler, the built-in editor requires no setup and no dependency on Vite or Node.

The decision point is complexity. A short script that adds a button to a page, intercepts an API call or changes a CSS rule does not need a build pipeline. Once the project grows to include multiple modules, a framework component, TypeScript types or shared utilities, assembling that manually becomes impractical, and a build tool like vite-plugin-monkey provides a meaningful benefit.

The MIT licence covers the plugin itself; the LICENCE file at the repository root is the text to read.

Editorial conclusion

vite-plugin-monkey is the right tool when a userscript project needs TypeScript, a front-end framework such as Vue or React, or Vite's HMR during development. It is not necessary for a simple script with no framework dependencies, where a plain text editor and Tampermonkey's built-in editor are sufficient. Before adopting, confirm that vite-plugin-monkey is placed last in the Vite plugin list, because plugin ordering affects how each plugin processes the output. Review the Getting Started guide at vite-plugin-monkey.pages.dev to understand metadata configuration, particularly how @require entries are generated from npm packages.

Frequently asked questions

Official sources

1. License: MIT
2. lisonge/vite-plugin-monkey on GitHub
3. Project website
4. README
5. Releases