Settings

contributes.settings describes a card the user sees in Connect for your plugin — the fields it renders and the values your handlers read back out.

Declaring settings

"settings": {
  "word-count.apiKey": { "type": "string", "title": "API key", "description": "Used for outbound calls", "secret": true, "required": true, "order": 1 },
  "word-count.verbose": { "type": "boolean", "title": "Verbose logging", "default": false, "order": 2 }
}

Each key is a setting id (conventionally <plugin-name>.<field>); each value describes how it’s rendered and validated.

Types

• string, boolean, number — ordinary form fields.
• action — renders a button instead of an input. Runs handler (a relative path) when clicked; variant is "primary" | "secondary" | "danger".
• info — displays text; collects no value.

action is not available under runtime: "process" — see Process runtime.

Other field options

enum, multiline, min/max, order are also accepted; order is shown above.

Secrets

secret: true stores the value encrypted, using the OS keychain. A secret value reaches your handlers through ctx.settings.get, exactly like any other setting — but it never reaches the renderer in plain text.

Reading settings

const apiKey = await ctx.settings.get('word-count.apiKey');

ctx.settings.get(key), ctx.settings.set(key, value), and ctx.settings.getAll() read and write values from a handler. getAll() returns only the keys under your plugin’s own prefix.

Reacting to a change

When the user saves a setting on the card, the app emits the onPluginSettingsChanged { key, oldValue, newValue } hook. Two things to know before relying on it:

• It is delivered to every plugin’s handler, not just the plugin whose setting changed — check that key starts with your prefix before acting.
• oldValue is always undefined; read newValue, or call ctx.settings.get for the current value.

A value written by your own handler through ctx.settings.set does not fire the hook. See Hooks and events.

Next

• Permissions — settings: true is what exposes ctx.settings at all
• Manifest reference — the full settings field shape