XMonkey TypeScript Lib

Tool for creating userscripts with typescript.

With XMonkey there are two ways of creating userscripts:

• Console Scripts
• UI Scripts

Project with both examples here

Install

npm i -D @lukaskj/xmonkey
# or
pnpm i -D @lukaskj/xmonkey

Console Scripts

A "Console Script" is a simple script that will run in the background. See a console script example here.

Creating an Console Script

• Create an class as entrypoint for your script. Only entry class must be the default export.
• The class must be decorated with the @ConsoleScript() decorator and be populated with the userscript metadata. See userscript metadata guide.
• Also, the class must implement the ConsoleScript interface.

// ConsoleScript decorator
@ConsoleScript({
  "@name": "Youtube Adblocker",
  "@namespace": "scripts",
  "@version": "1.0",
  "@description": "Youtube Custom Adblocker",
  "@author": "Lukas",
  "@match": "https://www.youtube.com/*",
})
export default class implements IConsoleScript {
  // Implements IConsoleScript interface
  async execute() {}
}

Ui Scripts

"Ui Script" is an userscript with an prebuilt UI. It is created using preact and have scss support out of the box. See the example code here.

Creating an Ui Script

• Install preact pnpm add preact@^10.19.7

• Add the following to tsconfig.json:

{
  "compilerOptions": {
    ...
    "jsx": "react-jsx", // this
    "jsxImportSource": "preact", // this
    ...
  }
}

• Create an class as entrypoint for your script. Only entry class must be the default export.
• The class must be decorated with the @UiScript() decorator and be populated with the userscript metadata. See userscript metadata guide.
• Also, the class must implement the UiScript interface.

// UiScript decorator
@UiScript({
  "@name": "WhatsApp Example",
  "@namespace": "example",
  "@match": "https://web.whatsapp.com/",
  "@version": "1.0",
  "@author": "-",
  "@description": "-",
  "@grant": ["GM.addStyle"],
})
export default class WhatsAppExample implements IUiScript {
  // Implements IUiScript interface
  title: string = "Example";

  async render() {}
}

whatsapp-example.webm

Building

To build the class to an working userscript, run the xmonkey binary with the script as argument.

xmonkey src/example-console-script.ts

#  for Ui Scripts
xmonkey src/example-console-script.tsx

Known bugs

• The UiScript render function has a bug that it cannot have any hook or it won't work. The workaround is to return a single component in the UiScript that this component can use any preact hook as usual. See example here.