{"id":22276,"library":"rollup-plugin-userscript","title":"rollup-plugin-userscript","description":"Rollup plugin that automatically parses userscript metadata blocks and injects @grant declarations for GM_* functions used in the code. Version 1.1.0 requires Rollup ^4.0.0 and Node >=18. Differentiates from manual grant management by analyzing the bundle at compile time and adding only needed grants. Maintained by Violentmonkey project; follows Tampermonkey/Violentmonkey metadata conventions.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/violentmonkey/rollup-plugin-userscript","tags":["javascript","rollup","userscript","typescript"],"install":[{"cmd":"npm install rollup-plugin-userscript","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-userscript","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-userscript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only; package has no default CJS export.","wrong":"const userscript = require('rollup-plugin-userscript');","symbol":"default export (userscript)","correct":"import userscript from 'rollup-plugin-userscript';"},{"note":"rollup.config.js must be ESM for this plugin.","wrong":"module.exports = {\n  plugins: [require('rollup-plugin-userscript')(meta => {})]\n};","symbol":"Plugin usage in rollup.config.js","correct":"import userscript from 'rollup-plugin-userscript';\nexport default {\n  plugins: [userscript(meta => meta.replace('KEY', 'value'))]\n};"},{"note":"The ?userscript-metadata query suffix is required to trigger the plugin's metadata extraction.","wrong":"import meta from './meta.js';","symbol":"Metadata file import","correct":"import './meta.js?userscript-metadata';"}],"quickstart":{"code":"// rollup.config.mjs\nimport userscript from 'rollup-plugin-userscript';\nimport { defineConfig } from 'rollup';\n\nexport default defineConfig({\n  input: 'src/index.js',\n  output: {\n    file: 'dist/bundle.user.js',\n    format: 'iife'\n  },\n  plugins: [\n    userscript(meta => {\n      const pkg = { author: 'John Doe' };\n      return meta.replace('process.env.AUTHOR', pkg.author);\n    })\n  ]\n});\n\n// src/index.js\nimport './meta.js?userscript-metadata';\n// Use GM_* functions\nGM_setClipboard('Hello');\n","lang":"javascript","description":"Configures Rollup to bundle a userscript, uses the plugin to replace placeholders in metadata and automatically add @grant for GM_setClipboard."},"warnings":[{"fix":"Upgrade Rollup to ^4.0.0 and Node to >=18.","message":"Requires Rollup ^4.0.0 and Node >=18. Not compatible with Rollup 3 or Node 16.","severity":"breaking","affected_versions":"<1.0.0 || >=1.0.0"},{"fix":"Ensure import path ends with ?userscript-metadata","message":"Metadata file must be imported with ?userscript-metadata suffix; otherwise plugin does not process it.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review final @grant list in output to avoid duplicates or missing grants.","message":"The plugin only injects @grant for GM_* functions used in the bundle. Custom @grant entries in the metadata are preserved but may conflict with auto-injected ones.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always return a string from the callback.","message":"The function passed to userscript() should return the modified metadata string. Returning undefined or null will cause the metadata to be removed.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Invoke as userscript(meta => { /* modify meta */ return meta; })","cause":"Calling userscript() without arguments or without a callback function.","error":"Error: You must provide a callback function when using rollup-plugin-userscript"},{"fix":"Add import './meta.js?userscript-metadata'; to your entry point.","cause":"Trying to use the plugin without importing any file with the special query suffix.","error":"Error: Metadata not found. Make sure you import a file with ?userscript-metadata suffix."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}