Storage

What is Storage?

storage is Unbound’s settings store. Values you write are held in memory, broadcast as an event, and saved to disk, so your addon’s configuration survives a reload without any file handling on your part. Writes are debounced and serialized to Unbound/settings.json in the documents directory, using the fs module. You don’t call read or write yourself. Use get and set.

import { storage } from '@unbound-app/api';

storage.set('my-plugin', 'enabled', true);
storage.get('my-plugin', 'enabled', false); // → true

Stores & keys

Settings are grouped into stores, one per addon. You pick each store’s name, usually your plugin’s id. Keys inside a store are dot-paths. set('appearance.compact', true) writes { appearance: { compact: true } } and creates the intermediate objects for you. To avoid repeating the store name on every call, use getStore to get a facade scoped to one store. Then call get, set, toggle, or remove on it directly.

import { storage } from '@unbound-app/api';

// Scope every call to one store so you never repeat its name.
const settings = storage.getStore('my-plugin');
settings.set('appearance.compact', true);   // dot-path key
settings.get('appearance.compact', false);  // with a default

Reading & writing

Every read takes a default value, which is returned when the key isn’t set yet. This means get never returns an unexpected undefined.

const settings = storage.getStore('my-plugin');

settings.set('volume', 0.8);
const volume = settings.get('volume', 1); // default 1 if unset

// Flip a boolean against its current (or default) value.
settings.toggle('muted', false);

settings.remove('volume'); // delete one key
settings.clear();          // drop the whole store

get requires a default as its last argument. This keeps the store predictable and keeps undefined out of your UI.

Reactivity

In React, useSettingsStore subscribes a component to a store and re-renders it whenever a matching change happens. Pass an optional predicate to narrow which changes trigger a re-render. Every change emits a changed event. Stores also emit set, toggled, removed, and cleared.

import { storage } from '@unbound-app/api';

// Re-renders the component whenever this store changes.
function Toggle() {
	const store = storage.useSettingsStore('my-plugin');
	const compact = store.get('appearance.compact', false);

	return (
		<Switch
			value={compact}
			onValueChange={(v) => store.set('appearance.compact', v)}
		/>
	);
}

Outside React, subscribe with storage.addListener(predicate, callback). It returns an unsubscribe function. Call it when your addon stops.

This module owns the values. To give your addon its own screen in Discord’s settings list, see settings. The keys the loader reads from the same file are listed in the settings reference.

Addons

Plugins

Themes

Icon Packs

Development

API Reference

Loader

What is Storage?

Stores & keys

Reading & writing

Reactivity

​What is Storage?

​Stores & keys

​Reading & writing

​Reactivity

What is Storage?

Stores & keys

Reading & writing

Reactivity