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

``bash
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.

$3

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

`typescript
// 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.

$3

- Install preact
pnpm add preact@^10.19.7

- Add the following to tsconfig.json:

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

`typescript
// 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.

`bash
xmonkey src/example-console-script.ts

for Ui Scripts


xmonkey src/example-console-script.tsx
``

---

$3

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