Skip to content

README.md

Latest commit

 

History

History
185 lines (127 loc) · 4.16 KB

README.md

File metadata and controls

185 lines (127 loc) · 4.16 KB

userscript-to-electron

An npm package that converts Tampermonkey or Greasemonkey userscripts into Electron-executable JavaScript.

This project tracks Tampermonkey documentation and implements a broad GM API compatibility layer.

Chinese documentation: README.zh-CN.md

Features

Full GM API Coverage

Compatibility notes:

  • Supports both classic GM_* and modern GM.* API styles.
  • Supports @grant GM and expands it to the full GM namespace bridge.
  • Supports GM.xmlHttpRequest and GM_xmlHttpRequest compatibility aliases.

Storage APIs:

  • GM_getValue, GM_setValue, GM_deleteValue, GM_listValues
  • GM_setValues, GM_getValues, GM_deleteValues
  • GM_addValueChangeListener, GM_removeValueChangeListener

Network APIs:

  • GM_xmlhttpRequest
  • GM_download
  • GM_webRequest (experimental)

UI APIs:

  • GM_notification
  • GM_openInTab
  • GM_registerMenuCommand, GM_unregisterMenuCommand

DOM and style APIs:

  • GM_addElement
  • GM_addStyle

Resources and clipboard APIs:

  • GM_getResourceText, GM_getResourceURL
  • GM_setClipboard

Tab and info APIs:

  • GM_getTab, GM_saveTab, GM_getTabs
  • GM_info
  • GM_log

Cookie and audio APIs:

  • GM_cookie.list, GM_cookie.set, GM_cookie.delete
  • GM_audio.setMute, GM_audio.getState
  • GM_audio.addStateChangeListener, GM_audio.removeStateChangeListener

Window globals:

  • unsafeWindow
  • window.close, window.focus
  • window.onurlchange

Metadata Header Support

Supports common Tampermonkey headers including:

  • @name, @namespace, @version, @description, @author
  • @match, @include, @exclude, @connect
  • @grant, @require, @resource
  • @run-at, @run-in, @sandbox
  • @updateURL, @downloadURL, @supportURL, @homepage
  • @noframes, @unwrap, @tag, @antifeature
  • I18n variants like @name:zh-CN, @description:en

Installation

npm install userscript-to-electron

Quick Start

import UserscriptConverter from 'userscript-to-electron';
import fs from 'fs';

const converter = new UserscriptConverter({
  dataDir: './userscript-data'
});

const scriptContent = fs.readFileSync('my-script.user.js', 'utf-8');
const result = converter.convert(scriptContent);

console.log(result.metadata.name);
converter.save(result, 'output.js');

Electron Integration Example

const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('path');
const UserscriptConverter = require('userscript-to-electron');

const converter = new UserscriptConverter({
  dataDir: path.join(app.getPath('userData'), 'userscripts')
});

ipcMain.handle('userscript:run', async (_event, scriptPath) => {
  const result = converter.convertFile(scriptPath);
  const win = BrowserWindow.getFocusedWindow();
  if (win) {
    await win.webContents.executeJavaScript(result.code);
  }
  return result.metadata;
});

API Overview

UserscriptConverter

new UserscriptConverter(options?: ConvertOptions)

Methods:

  • convert(scriptContent: string): ConvertResult
  • convertFile(filePath: string): ConvertResult
  • save(result: ConvertResult, outputPath: string): void

ConvertResult:

interface ConvertResult {
  code: string;
  metadata: UserscriptMetadata;
  sourceMap?: string;
}

MetadataParser

MetadataParser.parse(scriptContent: string): UserscriptMetadata

GMPolyfill

new GMPolyfill(options?: GMPolyfillOptions)
generatePolyfill(grants: string[]): string

Persistence Behavior

  • GM value storage is persisted to ${dataDir}/__gm_storage.json.
  • Tab state is persisted to ${dataDir}/__gm_tabs.json.
  • Downloads are saved to ${dataDir}/downloads/.

Known Limitations

  • DOM-dependent userscripts should run in an Electron renderer process or with jsdom.
  • Some browser-specific cookie and tab behavior may differ in Electron.
  • GM_webRequest behavior depends on integration context and is currently experimental.

Development

npm run build
npm run dev
npm test

License

MIT. See LICENSE.

References