{"id":28460,"library":"webpack-userscript","title":"Webpack Userscript Plugin","description":"A webpack plugin for building userscript projects targeting Tampermonkey, Greasemonkey, Violentmonkey, and similar userscript engines. Current stable version is 3.2.3 (Dec 2024), with active maintenance on GitHub. The plugin automatically generates userscript headers from metadata, produces .meta.js files for update checks, and creates proxy scripts to avoid caching during development. Key differentiators: full TypeScript support since v3, multi-entry support, header interpolation, and integrated hot-reload workflow with webpack-dev-server. Requires webpack 5 as a peer dependency.","status":"active","version":"3.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/momocow/webpack-userscript","tags":["javascript","webpack","userscript","tampermonkey","greasemonkey","typescript"],"install":[{"cmd":"npm install webpack-userscript","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-userscript","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-userscript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin requires webpack 5 to function.","package":"webpack","optional":false}],"imports":[{"note":"v3 renamed the plugin from WebpackUserscript to UserscriptPlugin. Old name no longer works.","wrong":"const WebpackUserscript = require('webpack-userscript');","symbol":"UserscriptPlugin","correct":"const { UserscriptPlugin } = require('webpack-userscript');"},{"note":"ESM named export is supported since v3 (TypeScript rewrite). Default export does not exist.","wrong":"import UserscriptPlugin from 'webpack-userscript';","symbol":"UserscriptPlugin","correct":"import { UserscriptPlugin } from 'webpack-userscript';"},{"note":"UserscriptOptions is a type export. Use `import type` in TypeScript to avoid runtime overhead.","wrong":"import { UserscriptOptions } from 'webpack-userscript';","symbol":"UserscriptOptions","correct":"import type { UserscriptOptions } from 'webpack-userscript';"}],"quickstart":{"code":"const path = require('path');\nconst { UserscriptPlugin } = require('webpack-userscript');\n\nmodule.exports = {\n  entry: './src/index.user.js',\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    filename: '[name].js',\n  },\n  plugins: [\n    new UserscriptPlugin({\n      headers: {\n        name: 'My Userscript',\n        namespace: 'https://example.com',\n        version: '1.0.0',\n        description: 'A sample userscript built with webpack',\n        author: 'You',\n        match: 'https://example.com/*',\n        grant: 'none',\n      },\n      metajs: true,\n      proxyScript: {\n        baseURL: 'http://localhost:8080',\n      },\n    }),\n  ],\n  mode: 'development',\n};","lang":"javascript","description":"Configures webpack-userscript with headers, metadata generation, and proxy script for hot development with webpack-dev-server."},"warnings":[{"fix":"Change `const WebpackUserscript = require('webpack-userscript'); new WebpackUserscript(...)` to `const { UserscriptPlugin } = require('webpack-userscript'); new UserscriptPlugin(...)`.","message":"In v3.0.0, the plugin constructor was renamed from `WebpackUserscript` to `UserscriptPlugin`. Old code using `new WebpackUserscript()` will throw a ReferenceError.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use `const { UserscriptPlugin } = require('webpack-userscript');` instead of `const UserscriptPlugin = require('webpack-userscript');`.","message":"In v3.0.0, the plugin was rewritten in TypeScript. CommonJS require of the default export no longer works; use named export `UserscriptPlugin`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Move `headers.proxyScript` to the top-level `proxyScript` option in `new UserscriptPlugin({ proxyScript: { ... } })`.","message":"The `headers.proxyScript` option was deprecated in v3.2.0; use `proxyScript` directly in the plugin options instead.","severity":"deprecated","affected_versions":">=3.2.0 <4.0.0"},{"fix":"Ensure the output .meta.js file is served at the URL specified by `@updateURL` header. Use `headers.updateURL` to set it correctly.","message":"When using `metajs: true`, the generated .meta.js file does not include the script body. Tampermonkey may fail update checks if the script is not hosted at the expected URL.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Rename your entry file to end with `.user.js`, e.g., `./src/index.user.js`.","message":"If the entry file does not end with `.user.js`, the plugin will not prepend headers. Headers are only added to entry points whose names match `*.user.js`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Upgrade to v3.2.3 which fixes the bug. Alternatively, ensure at least one chunk is named.","cause":"In v3.2.3 and earlier, the interpolater fails when chunk name is empty string.","error":"TypeError: Cannot read properties of undefined (reading 'chunkName')"},{"fix":"Use `const { UserscriptPlugin } = require('webpack-userscript')` and instantiate with `new UserscriptPlugin({...})`.","cause":"Using `WebpackUserscript` (old constructor) instead of `UserscriptPlugin` in v3.","error":"Error: Invalid configuration object. Webpack has been initialized using a configuration object that does not match the API schema."},{"fix":"Ensure your entry file has a `.js` or `.user.js` extension and is valid JavaScript/TypeScript.","cause":"The entry file is not recognized as valid JavaScript (e.g., missing `.js` extension).","error":"Module parse failed: Unexpected token (1:0) - You may need an appropriate loader to handle this file type."},{"fix":"Run `npm install webpack-userscript --save-dev` or `yarn add webpack-userscript --dev`.","cause":"The package is not installed or node_modules is missing.","error":"Cannot find module 'webpack-userscript'"},{"fix":"Use `import { UserscriptPlugin } from 'webpack-userscript'` (named import) instead of default import.","cause":"Importing the default export instead of named export in ESM context.","error":"UserscriptPlugin is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}