webpack-monkey


A webpack plugin for developing your userscripts with a modern workflow.

Focusing on support for Tampermonkey and Violentmonkey.

- Features
- Installation
- Quick start
- 1. Set up the project
- 2. Install the dev script
- 3. Start developing
- 4. Build for release
- Advanced: multiple userscripts
- More examples
- API / Configuration
- monkey(config)
- module.hot.monkeyReload(options)
- Meta generation
- External dependencies (@require)
- External assets (@resource)
- CSS
- TypeScript
- Working with HMR
- Comparison with vite-plugin-monkey
- Development Notes

Features

- HMR (Hot Module Replacement): Easily apply changes without page reload.
- CSP bypassing: No worries about CSP restrictions during development.
- Meta generation: Generate userscript meta blocks programmatically.
- Multiple userscripts: Develop multiple userscripts at the same time.
- Clean output: Comply with the userscript hosting sites' no-minification requirement.

The modern workflow also allows:

- Compiling: Use the latest JavaScript features and even TypeScript.
- Code splitting: Split your code into multiple files, and share code between userscripts.

Installation

``sh
npm install webpack-monkey

peer dependencies


npm install webpack webpack-dev-server
`

Quick start

Here is a preview of the final file structure:

`
.
├── dist
│ └── hello.user.js
├── src
│ ├── index.js
│ └── meta.js
├── webpack.config.js
└── package.json
`

$3

Create a new project and initialize it with npm:

`sh
npm init -y
npm install webpack webpack-cli webpack-dev-server webpack-monkey
`

Create src/index.js:

`js
GM_log("Hello world!")

// enable HMR, for more details please check the HMR section below
if (module.hot) {
module.hot.monkeyReload()
}
`

Create src/meta.js:

`js
module.exports = {
name: "Hello world",
version: "1.0.0",
match: ["*://example.com"],
}
`

Create webpack.config.js:

`js
const path = require("path")
const { monkey } = require("webpack-monkey")

module.exports = monkey({
entry: {
hello: "./src/index.js",
},
output: {
path: path.resolve(__dirname, "dist"),
},
})
`

Finally, add the following scripts to package.json:

`json
{
"scripts": {
"dev": "webpack serve --mode development",
"build": "webpack --mode production"
}
}
`

$3

Run npm run dev. When the dev server is ready, you should see a message like this:

`
[MonkeyPlugin] Dev script hosted at: http://localhost:xxxx/monkey-dev.user.js
`

Now open the URL in your browser and install the dev script.

> [!IMPORTANT]
> Unless the dev server's _port_ has changed, you don't need to reinstall the dev script after running npm run dev next time.

$3

Go to http://example.com and open the console, you should see the message "Hello world!".

Now edit index.js and try to change the message text in GM_log(), save the file, and you'll see the new message printed in the console without page reload!

$3

Run npm run build, and the userscript will be built to dist/hello.user.js:

`js
// ==UserScript==
// @name Hello world
// @grant GM_log
// @match *://example.com
// @version 1.0.0
// ==/UserScript==

;(() => {
GM_log("Hello, world!")
})()
`

Note that the GM_log function is automatically added to @grant.

$3

Set up your project as follows to develop multiple userscripts at the same time:

`
.
├── dist
│ ├── foo.user.js
│ └── bar.user.js
├── src
│ ├── foo
│ │ ├── index.js
│ │ └── meta.js
│ └── bar
│ ├── index.js
│ └── meta.js
├── webpack.config.js
└── package.json
`

And update webpack.config.js as:

`js
const path = require("path")
const { monkey } = require("webpack-monkey")

