plugin.toml reference

Every plugin has a plugin.toml at the root of its folder. It names the plugin, sets its version, and declares the settings a server owner fills in. Weeble checks it on every publish and rejects the version with a message that names the problem.

The file is TOML. Only name, slug, and version are required:

name = "Starboard"
slug = "starboard"
version = "1.0.0"

A complete example

name = "Starboard"
slug = "starboard"
version = "1.3.0"
summary = "Reposts the server's most starred messages."
entry = "src/main.ts"
commands = ["starboard"]

[[settings]]
key = "channel"
type = "channel"
label = "Starboard channel"
description = "Where starred messages are reposted."
required = true

[[settings]]
key = "threshold"
type = "number"
label = "Stars needed"
default = 3
min = 1
max = 50

[[settings]]
key = "emoji"
type = "choice"
label = "Reaction"
choices = ["⭐", "🌟", "🔥"]
default = "⭐"

[[settings]]
key = "self_star"
type = "boolean"
label = "Count the author's own star"
default = false

Top-level keys

name string Required

1 to 60 characters. Shown on cards, the plugin page, and the server's Plugins tab.

slug string Required

1 to 40 lowercase letters, digits, or dashes, starting and ending with a letter or digit. Permanent after the first publish.

version string Required

MAJOR.MINOR.PATCH, such as 1.2.0. Each publish must be higher than the last.

summary string

Up to 200 characters. One sentence about what the plugin does, shown under its name.

entry string

The file that calls weeble.definePlugin(). Defaults to src/main.ts.

commands array of strings

Up to 25 top-level command names the plugin registers, in lowercase and without the /. Used to prevent two plugins on one server from claiming the same name.

settings array of tables

Up to 20 settings. See below.

Weeble ignores keys it does not recognize.

Settings

Each [[settings]] table is one field in the form an owner fills in when they add the plugin. The plugin reads the value as plugin.settings[key].

key string Required

1 to 32 characters: a lowercase letter, then lowercase letters, digits, or underscores. Unique within the plugin.

type string Required

One of the types below.

label string Required

1 to 80 characters. The field's name in the form.

description string

Up to 200 characters of help text under the field.

required boolean

Defaults to false. A required setting with no default must be filled in before the plugin can be added.

default depends on type

Used when the owner leaves the field empty. Must be a valid value for the type.

choices array of strings Required for choice

Up to 25 options. Only allowed on choice settings.

min max number

Bounds for number settings.

max_length integer

Maximum length for string settings, from 1 to 2000. Defaults to 200.

Setting types

channel

The owner picks one of the server's channels. The code gets its ID as a string.

role

The owner picks one of the server's roles. The code gets its ID as a string.

user

The owner types a user ID. The code gets it as a string.

string

The owner types text, up to max_length characters. The code gets a string.

number

The owner types a number, between min and max when set. The code gets a number.

boolean

The owner flips a switch. The code gets true or false.

choice

The owner picks from a dropdown of choices. The code gets the chosen string.

A setting that is not required, has no default, and was left empty is missing from plugin.settings, so check for it before use:

weeble.definePlugin<{ log_channel?: string }>((plugin) => {
  const logChannelId = plugin.settings.log_channel;
  if (logChannelId) {
    // Only log when the owner picked a channel.
  }
});

Changing settings between versions

Installed servers keep their values when they update, so treat each key as permanent:

Adding an optional setting, or a required one with a default, updates without asking the owner anything.
Adding a required setting without a default makes the owner fill it in when they update. Bump the major version.
Renaming a key loses the old value, because the new key starts empty. Add the new key and keep reading the old one until servers have moved over.
Removing a setting is safe. Stored values for keys the new version does not declare are dropped on update.

Common errors

Click a message to see the fix.

plugin.toml is missing

Put plugin.toml at the root of the plugin folder.

entry src/main.ts is not in the project

Create the entry file, or set entry to the file that calls weeble.definePlugin().

plugin.toml slug is x, expected y

The slug in the file does not match the plugin you are publishing. The slug cannot change after the first publish.

version must be greater than 1.2.0

Raise version. Publish Plugin offers the next patch version.

setting keys must be unique

Two settings share a key. Rename one of them.

setting x needs choices

Add a choices array to the choice setting.

/x is already used by Y

Shown to an owner adding the plugin. Another plugin on that server registers the same command.