webpack-userscript


A Webpack4+ plugin for userscript projects. 🙈

> The package has been renamed from webpack-tampermonkey.

Features

- Combine your userscript development with Webpack
> With powerful Webpack support, you can even package everything in your userscript, e.g. icons and json data.
- Ability to generate userscript headers
- Ability to generate both .user.js and .meta.js
> .meta.js is used for update check containing headers only.
- Properly track files in watch mode
> Including external header files and package.json.

Installation

``bash
npm i webpack-userscript -D
`

Usage

$3

Include the plugin in the webpack.config.js as the following example.

`js
const WebpackUserscript = require('webpack-userscript')

module.exports = {
plugins: [
new WebpackUserscript()
]
}
`

Examples

$3


The following example can be used in development mode with the help of webpack-dev-server.

webpack-dev-server will build the userscript in watch mode. Each time the project is built, the buildNo variable will increase by 1.

In the following configuration, a portion of the version contains the buildNo; therefore, each time there is a build, the version is also increased so as to indicate a new update available for the script engine like Tampermonkey or GreaseMonkey.

After the first time starting the webpack-dev-server, you can install the script via http://localhost:8080/.user.js (the URL is actually refered to your configuration of webpack-dev-server). Once installed, there is no need to manually reinstall the script until you stop the server. To update the script, the script engine has an update button on the GUI for you.

- webpack.config.dev.js
`js
const path = require('path')
const WebpackUserscript = require('webpack-userscript')
const dev = process.env.NODE_ENV === 'development'

module.exports = {
mode: dev ? 'development' : 'production',
entry: path.resolve(__dirname, 'src', 'index.js'),
output: {
path: path.resolve(__dirname, 'dist'),
filename: '.user.js'
},
devServer: {
contentBase: path.join(__dirname, 'dist')
},
plugins: [
new WebpackUserscript({
headers: {
version: dev ? [version]-build.[buildNo] : [version]
}
})
]
}
`

$3

Other examples can be found under the test fixture folder.

Configuration

$3

The WebpackUserscript constructor has the following signature.
`js
new WebpackUserscript(options)
`

$3

> Also see the schema of options.

`ts
type WebpackUserscriptOptions =
WPUSOptions |
HeaderFile | // shorthand for WPUSOptions.headers
HeaderProvider // shorthand for WPUSOptions.headers
`

#### WPUSOptions
`ts
interface WPUSOptions {
headers: HeaderFile | HeaderProvider | HeaderObject

/**
Output .meta.js or not
*/
metajs: boolean

/**
* Rename all .js files to .user.js files.
*/
renameExt: boolean

/**
* Prettify the header
*/
pretty: boolean
}
`

#### HeaderFile
A path to a js or json file which exports a header object or a header provider function.

`ts
type HeaderFile = string
`

#### HeaderProvider
A function that returns a header object.

`ts
type HeaderProvider = (data: DataObject) => HeaderObject
`

#### HeaderObject
A header object, whose leaves are webpack-like template strings in [] format. Available variables can be found at DataObject.

> Also see explicit-config/webpack.config.js and template-strings/webpack.config.js.

`ts
type HeaderObject = Record>
`

#### DataObject
Local variables used to interpolate the templates of a HeaderObject.

`ts
interface DataObject {
/**
* Hash of Webpack compilation
*/
hash: string

/**
* Webpack chunk hash
*/
chunkHash: string

/**
* Webpack chunk name
*/
chunkName: string

/**
* Entry file path, which may contain queries
*/
file: string

/**
* Query string
*/
query: string

/**
* Build number
*/
buildNo: number

/**
* Info from package.json
*/
name: string
version: string
description: string
author: string
homepage: string
bugs: string // URL
}
``

> Also see template-strings/webpack.config.js.