module.exports = monkey({
entry: {
foo: "./src/foo/index.js",
bar: "./src/bar/index.js",
},
output: {
path: path.resolve(__dirname, "dist"),
},
})
`

Now you can run npm run dev and both userscripts will be served, no need to install the dev scripts again.

$3

- This project's examples
- This project's playground
- My own userscripts repo: userscripts (in pure TypeScript)

API / Configuration

$3

Takes a webpack config object and returns a cloned config object with plugins added and some options modified.

> [!NOTE]
> The followings are some major changes to the config, for more details please check the source code.
>
> - Adds some sensible defaults for userscript development.
> - Adds MonkeyPlugin to the plugins list.
> - Replaces the default minimizer TerserPlugin with MonkeyMinimizer, which extends TerserPlugin with some extra features.

The monkey options are passed as the monkey property of the webpack config object:

`js
module.exports = monkey({
// normal webpack options
entry: "./src/index.js",
output: {
path: path.resolve(__dirname, "dist"),
},

// monkey options
monkey: {
debug: true,
},
})
`

Options

- debug
- meta.resolve
- meta.load
- meta.transform
- require.provider
- require.lockVersions
- require.exportsFromUnnamed
- require.resolve
- devScript.meta
- devScript.transform
- beautify.prettier
- terserPluginOptions

You'll find some options that can be a function with a context object as the second argument. The context object has the following type:

`ts
interface OptionFunctionContext {
logger: WebpackLogger | Console
}
`

#### debug

Type: boolean\
Default: false

When enabled, some debug messages will be printed in the console (just a few for now).

#### meta.resolve

Type: string | string[] | (arg: { entryName: string; entry: string }, context) => string | undefined | Promise\
Default: ["meta.js", "meta.ts", "meta.json"]

The path of meta file to be used by meta.load later. If an array, the first file that matches will be used.

You can pass a custom function as the resolver:

`ts
monkey({
monkey: {
meta: {
resolve({ entry }) {
return path.resolve(path.dirname(entry), "meta.txt")

// if undefined, this entry will not be treated as a userscript
// return undefined
},
},
},
})
`

#### meta.load

Type: (arg: { file: string }, context) => UserscriptMeta | Promise\
Default: require()

Function to load the meta file and return the meta object. The default function uses require() to load the meta file with supported extensions: .js, .ts, .json.

`ts
monkey({
monkey: {
meta: {
load({ file }) {
// read JSON from a meta.txt given by the above meta.resolve example
return JSON.stringify(fs.readFileSync(file, "utf-8"))
},
},
},
})
`

#### meta.transform

Type: (arg: { meta: UserscriptMeta }, context) => UserscriptMeta | Promise\
Default: undefined

Function to transform the meta object before using it for serving or building. Can be used to add or modify meta properties.

#### require.provider

Type: "jsdelivr" | "unpkg"\
Default: "unpkg"

When importing modules using webpack externals, the module will be resolved to // @require /@, where is the provider's URL prefix (for example https://cdn.jsdelivr.net/npm), and is the version of the installed package, or, if not found, the version range specified in the project's package.json (can be controlled with require.lockVersions).

#### require.lockVersions

Type: boolean\
Default: true

When using a CDN provider, this option controls whether to generate URLs with the versions of installed packages, or the version ranges specified in the project's package.json. For example:

- false: https://unpkg.com/jquery@^3.5.0 (version range specified in package.json)
- true: https://unpkg.com/jquery@3.6.0 (version actually installed)

#### require.exportsFromUnnamed

Type: boolean\
Default: false

When importing an external module with URL, whether to allow using its exports without specifying a global variable name for it. For example:

`js
import { ajax } from "https://unpkg.com/jquery"
`

The above code will cause a runtime error because a global variable ($) is not specified along with the URL. In this case, webpack-monkey will print a warning in development mode and throw an error in production mode. Setting this option to true suppresses the warning and error.

#### require.resolve

Type:

`ts
type RequireResolver = (
arg: {
name: string // the module name
externalType: string // you would't need this if you don't know what it is
version?: string // the installed version, or undefined if not found
packageVersion?: string // the version specified in package.json, or undefined if not found
url?: string // the URL if the module is imported with URL, otherwise undefined
},
context: object,
) => string | undefined | Promise
`

Default: undefined

Custom resolver for external dependencies. The function should return a URL string, or undefined if the module should not produce a @require.

`js
monkey({
monkey: {
require: {
resolve({ name, url }) {
if (name.includes("dev-tools")) {
return undefined
}

return url || "https://unpkg.com/" + name
},
},
},
})
`

#### devScript.meta

Type: UserscriptMeta | ((arg: { meta: UserscriptMeta }) => UserscriptMeta)\
Default: undefined

Meta object for the dev script. If an object, it will be merged with the default meta object; if a function, it will be called with the default meta object as the argument, and the returned object will be used as a replacement.

#### devScript.transform

Type: (arg: { content: string }, context) => string\
Default: undefined

Function to transform the dev script content before serving. Can be used to add or modify the script content.

#### beautify.prettier

Type: boolean\
Default: undefined

When enabled, the output will be formatted using Prettier with your Prettier config. When undefined, it will be enabled if Prettier is found installed.

#### terserPluginOptions

Type: object\
Default: undefined

Custom options for the minimizer TerserPlugin.

$3

Works the same as module.hot.accept(), except that it'll reload the whole userscript instead of the changed module and the modules that depend on it. See Working with HMR section for more details.

Options

- ignore

#### ignore

Type: (string | RegExp)[] | (moduleId: string | number) => boolean\
Default: ["node_modules"]

Modules to ignore when reloading. Can be a list of strings or regular expressions, or a function that returns a boolean.

Note that this only affects the modules that webpack-monkey tries to additionally reload, and does not affect the modules that webpack would reload according to its own rules.

Meta generation

The meta object is provided in a separate file. By default, webpack-monkey will look for meta.js, meta.ts, or meta.json in the same directory as the entry file, and load it with require().

You can customize this behavior with the monkey.meta.resolve and monkey.meta.load options.

> [!NOTE]
> The meta file is evaluated in the Node.js environment, so you can require() other modules in it, and cannot use browser APIs such as window.

The meta fields have different types as shown below:






































Type	Fields	Example	Example output
Boolean	noframes	`js module.exports = { noframes: true, } `	`js // @noframes `
Array	grant match include exclude require resource connect webRequest	`js module.exports = { match: [ "*://example.com", "*://example.org" ], // can be a string if only one item require: "https://example.com/foo.js", // empty array will be omitted resource: [], } `	`js // @match *://example.com // @match *://example.org // @require https://example.com/foo.js `
Object (I18n)	name description	`js module.exports = { name: { default: "Hello world", "zh-CN": "你好世界", }, // can be a string if only one item description: "Say hello to the world!", } `	`js // @name Hello world // @name:zh-CN 你好世界 // @description Say hello to the world! `
String	All the others	`js module.exports = { version: "0.1", } `	`js //@version 0.1 `

