to-userscript

A powerful CLI for converting browser extensions into standalone userscripts.

Examples:

What is this?

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.

Features

• 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.

Installation

to-userscript requires Node.js v16 or higher.

You can install it globally using your preferred package manager:

# npm
npm install -g to-userscript

# pnpm
pnpm add -g to-userscript

# bun
bun install -g to-userscript

Alternatively, you can run it directly without a global installation using npx, pnpm dlx, or bunx.

Polyfill status:

Supported APIs

• chrome.storage
  • local (backed by GM_* storage or IndexedDB)
  • sync (maps to local storage)
  • managed (shimmed; read-only and empty)
  • onChanged
• chrome.runtime
  • sendMessage/onMessage (in-page/iframe communication only)
  • getURL (for bundled assets only)
  • getManifest
  • openOptionsPage: Opens options popup
• chrome.tabs
  • create (maps to GM_openInTab or window.open)
  • query (shimmed; returns current tab only)
  • sendMessage (shimmed; redirects to runtime.sendMessage)
• chrome.i18n
  • getMessage
  • getUILanguage
• chrome.contextMenus (emulated via GM_registerMenuCommand; limited functionality)
• chrome.permissions
  • request/contains/getAll (shimmed)
• chrome.notifications (maps to native Web Notifications API)
• chrome.cookies
  • get
  • getAll
  • set
  • remove
  • getAllCookieStores
  • getPartitionKey

Planned APIs

• chrome.browserAction
• chrome.tabs.insertCSS
• chrome.tabs.reload
• chrome.tabs.onActivated
• chrome.scripting.insertCSS
• chrome.scripting.executeScript
• chrome.identity:
  • getAuthToken
  • getProfileUserInfo
  • clearAllCachedAuthTokens
• chrome.runtime.onMessageExternal: Shim
• chrome.runtime.sendMessageExternal: Shim
• chrome.webNavigation
• (partial) chrome.permissions:
  • Get listeners working
  • Removing permission for an origin should persist this change and not match the script on it
• (mostly implemented) chrome.storage: Proper listeners
• chrome.action
  • onClicked.addListener: Add menu item for click
• Keyboard shortcuts (from manifest)
• background.page support

General tasks

• Make vanilla target better and more capable
• API bindings: import makeUserscript from 'to-userscript';
  • Vite plugin
  • Take dir and output
• Create reusable listener logic for supporting callbacks/promises

Usage & Commands

convert

Converts an extension into a userscript. This is the primary command.

Syntax: to-userscript convert <source> [options]

<source> Types:

• URL: A Chrome Web Store or Firefox Add-ons URL.
• Direct URL: A direct link to a .crx, .xpi, or .zip file.
• Local Directory: A path to an unpacked extension directory.
• Local Archive: A path to a local .crx, .xpi, or .zip file.

Examples

1. Convert from the Chrome Web Store with minification:

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:

to-userscript convert ./my-unpacked-extension/ -o my-script.user.js --locale fr

3. Convert a downloaded XPI to vanilla JS (using pnpm dlx):

pnpm dlx to-userscript convert ./my-addon.xpi --target vanilla -o my-addon.js

download

Syntax: to-userscript download <source>

Example

# 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

require

Generates a metadata block to @require another local userscript.

Syntax: to-userscript require <path-to-userscript>

Example

# Generate a main script that @requires the converted script
to-userscript require ./material-design-fileicons.user.js | pbcopy

How It Works

For a detailed explanation of the internal conversion pipeline, see the Architecture Guide note: AI generated but proofread.

What it can (and can't/shouldn't) convert

• 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

Troubleshooting & Advanced Usage

Content Security Policy (CSP) Issues

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".

Resulting userscript output format:

// ==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.
})();

Contributing

I welcome contributions! Especially to implement new chrome apis, or fix bugs.