Plugins

Plugins add features to The Hub: slash commands, buttons next to the message box, decorations on messages, settings panels, extra themes. They are plain JavaScript (plus optional CSS), with no build step.

Everyone chooses which plugins they use, in Settings → Plugins. Plugins come from the community shop: when yours is ready, send it.

Security#

Every plugin runs in its own sandbox: it can't touch The Hub's page, the person's session or their stored data, and it can't reach the internet unless it asks. Reading messages, sending them, acting as the person through the API and using the internet are permissions you list in plugin.json; each person sees them and agrees before your plugin turns on. HTML and CSS you show are cleaned first. Ask for as little as you can: plugins that ask for more than they need, collect data, or hide what they do are refused from the shop, and anyone can report a plugin.

Try yours as you build it#

You don't need a server. In The Hub, Settings → Plugins → Developer mode → Load a plugin folder runs a plugin from a folder on your computer, in your own browser only, until you reload. Nothing is uploaded. Load it again after you change a file.

A plugin folder looks like this:

my-plugin/
    plugin.json     what it is (required)
    plugin.js       its code (required)
    plugin.css      its styles (optional)

plugin.json#

{
    "id": "dice",
    "name": "Dice roller",
    "version": "1.0.0",
    "author": "The Hub",
    "description": "Roll dice in chat with /roll 2d6, or roll a d20 with the button next to the message box.",
    "main": "plugin.js",
    "styles": "plugin.css",
    "default": false
}

A manifest that breaks any rule is ignored as a whole.

Writing a plugin#

A plugin's script calls TheHub.plugin() with its id and a setup function. Setup runs each time the plugin is turned on, and receives the api object:

TheHub.plugin('hello', api => {
    api.commands.register({
        name: 'hello',
        description: 'Say hello to everyone',
        run: () => `👋 Hello from ${api.me().display_name}!`,
    });
    api.ui.toast('Hello plugin is on');
});

The rules of the road:

• Call TheHub.plugin() right away, at the top level of your main script, with the id from your plugin.json. Calls made later (after a fetch, in a timer) or with another plugin's id are refused.
• Do your work inside setup. Code outside it runs only once per page load, even if the plugin is turned off and on again.
• Everything you add through api is removed for you when the plugin is turned off: commands, buttons, event listeners, decorators, styles, themes, its settings panel and any modal it opened. Messages are redrawn without your decorations.
• If you set up anything yourself (a setInterval, a listener on window, elements you added outside the places api gives you), return a cleanup function from setup. It runs when the plugin is turned off. Setup may also be async, as long as TheHub.plugin() itself is called right away.
• Escape text before you put it in HTML. Messages, names and topics come from other people. Use api.util.esc(text), or set textContent instead of innerHTML.
• Prefix your CSS classes (for example dice-…) or scope rules to [data-plugin="<id>"].

Every call into your code is guarded: if it throws, the error is shown in your plugin's entry in Settings → Plugins and logged to the console, and the rest of The Hub (and other plugins) carry on. If setup throws, everything it had registered is removed and the plugin stays off until it's turned on again.

API reference#

Basics#

Events: api.on(event, fn) → off()#

const off = api.on('message', msg => {
    if (!msg.mine && /good night/i.test(msg.content)) api.ui.toast(`${msg.author.display_name} is off to bed`);
});

Everything a handler receives is a copy: changing it changes nothing in The Hub.

Message objects look like this:

{
    id: 42, channel_id: 7,
    author: { id, username, display_name, avatar, color, badge, name_style, … },
    content: 'hi <@&3>',    // raw text with Markdown; role mentions are <@&roleId>
    attachments: [{ url, name, size, type, … }],
    sticker: null,          // or { name, url, … }
    reply: null,            // or { id, author, content, … }
    reactions: [], pinned: false,
    created_at: 1759660000000, edited_at: null,
    mine: true,             // added for plugins: you sent it
    pending: true,          // decorators only: your own message is still being sent ('message' events come after it's sent)
}