External dependencies (@require)

There are several ways to handle external dependencies, please choose the one that suits you best.

1. meta.require (simple)
2. import with URL (good for tree-shaking)
3. Webpack externals with URL (good for tree-shaking and TypeScript) <- recommended
4. Webpack externals with global variable (most flexible)

$3

The simplest way is to put the URL in the require meta property:

`js
// meta.js
module.exports = {
require: [
"https://unpkg.com/jquery@3.6.0",

// to load a specific file instead of the default entry, specify its full path
"https://unpkg.com/lodash@4.17.21/lodash.min.js",
],
}

// index.js
$(".foo").text(_.capitalize("hello world"))
`

$3

You can directly import an external script with URL:

`js
// index.js
import "https://unpkg.com/jquery@3.6.0"

$(".foo")
`

You can also use other import forms. When using an import form other than _Side effect import_, the external script will be treated as a module, and you must provide a global variable name to reference the module in the format of "@", for example:

`js
import jq, { ajax } from "$@https://unpkg.com/jquery@3.6.0"

jq(".foo").click(() => ajax("/api"))
`

The above code is roughly equivalent to the following:

`js
import "https://unpkg.com/jquery@3.6.0"

const jq = $
const { ajax } = $
`

... except that the global variable $ is treated as a module object, so webpack generates a shim for it - not much a thing to worry about though.

Note that you don't need to specify an import name that is different from the global variable name, because webpack will (always) rename it to a longer form. For example, you can write import $ from "$@...", and webpack will generate an output like const external_$_namespaceObject = $.

$3

`js
// webpack.config.js
module.exports = {
externals: {
// same rule as in [2. import with URL], specify a global variable name if needed
jquery: "https://unpkg.com/jquery@3.6.0",
lodash: "_@https://unpkg.com/lodash",
},
}

// index.js
import "jquery"
import _ from "lodash"
`

$3

`js
// webpack.config.js
module.exports = {
externals: {
jquery: "$",
},
}

// index.js
import "jquery"
// or
import $ from "jquery"
`

In this case, the module will be resolved to a URL according to the require option. If require.resolve is specified, it will be used; otherwise, a CDN provider will be used according to require.provider.

