{"id":25418,"library":"esbuild-plugin-userscript","title":"esbuild-plugin-userscript","description":"ESbuild plugin suite for building userscripts targeting Tampermonkey, Greasymonkey, Violentmonkey, and other userscript engines. Current stable version is 0.2.6. The package provides three distinct plugins: `userscript-inject-code` for injecting code fragments, `userscript-metadata` for generating metadata headers (e.g., @name, @match, @grant), and `userscript-proxy` to create development proxy scripts that bypass browser cache during development. Unlike general bundler plugins, this package is purpose-built for userscript workflows, supporting both CommonJS and ESM via esbuild. Key differentiators include combined or individual plugin usage, TypeScript-first design, and minimal configuration overhead.","status":"active","version":"0.2.6","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","esbuild","plugin","userscript","tampermonkey","greasymonkey","violentmonkey"],"install":[{"cmd":"npm install esbuild-plugin-userscript","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-userscript","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-userscript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS require works but defaults to ESM in modern Node; named import is preferred.","wrong":"const userscript = require('esbuild-plugin-userscript')","symbol":"userscript","correct":"import { userscript } from 'esbuild-plugin-userscript'"},{"note":"No default export; must use named import. Common mistake: treating it as default export.","wrong":"import userscript from 'esbuild-plugin-userscript'","symbol":"userscript (as namespace)","correct":"import { userscript } from 'esbuild-plugin-userscript'"},{"note":"Sub-plugins are accessed as methods on the main `userscript` object, not as separate named exports.","wrong":"import { metadata } from 'esbuild-plugin-userscript'","symbol":"userscript.metadata","correct":"import { userscript } from 'esbuild-plugin-userscript'; userscript.metadata()"},{"note":"Same pattern as metadata; injectCode is a method, not a top-level export.","wrong":"import { injectCode } from 'esbuild-plugin-userscript'","symbol":"userscript.injectCode","correct":"import { userscript } from 'esbuild-plugin-userscript'; userscript.injectCode()"}],"quickstart":{"code":"const esbuild = require('esbuild');\nconst { userscript } = require('esbuild-plugin-userscript');\nesbuild.build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'dist/userscript.user.js',\n  plugins: [\n    userscript({\n      metadata: {\n        name: 'My Userscript',\n        version: '1.0.0',\n        match: ['https://example.com/*'],\n        grant: ['GM_setValue', 'GM_getValue']\n      },\n      proxy: {\n        baseUrl: 'http://localhost:3000',\n        enable: true\n      }\n    })\n  ]\n}).catch(() => process.exit(1));\n","lang":"javascript","description":"Shows a complete esbuild build configuration using the userscript plugin to add metadata and proxy support for development."},"warnings":[{"fix":"Start a local dev server (e.g., `npx serve dist`) or use a separate tool like `browser-sync`.","message":"Proxy plugin (userscript.proxy) requires a running local server; no automatic server is started.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Replace `userscriptMetadata()` with `userscript.metadata()` via `import { userscript } from 'esbuild-plugin-userscript'`.","message":"As of 0.2.0, the standalone plugin names were removed; use the combined `userscript()` entry.","severity":"deprecated","affected_versions":">=0.2.0 <0.3.0"},{"fix":"Use `match: ['https://*/*']` instead of `'@match': ...`.","message":"Metadata keys like `@match` and `@grant` are automatically prefixed; do not include the '@' symbol.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use `const { userscript } = require('esbuild-plugin-userscript')` or switch to ESM `import`.","message":"Transition from CommonJS to ESM-esque exports in v0.1.0 broke `require('esbuild-plugin-userscript')` in some contexts.","severity":"breaking","affected_versions":">=0.1.0 <0.2.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install esbuild-plugin-userscript --save-dev`","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'esbuild-plugin-userscript'"},{"fix":"Use `import { userscript } from 'esbuild-plugin-userscript'` instead of `import userscript from ...`","cause":"Using default import instead of named import.","error":"TypeError: userscript is not a function"},{"fix":"Use keys without '@': e.g., `name: 'My Script'` instead of `'@name': 'My Script'`.","cause":"Including '@' prefix in metadata keys.","error":"Error: [plugin: userscript] Invalid metadata option: '@name'"},{"fix":"Start your own dev server (e.g., `http-server dist`) or use a watcher that serves files.","cause":"Proxy plugin expects an external server; no auto-start.","error":"esbuild Build Failed: The plugin \"userscript-proxy\" didn't start a dev server"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}