api.storage

Key-value storage with JSON serialization

Overview

api.storage wraps localStorage with automatic JSON serialization.

Global Storage Methods

storage.get(key)

Retrieve a value. Returns null if not found.

const theme = api.storage.get('my-theme');

Parameter	Type	Description
key	string	Storage key

Returns: any | null

storage.set(key, value)

Store a value (auto-serialized to JSON).

api.storage.set('my-counter', 42);
api.storage.set('my-list', [1, 2, 3]);
api.storage.set('my-obj', { name: 'test' });

Parameter	Type	Description
key	string	Storage key
value	any	Value to store (must be JSON-serializable)

storage.set() emits a storage:change event automatically, so other plugins can react to storage updates.

storage.remove(key)

Delete a stored key.

api.storage.remove('my-counter');

storage.list()

Returns an array of all localStorage keys.

const keys = api.storage.list();
// → ['board-plugins-registry', 'my-counter', ...]

Returns: string[]

storage.clear()

Clears all localStorage data. Use with caution.

api.storage.clear();

storage.clear() removes everything, including other plugins’ data and the plugin registry.

Plugin-Scoped Storage

These methods automatically prefix keys with plugin:{pluginId}:, preventing collisions between plugins. The current plugin ID is determined automatically.

storage.getForPlugin(pluginId, key)

Retrieve a value scoped to a specific plugin.

const theme = api.storage.getForPlugin(meta.id, 'theme');
// Actually reads from localStorage key: "plugin:my-plugin:theme"

Parameter	Type	Description
pluginId	string	Plugin ID to scope to
key	string	Storage key (no need to prefix manually)

Returns: any | null

storage.setForPlugin(pluginId, key, value)

Store a value scoped to a specific plugin.

api.storage.setForPlugin(meta.id, 'theme', 'dark');
// Actually writes to localStorage key: "plugin:my-plugin:theme"

Parameter	Type	Description
pluginId	string	Plugin ID to scope to
key	string	Storage key (no need to prefix manually)
value	any	Value to store

setForPlugin() emits a storage:change event with the pluginId field set, so listeners can identify which plugin changed.

Best Practices

Use plugin-scoped storage

Prefer getForPlugin/setForPlugin over manual prefixing — it’s safer and cleaner:

// ✅ Good — automatic scoping
api.storage.setForPlugin(meta.id, 'theme', 'dark');

// ⚠️ Works, but manual prefixing
api.storage.set(`${meta.id}-theme`, 'dark');

Use nullish coalescing for defaults

const is24h = api.storage.get('clock-24h') ?? false;

See Also

• Storage concept — detailed guide with examples
• Persisting Data guide — real-world patterns