esbuild-plugin-userscript

0.2.6 verified Fri May 01 auth: no javascript

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.

Common errors

error Error: Cannot find module 'esbuild-plugin-userscript' ↓

cause Package not installed or not in node_modules.

fix

Run npm install esbuild-plugin-userscript --save-dev

error TypeError: userscript is not a function ↓

cause Using default import instead of named import.

fix

Use import { userscript } from 'esbuild-plugin-userscript' instead of import userscript from ...

error Error: [plugin: userscript] Invalid metadata option: '@name' ↓

cause Including '@' prefix in metadata keys.

fix

Use keys without '@': e.g., name: 'My Script' instead of '@name': 'My Script'.

error esbuild Build Failed: The plugin "userscript-proxy" didn't start a dev server ↓

cause 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.

Warnings

gotcha Proxy 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`.

deprecated As 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'`.

gotcha Metadata keys like `@match` and `@grant` are automatically prefixed; do not include the '@' symbol. ↓

fix Use `match: ['https://*/*']` instead of `'@match': ...`.

breaking Transition 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`.

Install

npm install esbuild-plugin-userscript

yarn add esbuild-plugin-userscript

pnpm add esbuild-plugin-userscript

Imports

userscript

wrong

const userscript = require('esbuild-plugin-userscript')

correct

import { userscript } from 'esbuild-plugin-userscript'

CommonJS require works but defaults to ESM in modern Node; named import is preferred.

userscript (as namespace)
wrong
```
import userscript from 'esbuild-plugin-userscript'
```
correct
```
import { userscript } from 'esbuild-plugin-userscript'
```
No default export; must use named import. Common mistake: treating it as default export.

userscript.metadata

wrong

import { metadata } from 'esbuild-plugin-userscript'

correct

import { userscript } from 'esbuild-plugin-userscript'; userscript.metadata()

Sub-plugins are accessed as methods on the main `userscript` object, not as separate named exports.

userscript.injectCode

wrong

import { injectCode } from 'esbuild-plugin-userscript'

correct

import { userscript } from 'esbuild-plugin-userscript'; userscript.injectCode()

Same pattern as metadata; injectCode is a method, not a top-level export.

Quickstart

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));