External assets (@resource)

Not well supported yet, coming soon. For now, you can put the asset URLs in the meta object, and manually fetch them during development:

`js
// meta.js
module.exports = {
resource: ["myText https://example.com/my-text.txt"],
}

// index.js
async function main() {
const myText =
process.env.NODE_ENV === "development"
? await fetch("https://example.com/my-text.txt").then((res) => res.text())
: GM_getResourceText("myText")

console.log(myText)
}
`

CSS

You can import CSS files in your js files (check out webpack's guide), and webpack-monkey will bundle them into the userscript:

index.js

`js
import "./styles.css"

GM_log("Hello world!")
`

styles.css

`css
body {
color: red;
}
`

dist/hello.user.js

`js
// ==UserScript==
// @name Hello world
// @grant GM_log
// @grant GM_addStyle
// @match :///*
// @version 1.0.0
// ==/UserScript==

;(() => {
GM_log("Hello, world!")
})()

GM_addStyle(
body {
color: red;
}
)
`

The CSS content will be wrapped in a GM_addStyle() at the end of the userscript, so if you or your users are inspecting the code, you can see the JavaScript code from the beginning, without having to scroll over a massive CSS block.

Bonus: when writing styles for your custom DOM elements, a good practice is to use CSS Modules, which ensures that your class names will not conflict with other userscripts or the page itself. Check out webpack's guide.

TypeScript

TypeScript is supported out of the box. Just set up the TypeScript environment as usual, and you're good to go. Check out webpack's guide if you're not familiar with it.

Note that only ts-loader and babel-loader are tested. Other loaders are supposed to work, otherwise please let me know by opening an issue.

Bonus: install @types/tampermonkey to get the types for GM_*.

$3

You can place the meta object in a meta.ts as well:

`ts
// note: Meta is an alias of UserscriptMeta
import { Meta } from "webpack-monkey"

export default {
version: "1.0",
name: "Hello world",
} satisfies Meta
`

However, since this TypeScript file will be loaded with require(), you'll need to set up your environment to support it. Here's an example using ts-node:

1. Install ts-node: npm install ts-node
2. In your tsconfig.json, set esModuleInterop: true and add a ts-node object that sets module: "commonjs":

`json
{
"compilerOptions": {
"esModuleInterop": true
},

"ts-node": {
"compilerOptions": {
"module": "commonjs"
}
}
}
`

3. Do either of the following:

- Rename webpack.config.js to webpack.config.ts (maybe need some rewriting), then webpack will do the rest for you.
- Install cross-env. Then in your package.json, prepend a node flag to the webpack commands:

`diff
{
"scripts": {
- "dev": "webpack serve --mode development",
- "build": "webpack --mode production"
+ "dev": "cross-env NODE_OPTIONS=\"-r ts-node/register --no-warnings\" webpack serve --mode development",
+ "build": "cross-env NODE_OPTIONS=\"-r ts-node/register --no-warnings\" webpack --mode production"
}
}
`

$3

If you find the above method too complicated, you can also use a meta.js with JSDoc comments:

`js
/**
* @type {import("webpack-monkey").Meta}
*/
const meta = {
name: "Hello world",
version: "1.0.0",
}

module.exports = meta
`

If you're using WebStorm, the JSDoc type checking seems to be supported out of the box so you're good to go.

If you're using VSCode, some extra steps are needed.

$3

To type an external dependency, you are most likely to locally install it (npm install xxx), or if the types are not built-in, install only its types package (@types/xxx).

Then, if using the #3 or #4 method of handling external dependencies, TypeScript will automatically recognize the types when imported:

`ts
import $ from "jquery"
`

And if using #1 or #2, you need to manually declare the global variables:

`ts
///

declare global {
var $: JQueryStatic

// you can also use an inline import
var mitt: typeof import("mitt").default
}

$(".foo")
mitt()
`

Working with HMR

If you don't know what HMR is, check out webpack's introduction.

$3

webpack-monkey extends webpack's HMR API with module.hot.monkeyReload() to reload all the modules in a userscript when any of them is changed.

module.hot.monkeyReload() should be added to each userscript's entry file, and then you can clear side effects with module.hot.dispose() in any dependent modules. Example:

index.js

`js
import { foo } from "./foo"

const element = $("