Settings and persistent storage

Declare settings for manifest-defined preferences and storage for plugin-private JSON data. These serve different purposes.

Define preferences

Add a setting to your manifest’s settings array:

{
  "key": "greeting",
  "title": "Greeting",
  "kind": "string",
  "defaultValue": "Hello"
}

FluxPlugs renders the setting in its native Settings page and validates updates against its declared type.

const greeting = await api.settings.get<string>("greeting");
const starts = (await api.storage.get<number>("starts")) ?? 0;
await api.storage.set("starts", starts + 1);
api.logger.info("Plugin started", { greeting, starts: starts + 1 });

The generic TypeScript parameter describes the expected value; it is not runtime validation for arbitrary stored data. Validate structured storage before using it, especially after upgrades.

Choose the right persistence

Settings are boolean, string, or finite number values. Their defaults must match their type. Storage accepts bounded JSON values and provides get, set, and delete; it is not browser localStorage or executable code storage.

Read current settings on each start because setting changes restart the plugin.

Updates and removal

Keep IDs and compatible setting keys stable. Reimport retains compatible values, uses defaults for new settings, and removes obsolete ones. Separate plugin storage survives updates and uninstall; settings and trust do not survive uninstall.

If your storage structure changes, add a version field, validate old values, and migrate without deleting unrelated data. Catch storage errors and show an actionable message rather than continuing with a partially saved change.