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

npm i webpack-userscript -D

Usage

webpack.config.js

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

const WebpackUserscript = require('webpack-userscript')

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

Examples

Hot Development

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/<project-name>.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

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: '<project-name>.user.js'
  },
  devServer: {
    contentBase: path.join(__dirname, 'dist')
  },
  plugins: [
    new WebpackUserscript({
      headers: {
        version: dev ? `[version]-build.[buildNo]` : `[version]`
      }
    })
  ]
}

Other

Other examples can be found under the test fixture folder.

Configuration

WebpackUserscript

The WebpackUserscript constructor has the following signature.

new WebpackUserscript(options)

options

Also see the schema of options.

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

WPUSOptions

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.

type HeaderFile = string

HeaderProvider

A function that returns a header object.

type HeaderProvider = (data: DataObject) => HeaderObject

HeaderObject

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

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

type HeaderObject = Record<string, string | Array<string>>

DataObject

Local variables used to interpolate the templates of a HeaderObject.

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.