Add plugin settings
Add plugin settings for choices the user controls, such as a default sort, a feature toggle, a refresh interval, or a preferred folder. Phials persists settings by plugin ID and presents them with the plugin’s capabilities in Settings.
Most plugins need only a PluginSettingsSchema. Phials builds the controls, loads saved values before activation, applies defaults for new fields, and provides a standard Reset to defaults action.
const SETTINGS = { showSummary: "showSummary", refreshMinutes: "refreshMinutes",} as const;
const settings: PluginSettingsSchema = { title: "Document summary", fields: [ { key: SETTINGS.showSummary, type: "boolean", label: "Show summary", description: "Show a generated summary above document details.", default: true, }, { key: SETTINGS.refreshMinutes, type: "number", label: "Refresh interval", description: "Minutes between background refreshes.", default: 30, min: 5, max: 240, step: 5, }, ],};
export default function createPlugin(): PhialsPlugin { return { id: "example.document-summary", name: "Document summary", version: "1.0.0", settings, providers: [ // Capability providers ], };}Build the settings contract
- Define plugin settings with stable keys, useful defaults, field constraints, and reset behavior.
- Read and update plugin settings through
api.settings, and callapi.openSettings()when a command should open this plugin’s settings page. - Build a custom settings interface only when the schema-generated controls cannot express the interaction.
Plugin settings are for user-configurable behavior. They are not a general persistence bucket. Use Choose between settings, storage, and a database for cached state, progress, indexes, records, and other plugin-owned data.
Public settings contracts
The generated reference provides exact signatures for:
A plugin can contribute several capabilities but has one settings namespace and one optional settings interface.