Registry / rollup-plugin-userscript
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default export (userscript)
✓ import userscript from 'rollup-plugin-userscript';
✗ const userscript = require('rollup-plugin-userscript');
ESM-only; package has no default CJS export.
Plugin usage in rollup.config.js
✓ import userscript from 'rollup-plugin-userscript';
export default {
plugins: [userscript(meta => meta.replace('KEY', 'value'))]
};
✗ module.exports = {
plugins: [require('rollup-plugin-userscript')(meta => {})]
};
rollup.config.js must be ESM for this plugin.
Metadata file import
✓ import './meta.js?userscript-metadata';
✗ import meta from './meta.js';
The ?userscript-metadata query suffix is required to trigger the plugin's metadata extraction.
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');
Debug
Known issues
breakingRequires Rollup ^4.0.0 and Node >=18. Not compatible with Rollup 3 or Node 16.fixUpgrade Rollup to ^4.0.0 and Node to >=18.
affects: <1.0.0 || >=1.0.0
gotchaMetadata file must be imported with ?userscript-metadata suffix; otherwise plugin does not process it.fixEnsure import path ends with ?userscript-metadata
affects: >=1.0.0
gotchaThe 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.fixReview final @grant list in output to avoid duplicates or missing grants.
affects: >=1.0.0
deprecatedThe function passed to userscript() should return the modified metadata string. Returning undefined or null will cause the metadata to be removed.fixAlways return a string from the callback.
affects: >=1.0.0
Errors
Common errors & fixes
Error: You must provide a callback function when using rollup-plugin-userscript
Calling userscript() without arguments or without a callback function.
fixInvoke as userscript(meta => { /* modify meta */ return meta; }) Error: Metadata not found. Make sure you import a file with ?userscript-metadata suffix.
Trying to use the plugin without importing any file with the special query suffix.
fixAdd import './meta.js?userscript-metadata'; to your entry point.
Audit
Dependencies
No dependency data recorded yet.