Creating an Addon

This guide builds a small working plugin that finds a Discord module, patches it, and stores a setting. Plugins have the most features of any addon kind, so they make the best example. Themes and icon packs use the same manifest and lifecycle, with different content.

Describe it with a manifest

Create a manifest.json with at least the required fields. The manifest is the metadata Unbound uses to list, attribute, and validate your addon.

manifest.json

{
	"id": "hello-world",
	"name": "Hello World",
	"description": "Logs a greeting when a message is sent.",
	"authors": [{ "name": "you", "id": "1234567890" }],
	"version": "1.0.0",
	"main": "index.js"
}

main points at your entry file. id is the name you use everywhere else. See the manifest for the full field list.

Write the entry point

Your main file default-exports an object with optional start and stop hooks.

Unbound calls start when the plugin is enabled. Set everything up here.
Unbound calls stop when the plugin is disabled. Undo everything start did.

index.ts

export default {
	start() {
		// set up patches, listeners, subscriptions
	},
	stop() {
		// undo everything start() did
	},
};

Unbound evaluates your bundle at startup, even when the plugin is disabled. Keep top-level code cheap and do the real work inside start. See how plugins are loaded.

Find what you want to change

Use Metro to find the Discord module you need. Pass { lazy: true } so the search only runs the first time a property on it is accessed.

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

const Messages = metro.findByProps('sendMessage', 'receiveMessage', { lazy: true });

Patch it

Wrap the function with the patcher. Create a patcher scoped to your plugin so you can revert all of its patches at once.

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

const Patcher = patcher.createPatcher('hello-world');

// inside start():
Patcher.before(Messages, 'sendMessage', ({ args }) => {
	console.log('Sending message to channel', args[0]);
});

Remember a setting

Save configuration with storage. Create a store named after your plugin id, then read and write keys on it. Values persist across reloads with no extra work.

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

const settings = storage.getStore('hello-world');
settings.set('greeting', 'Hello from Unbound');
settings.get('greeting', 'Hi'); // default if unset

Clean up in stop

Revert everything when the plugin is disabled. A single unpatchAll call undoes every patch the patcher made.

stop() {
	Patcher.unpatchAll();
}

If you skip cleanup, your patches keep running after the plugin is disabled. Always clean up in stop. If you patched a component’s render, also force a re-render. See cleaning up.

The full plugin

All the steps combined into one file:

index.ts

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

const Patcher = patcher.createPatcher('hello-world');
const settings = storage.getStore('hello-world');

const Messages = metro.findByProps('sendMessage', 'receiveMessage', { lazy: true });

export default {
	start() {
		Patcher.before(Messages, 'sendMessage', ({ args }) => {
			const greeting = settings.get('greeting', 'Hi');
			console.log(greeting, '→ channel', args[0]);
		});
	},
	stop() {
		Patcher.unpatchAll();
	},
};

Where to go next

Patcher

The full patcher API: before, after, instead, and typing.

Patching Components

Change what Discord’s components render.

Flux Stores

Read Discord’s state and react to its events.

Debugging

Tools for developing and inspecting your addon.

Addons

Plugins

Themes

Icon Packs

Development

API Reference

Loader

Creating an Addon

The full plugin

Where to go next

Patcher

Patching Components

Flux Stores

Debugging

​The full plugin

​Where to go next

Patcher

Patching Components

Flux Stores

Debugging

The full plugin

Where to go next