FOR THE PERSON WRITING ONE
Write a
plugin.
One .js file, in CommonJS: it sets module.exports, which
gives Elixcord its hooks, its chat commands and its settings, and may call
elixcord's own API and nothing else. A call into it has
100 ms to answer; its JavaScript holds at most
32 MiB — a plugin that looped forever is stopped at its own
error and switched off, so it can never hold the app still.
The shape of one
The hooks
| Name | Called with | What it may answer |
|---|---|---|
start() · stop() |
nothing | The plugin switched on, and off. Set up and let go here. |
transformOutgoing(msg) |
{room, content} |
{content} with what to send instead, or false to
stop the message, or nothing to leave it. An edit goes through it too. |
transformIncoming(msg) |
{room, id, author, content, own, bot, time} |
{content} to change what shows, or false to hide
the message. Only the open room's timeline and its thread's come through. |
onMessage(msg) |
the same as transformIncoming's |
Anything; nobody reads it. |
run(args, ctx) — inside a commands entry |
args, the words after the name, and ctx =
{room} |
{content}, which sends as a message, or
{toast: {title, body}}, which tells of itself. |
A hook that answers nothing leaves the message as it was. One that throws shows its error on the Plugins page and keeps running; one that doesn't answer in time is stopped, and its plugin with it.
The elixcord API
A plugin reads no file and opens no socket of its own: the calls below are everything it may do. Arguments and answers are plain values.
| Call | What it does |
|---|---|
elixcord.notify(title, body) |
Tells of something, as a new message's notification does: the sound, the tray, and the system's notification — which opens nothing, as the plugin sent it. |
elixcord.log(...) |
One line to Elixcord's own log, as [file.js] …; only the first
line of each call is kept. |
elixcord.storage.get(key)elixcord.storage.set(key, value)elixcord.storage.delete(key) |
The plugin's own store, kept in the data folder's
plugins-data.json, written whole. Each plugin's store is its own. |
elixcord.settings.get(key) |
One of the plugin's settings, as the Plugins page set it; nothing for a key its schema doesn't declare. |
elixcord.net.fetch(url, options) |
A fetch, as fetch's are: {method, headers, body}. It
answers a promise with {status, body}, the body as text at most
10 MiB, or rejects with what went wrong. It goes nowhere unless the person
turned Allow network access on for this plugin; off, the
promise rejects at once. |
Settings, as a schema
Whatever settings declares shows on the Plugins page, kept in the app's
layout.json, and read back with elixcord.settings.get:
settings: {
word: { type: "text", label: "Word to shout", default: "hey" },
times: { type: "number", label: "How many", default: 1 },
on: { type: "switch", label: "Be loud", default: false },
}
A number's entry shows what was typed, and reads to the plugin as a number once it parses — a setting is never corrected under the person's keys.
What a plugin may not do
- No
require, noimport, no timer, no filesystem, noXMLHttpRequest— only the API above. - No look at who says what beyond what the hooks hand over: names, avatars and attachments aren't a hook's to read.
- No network but
net.fetch, and only where it's allowed, per plugin, by the person. - No polling of Elixcord: a plugin runs when it's called.
Publish it to the registry
-
1
Make the file whole
Give it
name,description,versionandauthor— the registry's pages read them — and try it in your own plugins folder first. -
2
Put it in the site's repo
Drop the
.jsintoplugins/files/of the site's folder. -
3
Rebuild the registry
Run
node build.mjs: it reads each file's metadata, hashes the file, and rewritesplugins/index.json. A file that exports no name stops the build. -
4
Push
Pages redeploys in under a minute, and every client's next check sees the newer version, downloads the file, checks its hash, and switches it on — by itself.
Whoever controls the registry decides what the clients run, so keep the repo and the deploy yours alone, and keep it on HTTPS. The hash is what makes a download worth writing: a file that doesn't answer for the hash the registry publishes is never installed.