Registry / devops / esbuild-plugin-userscript

esbuild-plugin-userscript

JSON →
library0.2.6jsnpmunverified

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.

devopshttp-networking
npm install esbuild-plugin-userscript
package ↗
INSTALL
IMPORT
SIG · ESBUILD-PLUGIN-USE
E
esbuild-plugin-userscript
devopsjavascriptv0.2.6
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

userscript
✓ import { userscript } from 'esbuild-plugin-userscript'
✗ const userscript = require('esbuild-plugin-userscript')
CommonJS require works but defaults to ESM in modern Node; named import is preferred.
userscript (as namespace)
✓ import { userscript } from 'esbuild-plugin-userscript'
✗ import userscript from 'esbuild-plugin-userscript'
No default export; must use named import. Common mistake: treating it as default export.
userscript.metadata
✓ import { userscript } from 'esbuild-plugin-userscript'; userscript.metadata()
✗ import { metadata } from 'esbuild-plugin-userscript'
Sub-plugins are accessed as methods on the main `userscript` object, not as separate named exports.
userscript.injectCode
✓ import { userscript } from 'esbuild-plugin-userscript'; userscript.injectCode()
✗ import { injectCode } from 'esbuild-plugin-userscript'
Same pattern as metadata; injectCode is a method, not a top-level export.

Shows a complete esbuild build configuration using the userscript plugin to add metadata and proxy support for development.

const esbuild = require('esbuild'); const { userscript } = require('esbuild-plugin-userscript'); esbuild.build({ entryPoints: ['src/index.js'], bundle: true, outfile: 'dist/userscript.user.js', plugins: [ userscript({ metadata: { name: 'My Userscript', version: '1.0.0', match: ['https://example.com/*'], grant: ['GM_setValue', 'GM_getValue'] }, proxy: { baseUrl: 'http://localhost:3000', enable: true } }) ] }).catch(() => process.exit(1));
Debug
Known issues
gotchaProxy plugin (userscript.proxy) requires a running local server; no automatic server is started.
fix
Start a local dev server (e.g., `npx serve dist`) or use a separate tool like `browser-sync`.
affects: >=0.0.0
deprecatedAs of 0.2.0, the standalone plugin names were removed; use the combined `userscript()` entry.
fix
Replace `userscriptMetadata()` with `userscript.metadata()` via `import { userscript } from 'esbuild-plugin-userscript'`.
affects: >=0.2.0 <0.3.0
gotchaMetadata keys like `@match` and `@grant` are automatically prefixed; do not include the '@' symbol.
fix
Use `match: ['https://*/*']` instead of `'@match': ...`.
affects: >=0.0.0
breakingTransition from CommonJS to ESM-esque exports in v0.1.0 broke `require('esbuild-plugin-userscript')` in some contexts.
fix
Use `const { userscript } = require('esbuild-plugin-userscript')` or switch to ESM `import`.
affects: >=0.1.0 <0.2.0
Errors
Common errors & fixes
Error: Cannot find module 'esbuild-plugin-userscript'
Package not installed or not in node_modules.
fix
Run `npm install esbuild-plugin-userscript --save-dev`
TypeError: userscript is not a function
Using default import instead of named import.
fix
Use `import { userscript } from 'esbuild-plugin-userscript'` instead of `import userscript from ...`
Error: [plugin: userscript] Invalid metadata option: '@name'
Including '@' prefix in metadata keys.
fix
Use keys without '@': e.g., `name: 'My Script'` instead of `'@name': 'My Script'`.
esbuild Build Failed: The plugin "userscript-proxy" didn't start a dev server
Proxy plugin expects an external server; no auto-start.
fix
Start your own dev server (e.g., `http-server dist`) or use a watcher that serves files.
Upgrade
Version history
0.2.6latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
packagehttps://www.npmjs.com/package/esbuild-plugin-userscript ↗
esbuild-plugin-userscript — npm install esbuild-plugin-userscript · libregistry