V2 Library

The BundleBD package includes an optional library with tools for commonly needed functionality like settings, strings, etc. None of the modules in the library are required or bundled with plugins by default. The modules can be imported and bundled just like any other file.

Note: Even though each library module is imported from the same source, BundleBD uses tree shaking to ensure that only the exports used in your plugin will be bundled with it.

SettingsManager

Simple class for managing and using a plugin's settings.

import { SettingsManager } from "bundlebd";

constructor()

Creates a new SettingsManager object with the given default settings. Takes as a parameter an object containing the default settings. The type of the defaultSettings object will be used to determine the type of the settings object.

constructor<Settings>(defaultSettings: Settings)

keys

An array of all the settings keys.

keys: (keyof Settings)[]

get()

Gets the value of a setting, or a default value if the setting does not exist. Takes as a parameter the key of the setting, and returns the value of the setting.

get<Key extends keyof Settings>(key: Key): Settings[Key]

set()

Sets and saves the value of a setting. Takes the key of the setting and the new value as parameters.

set<Key extends keyof Settings>(key: Key, value: Settings[Key]): void

type Listener

A callback that is run when a setting is changed.

type listener = (key?: keyof Settings, value?: Settings[keyof Settings]) => void;

addListener()

Adds a listener that runs when a setting is changed. Takes a callback function with optional key and value arguments (for the key of the changed setting and its new value) to run when a setting is changed. Returns a function to remove the listener.

addListener(callback: Listener): () => void

clearListeners()

Removes all listeners. Used for cleanup from addListener. Should be run at plugin stop if any listeners were added and not removed.

clearListeners(): void

useSettingsState()

A React hook that gets the settings object as a stateful variable.

useSettingsState(): Settings

Example

An example of the Settings module in action.

import { SettingsManager } from "bundlebd";

export default class Plugin {
	// Creates a new SettingsManager with the given default settings
	Settings = new SettingsManager({ color: "red", checked: true });

	start() {
		// Gets the value of the 'color' setting. Since no value is saved, returns the default of 'red'.
		const red = this.Settings.get("color");

		// Sets the value of the 'color' setting to 'green' and saves it to the plugin's config file.
		this.Settings.set("color", "green");

		// Gets the value of the 'color' setting. Since a value is saved, returns 'green'.
		// Since a value is now saved to the plugin's config file, even when the plugin is restarted, each variable will be set to saved value of 'green'.
		const green = this.Settings.get("color");

		// Will log when any setting is changed and what its new value is.
		const remove = this.Settings.addListener((key, value) => {
			console.log(`${key} changed to ${value}!`);
		});

		// This would remove the previously added listener.
		// remove();
	}

	stop() {
		// Removes all listeners. Always be sure to remove listeners when the plugin is stopped if you've added any.
		this.Settings.clearListeners();
	}
}

useSettingState Example

export default function MyComponent(props) {
	// Now whenever the value of the 'color' setting changes, the component will be updated.
	const { color } = Settings.useSettingsState();

	return <div style={{ color }}>This text is colored!</div>;
}

StringsManager

Utilities for handling localization and strings.

import { StringsManager } from "bundlebd";

constructor()

Creates a StringsManager object with the given locales object. Takes as parameters an object containing the strings for each locale, and optionally a code for the locale to use as a fallback when strings for Discord's selected locale are not defined (defaults to "en-US").

constructor<Locales>(locales: Locales, defaultLocale?: keyof Locales)

get()

Gets a string from Discord's selected locale (or default locale if the string is not defined). Takes as a parameter the key of the desired string and returns the string.

get(key: string): string

subscribe()

Subscribes to Discord's locale changes. Should be run on plugin start.

subscribe(): void

unsubscribe()

Unsubscribes from Discord's locale changes. Should be run on plugin stop.

unsubscribe(): void

Example

An example of the Strings module in action.

import { StringsManager } from "bundlebd";

const locales = {
	"en-US": {
		HELLO: "Hello",
		HELLO_WORLD: "Hello world!"
	},
	de: {
		HELLO: "Hallo"
	}
};

export default class Plugin {
	// Initializes a new StringsManager with the locales object and sets the default locale to 'en-US'. It already is by default, but this is just to demonstrate usage of the method.
	Strings = new StringsManager(locales, "en-US");

	start() {
		// Subscribes to locale changes.
		this.Strings.subscribe();

		// Gets the string at key 'HELLO' for Discord's selected locale (Let's say its English for now). So it will return 'Hello'.
		let hello = this.Strings.get("HELLO");

		// Now let's say the user changes their locale to German...

		// It will return 'Hallo' since the string is defined for the selected locale.
		hello = this.Strings.get("HELLO");

		// Since there is no string for the key 'HELLO_WORLD' for German, it will return the string for the key 'HELLO_WORLD' for the default locale, or in this case, English. So it will return 'Hello world!'.
		hello = this.Strings.get("HELLO_WORLD");
	}

	stop() {
		// Unsubscribes from locale changes for cleanup.
		this.Strings.unsubscribe();
	}
}

If you want, you can also import the locales object from a JSON file:

// src/locales.json

{
	"en-US": {
		"HELLO": "Hello",
		"HELLO_WORLD": "Hello world!"
	},
	"de": {
		"HELLO": "Hallo"
	}
}

// src/index.js

import { StringsManager } from "bundlebd";
import locales from "./locales.json";

export default class Plugin {
	Strings = new StringsManager(locales);

	start() {
		this.Strings.subscribe();
	}

	stop() {
		this.Strings.unsubscribe();
	}
}