repository·main·Indexed 24 days ago
https://github.com/lisonge/vite-plugin-monkeyA Vite plugin for building userscripts compatible with engines like Tampermonkey, Violentmonkey, Greasemonkey, and ScriptCat. It provides a modern development experience featuring HMR, TypeScript support, and automated management of userscript metadata such as @grant, @require, and @resource. The project includes a scaffolding tool, create-monkey, with templates for frameworks including React, Vue, Svelte, and Solid.
vite-plugin-monkey is a Vite plugin designed to serve and build .user.js files for userscript engines. It enables a development workflow for creating scripts compatible with engines such as Tampermonkey, Violentmonkey, Greasemonkey, and ScriptCat.vite-plugin-monkey is a Vite plugin designed to facilitate the development of userscripts for engines like Tampermonkey, Violentmonkey, Greasemonkey, and ScriptCat.
Key features include:
@require and @resource to use external CDNs, reducing the final bundle size.GM_api via ESM imports with full TypeScript type hints. It also intelligently collects used GM_api calls to automatically configure the @grant metadata.top level await and dynamic import within single files.Hot Module Replacement (HMR) state preservation is disabled by default in svelte-hmr and @sveltejs/vite-plugin-svelte due to unpredictable behavior.
If you need to retain important component state during HMR, you should move that state into an external store. This prevents the state from being replaced when the component is reloaded.
// store.ts
// An extremely simple external store
import { writable } from 'svelte/store';
export default writable(0);When using iife-cdn, variables declared with var in an IIFE do not become properties of window within the Userscript scope. This causes issues when a UMD library (like element-plus) depends on an IIFE library (like vue).
To resolve this, append a dataUrl script after the iife-cdn declaration to manually attach the IIFE variable to the window object.
import { cdn, util } from 'vite-plugin-monkey';
const buildConfig = {
vue: cdn
.jsdelivr('Vue', 'dist/vue.global.prod.js')
.concat(util.dataUrl(';window.Vue=Vue;')),
'element-plus': cdn.jsdelivr('ElementPlus', 'dist/index.full.min.js'),
};HMR (Hot Module Replacement) state preservation is disabled by default in this template due to unpredictable behavior in svelte-hmr and @sveltejs/vite-plugin-svelte.
If you need to retain important state within a component during HMR, use an external Svelte store. External stores are not replaced by HMR, allowing the data to persist even when components are re-rendered.
// store.js
// An extremely simple external store
import { writable } from 'svelte/store';
export default writable(0);This template is designed as a lightweight starting point for Vite + TypeScript + Svelte projects, focusing on HMR and Intellisense.
Use this template instead of SvelteKit if you want a standard Vite app rather than a framework-first environment. SvelteKit uses its own routing and specialized build processes where standard vite dev or vite build commands may not work as expected. This template is structured to allow for easy migration to SvelteKit if extended capabilities are needed later.
global.d.ts with triple-slash references instead of compilerOptions.types in tsconfig.json. This ensures svelte and vite/client type information is added while still allowing TypeScript to accept type information from the entire workspace.allowJs is enabled in the TypeScript configuration. This allows for mixed codebases and ensures that JavaScript syntax within .svelte files is handled correctly without compromising typechecking quality.dist folder to any static host provider (such as Netlify, Surge, or Vercel/Now).To build a library that can be used by vite-plugin-monkey users via npm, follow these steps:
GM_api from vite-plugin-monkey/dist/client.tsup), exclude vite-plugin-monkey/dist/client from the bundle so users can provide their own implementation.@require, build an IIFE version where you alias vite-plugin-monkey/dist/client to vite-plugin-monkey/dist/native. This ensures the library uses the native implementation when bundled as an IIFE.This approach allows your library to be used seamlessly both as an npm dependency in a Vite project and as a standalone script via @require.
// /src/index.ts
import { GM_setValue } from 'vite-plugin-monkey/dist/client';
export const setValue = (name: string, value: unknown) => {
console.log('you invoke setValue', name, value);
GM_setValue(name, value);
};// tsup.config.ts
import { defineConfig } from 'tsup';
const outExtension = (ctx: { format: 'esm' | 'cjs' | 'iife' }) => ({
js: { esm: '.mjs', cjs: '.cjs', iife: '.iife.js' }[ctx.format],
});
export default defineConfig([
{
// for vite import
entry: ['src/index.ts'],
outDir: 'dist',
sourcemap: true,
platform: 'browser',
outExtension,
dts: true,
format: ['esm'],
external: ['vite-plugin-monkey/dist/client'],
},
{
// for userscript @require
entry: ['src/index.ts'],
outDir: 'dist',
sourcemap: true,
platform: 'browser',
outExtension,
dts: false,
format: ['iife'],
minify: true,
globalName: `GmExtra`,
target: 'es2015',
esbuildOptions: (options) => {
options.alias = {
'vite-plugin-monkey/dist/client': 'vite-plugin-monkey/dist/native',
};
},
},
]);To ensure the best development experience with Vue 3 SFCs, use the following IDE configuration:
To avoid manual imports while maintaining best practices, you can use unplugin-auto-import with the util.unimportPreset provided by vite-plugin-monkey.
// vite.config.ts
import { defineConfig } from 'vite';
import monkey, { util } from 'vite-plugin-monkey';
import AutoImport from 'unplugin-auto-import/vite';
export default defineConfig({
plugins: [
AutoImport({
imports: [
util.unimportPreset,
],
}),
monkey({
// ...
}),
],
});
// main.ts
// GM_api is automatically imported
console.log({ GM_cookie, unsafeWindow, monkeyWindow, GM_addElement });Build the application for production. This command bundles Solid in production mode, optimizes the build for performance, minifies the output, and includes hashes in the filenames. The production-ready files are output to the dist folder.
npm run build