Skip to main content

Settings

Declare settings in your manifest and Termix draws the form, stores the values, encrypts secrets and checks every save. You don't build settings UI.

"contributes": {
"settings": {
"admin": [
{
"key": "apiUrl",
"type": "string",
"labelKey": "settings.apiUrl.label",
"descriptionKey": "settings.apiUrl.description",
"default": "https://api.example.com"
},
{ "key": "apiToken", "type": "secret", "labelKey": "settings.apiToken.label" }
],
"user": [
{ "key": "compact", "type": "boolean", "labelKey": "settings.compact.label", "default": false }
],
"host": {
"enableKey": "enabled",
"enableLabelKey": "settings.host.enabled.label",
"fields": [
{ "key": "port", "type": "number", "labelKey": "settings.host.port.label", "default": 8080, "min": 1, "max": 65535 }
]
}
}
}

Scopes​

ScopeWho sets itWhere it shows
adminAdmins, for everyone.Your page in Settings, for admins.
userEach person, for themselves.Your page in Settings.
hostPer host.A section in the host editor, named after your plugin.

A host section's enableKey is a switch shown first. It gates the rest, and Termix uses it for the feature filter and bulk on and off in the host list.

Field types​

boolean, string, number, select, multiselect, secret, textarea, json and custom.

OptionWhat it does
labelKey, descriptionKey, placeholderKeyStrings from your locales/en.json.
defaultThe value before anyone saves one.
optionsFor select and multiselect: [{ value, labelKey }].
min, maxFor number.
requiresA boolean in the same scope that has to be on.
groupA heading the field sits under.
permissionWho may change it. Admin fields default to admin.plugins.manage.
hiddenStored and checked, but left out of the form. For fields you edit in your own UI.
componentFor custom: a component you registered with app.registerSettingsComponent.

Host fields also take:

OptionWhat it does
defaultablefalse keeps it out of host defaults, for values unique to one host.
defaultLevelsWhich default levels it can be set at.
personalLook and feel. A shared host reads it from the viewer's defaults.
shareReadHides it from people a host is shared with below this level.
ownerOnlyOnly the host's owner can change it.

Secrets are encrypted, never sent to the browser, and can't be host defaults.

Read and write​

const url = await ctx.settings.get<string>("apiUrl");
const compact = await ctx.settings.getUser<boolean>(userId, "compact");
const port = await ctx.settings.getHost<number>(hostId, "port");

await ctx.settings.setHost(hostId, "port", 9090);
ctx.settings.onChange((change) => reload(change));

Your own settings need no capability. listHostValues(key) lists every host with a value for a host field, for background jobs, and needs hosts:read.

On the frontend, useSettings("user") gives you values and a save.

Check a save​

ctx.settings.onValidate("admin", (values) => {
if (!String(values.apiUrl).startsWith("https://")) {
return { apiUrl: "Use an https address" };
}
return {};
});

Return field key to message. The form shows every problem at once and nothing is saved.

Settings or environment variables​

Use settings. They can be changed in the app and per user or host, and they sync. Use an environment variable only for something needed before Termix starts.