2.3.2 • Public • Published


Build Status JavaScript Style Guide npm Gitmoji

A Webpack4+ plugin for userscript projects. 🙈

The package has been renamed from webpack-tampermonkey.


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


npm i webpack-userscript -D



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

const WebpackUserscript = require('webpack-userscript')

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


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 examples can be found under the test fixture folder.



The WebpackUserscript constructor has the following signature.

new WebpackUserscript(options)


Also see the schema of options.

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


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


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

type HeaderFile = string


A function that returns a header object.

type HeaderProvider = (data: DataObject) => 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>>


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.


npm i @0xdv/webpack-userscript

DownloadsWeekly Downloads






Unpacked Size

16.5 kB

Total Files


Last publish


  • 0xdv