Skip to content
A Webpack4+ plugin for userscript projects. πŸ™ˆ
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib ✨ Add new variable, build number. Apr 1, 2019
test βœ… Add a test for build number. Apr 1, 2019
.eslintignore πŸ”§ Update .eslintignore. Mar 28, 2019
.eslintrc.json πŸŽ‰ Init v2. Mar 28, 2019
.gitignore WIP: tm.js Feb 2, 2018
.releaserc.json
.travis.yml πŸ‘· Add semantic release stage. Jul 11, 2019
LICENSE
README.md πŸ“ Fix typo. (#11) Apr 10, 2019
package-lock.json
package.json πŸ”– v2.3.1 [skip ci] Jul 11, 2019

README.md

webpack-userscript

Build Status JavaScript Style Guide npm Gitmoji

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

  /**
   * 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 HeaderFile = 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.

You can’t perform that action at this time.