If your 'message' handler sends messages, ignore msg.mine ones, or you'll answer yourself forever.

Slash commands: api.commands.register({ name, description, run }) → off()#

api.commands.register({
    name: 'flip',                        // the user types /flip; a-z, 0-9 and -, up to 32 characters
    description: 'Flip a coin',          // shown in the suggestions and in Settings → Plugins
    run(args, ctx) {                     // args: the text after the name; ctx: { name, channel }
        return Math.random() < .5 ? '🪙 Heads' : '🪙 Tails';
    },
});

• Return a string to send it as the person's message in the open channel.
• Return nothing when you've handled it yourself: nothing is sent.
• Return false when you couldn't use what was typed (bad arguments, say): nothing is sent and the person's text goes back in the message box so they can fix it.
• run may be async. If it throws, the person sees an error and gets their text back in the message box.
• Commands can't replace The Hub's built-in ones (/shrug, /tableflip, /unflip, /lenny, /disapprove), and the first plugin to register a name keeps it.
• While someone types / and the start of a name, matching plugin commands are suggested above the message box.

Message decorations: api.messages.decorate(fn) → off()#

fn(el, msg) runs for every message drawn in the chat, each time the list is redrawn. el is the message's element (.msg, with the text in .msg-content); msg is a message object. Change only el and what's inside it.

api.messages.decorate((el, msg) => {
    if (!msg.content.includes('#todo')) return;
    el.querySelector('.msg-content')?.insertAdjacentHTML('beforeend',
        `<span class="todo-tag" title="${api.util.esc(msg.author.display_name)}'s to-do">✔ to-do</span>`);
});

Interface#

Styles: api.styles.add(cssText) → off()#

Adds a <style> element. For a stylesheet file, use "styles" in plugin.json instead. Use The Hub's colour tokens so you match every theme: var(--text), var(--muted), var(--s3), var(--line), var(--air) (the accent), var(--air-soft), var(--rose)… (the full list is at the top of assets/app.css).

Storage: api.storage.get(key, fallback), api.storage.set(key, value)#

Small JSON values saved in this browser, separately for each plugin (in localStorage, under voicelink.plugin.<id>). set(key, undefined) removes a key. Nothing is shared between devices or people.

The person and the conversation#

Themes: api.themes.register(theme) → off() or null#

Adds a theme people can pick in Settings → Appearance. It's removed when the plugin is turned off, and anyone using it goes back to its base theme.

api.themes.register({
    id: 'dusk',                   // a-z, 0-9 and -, up to 40 characters
    name: 'Dusk',                 // up to 40 characters
    base: 'night',                // 'night', 'day', 'mono' or 'mono-light': what it starts from
    vars: { '--bg': '#1f1420', '--s1': '#2a1a29', '--air': '#ff9e5e' },   // colour tokens to override
    css: '',                      // optional extra CSS
    author: 'You', description: 'Plum dusk with a warm orange glow',
});

Only The Hub's theme colour tokens can be set in vars, with plain colour values. Returns null (and shows why in Settings → Plugins) if the theme isn't valid or this Hub can't add themes. See plugins/dusk-theme/.

Utilities#

Debugging#

• Settings → Plugins shows each plugin's last errors under its entry: a script that couldn't load (missing file), a syntax error, a setup that threw, or an error in one of its commands, events, decorators or buttons (including a promise it rejected without catching). A plugin that is switched on but not running has a red outline.
• The browser console logs every error with its plugin id, like [plugin dice] Setup: TypeError: …, with the full stack trace.
• A plugin that doesn't appear at all was left out: log in as The Hub owner and look at the bottom of Settings → Plugins, or check plugin.json against the table above.
• Changed files not showing up? Raise "version" in plugin.json, then reload.
• To try changes quickly, turn the plugin off and on in Settings → Plugins: setup runs again (the script itself is only fetched again after a reload).