rollup-plugin-userscript

1.1.0 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error: You must provide a callback function when using rollup-plugin-userscript ↓

cause Calling userscript() without arguments or without a callback function.

fix

Invoke as userscript(meta => { /* modify meta */ return meta; })

error Error: Metadata not found. Make sure you import a file with ?userscript-metadata suffix. ↓

cause Trying to use the plugin without importing any file with the special query suffix.

fix

Add import './meta.js?userscript-metadata'; to your entry point.

Warnings

breaking Requires Rollup ^4.0.0 and Node >=18. Not compatible with Rollup 3 or Node 16. ↓

fix Upgrade Rollup to ^4.0.0 and Node to >=18.

gotcha Metadata file must be imported with ?userscript-metadata suffix; otherwise plugin does not process it. ↓

fix Ensure import path ends with ?userscript-metadata

gotcha 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. ↓

fix Review final @grant list in output to avoid duplicates or missing grants.

deprecated The function passed to userscript() should return the modified metadata string. Returning undefined or null will cause the metadata to be removed. ↓

fix Always return a string from the callback.

Install

npm install rollup-plugin-userscript

yarn add rollup-plugin-userscript

pnpm add rollup-plugin-userscript

Imports

default export (userscript)

wrong

const userscript = require('rollup-plugin-userscript');

correct

import userscript from 'rollup-plugin-userscript';

ESM-only; package has no default CJS export.

Plugin usage in rollup.config.js

wrong

module.exports = {
  plugins: [require('rollup-plugin-userscript')(meta => {})]
};

correct

import userscript from 'rollup-plugin-userscript';
export default {
  plugins: [userscript(meta => meta.replace('KEY', 'value'))]
};

rollup.config.js must be ESM for this plugin.

Metadata file import
wrong
```
import meta from './meta.js';
```
correct
```
import './meta.js?userscript-metadata';
```
The ?userscript-metadata query suffix is required to trigger the plugin's metadata extraction.

Quickstart

Configures Rollup to bundle a userscript, uses the plugin to replace placeholders in metadata and automatically add @grant for GM_setClipboard.

// rollup.config.mjs
import userscript from 'rollup-plugin-userscript';
import { defineConfig } from 'rollup';

export default defineConfig({
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.user.js',
    format: 'iife'
  },
  plugins: [
    userscript(meta => {
      const pkg = { author: 'John Doe' };
      return meta.replace('process.env.AUTHOR', pkg.author);
    })
  ]
});

// src/index.js
import './meta.js?userscript-metadata';
// Use GM_* functions
GM_setClipboard('Hello');