Converts simple browser extensions to userscripts
npm install to-userscript
Demo
##### 2x Speed (conversion takes 4s total normal speed, incl. downloading)
https://github.com/user-attachments/assets/e0adebcb-843d-4b04-830b-0b6ef5344652
##### Demo but normal speed
https://github.com/user-attachments/assets/874dc6fd-ad6c-4e07-9d27-da1184f3036d
A powerful CLI for converting browser extensions into standalone userscripts.
| Extension | View output code | Install |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Material Design File Icons | View | Install |
| JSON Formatter | View | Install |
| Modern for Wikipedia | View | Install |
| Return Dislikes | View | Install |
| Web Search Navigator | View | Install |
| uBlacklist | View | Install |
| Iridium | View | Install |
| Modern for Hackernews | View | Install |
to-userscript converts browser extensions into portable userscripts. It takes an extension from the Chrome or Firefox store, a local directory, or a zip/xpi, and creates a single .user.js file that can be run in any userscript manager. This allows you to use, or modify extensions on browsers or platforms that might not natively support them.
- Convert from Chrome Web Store, Firefox Add-ons site, direct URLs, local directories, or archive files (.crx, .xpi, .zip).
- Replaces WebExtension APIs (chrome.storage, chrome.runtime, chrome.tabs, etc.) with userscript-compatible equivalents (GM_* functions, IndexedDB, and custom event buses).
- Asset inlining: Embeds CSS, images, fonts, and other resources into the userscript (replacing runtime.getURL and options/popup pages).
- Renders extension popup and options pages within an embedded modal (after inlining all asset links), preserving most UI functionality.
- Emulates the background script environment, allowing persistent logic to run as intended and two way messaging.
- Respects _locales directories and uses the specified or default locale for manifest, text, etc.
- Optional minification (terser) and code formatting (prettier) for the final output.
to-userscript requires Node.js v16 or higher.
You can install it globally using your preferred package manager:
``bash`npm
npm install -g to-userscript
`bash`pnpm
pnpm add -g to-userscript
`bash`bun
bun install -g to-userscript
Alternatively, you can run it directly without a global installation using npx, pnpm dlx, or bunx.
- [x] chrome.storagelocal
- [x] (backed by GM_* storage or IndexedDB)sync
- [x] (maps to local storage)managed
- [x] (shimmed; read-only and empty)onChanged
- [x] chrome.runtime
- [x] sendMessage
- [x] /onMessage (in-page/iframe communication only)getURL
- [x] (for bundled assets only)getManifest
- [x] openOptionsPage
- [x] : Opens options popupchrome.tabs
- [x] create
- [x] (maps to GM_openInTab or window.open)query
- [x] (shimmed; returns current tab only)sendMessage
- [x] (shimmed; redirects to runtime.sendMessage)chrome.i18n
- [x] getMessage
- [x] getUILanguage
- [x] chrome.contextMenus
- [x] (emulated via GM_registerMenuCommand; limited functionality)chrome.permissions
- [x] request
- [x] /contains/getAll (shimmed)chrome.notifications
- [x] (maps to native Web Notifications API)chrome.cookies
- [x] get
- [x] getAll
- [x] set
- [x] remove
- [x] getAllCookieStores
- [x] getPartitionKey
- [x]
- [ ] chrome.browserActionchrome.tabs.insertCSS
- [ ] chrome.tabs.reload
- [ ] chrome.tabs.onActivated
- [ ] chrome.scripting.insertCSS
- [ ] chrome.scripting.executeScript
- [ ] chrome.identity
- [ ] :getAuthToken
- [ ] getProfileUserInfo
- [ ] clearAllCachedAuthTokens
- [ ] chrome.runtime.onMessageExternal
- [ ] : Shimchrome.runtime.sendMessageExternal
- [ ] : Shimchrome.webNavigation
- [ ] chrome.permissions
- [ ] (partial) :chrome.storage
- Get listeners working
- Removing permission for an origin should persist this change and not match the script on it
- [ ] (mostly implemented) : Proper listenerschrome.action
- [ ] onClicked.addListener
- : Add menu item for clickbackground.page
- [ ] Keyboard shortcuts (from manifest)
- [ ] support
- [ ] Make vanilla target better and more capableimport makeUserscript from 'to-userscript';
- [ ] API bindings:
- [ ] Vite plugin
- [ ] Take dir and output
- [ ] Create reusable listener logic for supporting callbacks/promises
Converts an extension into a userscript. This is the primary command.
Syntax: to-userscript convert
Types:
- URL: A Chrome Web Store or Firefox Add-ons URL.
- Direct URL: A direct link to a .crx, .xpi, or .zip file..crx
- Local Directory: A path to an unpacked extension directory.
- Local Archive: A path to a local , .xpi, or .zip file.
| Option | Alias | Description |
| :---------------- | :---- | :-------------------------------------------------------------------------------------- |
| --output | -o | Specify the output .user.js file path. |--target
| | -t | Set build target. userscript (default) includes metadata, vanilla outputs plain JS. |--minify
| | | Minify the JavaScript output using terser. |--beautify
| | | Beautify the JavaScript output using prettier. |--locale
| | -l | Preferred locale for name/description (e.g., en, fr, de). |--ignore-assets
| | | Asset extensions to ignore during inlining (e.g., mp4,webm,ttf). |--force
| | -f | Overwrite the output file if it exists. |--keep-temp
| | | Keep temporary files for debugging purposes. |
#### Examples
1. Convert from the Chrome Web Store with minification:
`bash`
to-userscript convert "https://chromewebstore.google.com/detail/modern-for-wikipedia/emdkdnnopdnajipoapepbeeiemahbjcn?hl=en" -o modern-wikipedia.user.js --minify
2. Convert a local directory with French localization:
`bash`
to-userscript convert ./my-unpacked-extension/ -o my-script.user.js --locale fr
3. Convert a downloaded XPI to vanilla JS (using pnpm dlx):
`bash`
pnpm dlx to-userscript convert ./my-addon.xpi --target vanilla -o my-addon.js
Syntax: to-userscript download
#### Example
`bash`Using bunx to download Material Design File Icons
bunx to-userscript download "https://chromewebstore.google.com/detail/material-icons-for-github/bggfcpfjbdkhfhfmkjpbhnkhnpjjeomc/" -o ublock-origin.xpi
Generates a metadata block to @require another local userscript.
Syntax: to-userscript require
#### Example
`bash`Generate a main script that @requires the converted script
to-userscript require ./material-design-fileicons.user.js | pbcopy
For a detailed explanation of the internal conversion pipeline, see the Architecture Guide _note: AI generated but proofread_.
- Extensions intended for one site should work well, extensions meant to apply some sort of enhancement to the entire web might not work quite as well
- Extensions where the functionality is primarily browser API based (even though these are polyfilled most of the time it's not something useful for the functionality)
- E.g: An adblocker is a bad use case for this, as is something like a custom new tab page or similar, whereas an extension like "YouTube auto HD" might work really well
Some websites have strict CSP rules that can prevent converted userscripts from functioning correctly (blocking data urls and blobs). If your script isn't working as expected on a specific site, you may need to adjust Tampermonkey's security settings.
1. In Tampermonkey, go to the Dashboard.
2. Click the Settings tab.
3. Change Config mode from "Beginner" to "Advanced".
4. Scroll down to the Security section.
5. For the option Modify existing Content Security headers, select "Remove entirely".
`js
// ==UserScript==
// ... Metadata Block ...
// ==/UserScript==
(function () {
// IIFE for scope isolation
"use strict";
// 1. UNIFIED POLYFILL is defined here
// - messaging.template.js -> createEventBus, createRuntime
// - abstractionLayer.*.template.js -> _storageSet, _fetch, etc.
// - assetsGenerator code -> EXTENSION_ASSETS_MAP, _createAssetUrl
// - polyfill.template.js -> buildPolyfill() which creates chrome.*
// 2. BACKGROUND SCRIPT ENVIRONMENT is defined and executed
// - Runs all background scripts inside the polyfill's scope.
// - This happens immediately on script start.
// 3. ORCHESTRATION LOGIC is defined and executed
// - Checks if location.href matches a content_script pattern.
// - If it matches:
// - Calls executeAllScripts().``
// - This function injects CSS and runs JS in phases:
// - document-start
// - document-end
// - document-idle
// - Registers GM_registerMenuCommand for options/popup pages.
// - Options/Popup pages are rendered in a modal with an iframe.
// - The iframe's content is populated with the inlined HTML and
// a specialized 'postmessage' version of the polyfill.
})();
I welcome contributions! Especially to implement new chrome apis, or fix bugs.