Architecture overview

Understanding BetterDiscord’s three-package architecture

BetterDiscord is built as a modular system with three core packages that work together to modify and enhance Discord. This architecture provides a clean separation of concerns and enables reliable injection into the Discord client.

Three-package architecture

BetterDiscord uses a monorepo structure managed by pnpm with three main packages:

Injector

The injector package is responsible for the initial injection into Discord. Its primary job is to:

• Inject into Discord’s main process
• Load the preload script into Discord’s BrowserWindow
• Set up the foundation for BetterDiscord to run

The injector code lives in the injector/ folder of the repository.

Preload

The preload package serves as a bridge between Discord’s main process and the renderer process. It:

• Runs as Discord’s preload script for the main BrowserWindow
• Sets up cross-context APIs between main and renderer processes
• Provides secure communication channels through IPC
• Exposes necessary functionality to the renderer

The preload code lives in the preload/ folder.

Renderer application

The renderer is the main payload of BetterDiscord and where most user interaction occurs. This is executed in the renderer context by the injector and handles:

• Loading and managing plugins
• Loading and applying themes
• Initializing builtin features
• Managing settings and user preferences
• Providing the BdApi for plugin developers

The renderer code lives in the renderer/ folder.

Startup sequence

When Discord launches with BetterDiscord, the following sequence occurs:

1. Injector runs

   The injector modifies Discord’s main process and sets up the preload script.

2. Preload executes

   The preload script runs before Discord’s renderer code, establishing cross-context APIs.

3. Renderer loads

   The renderer application is loaded into Discord’s renderer process:

   // From src/betterdiscord/index.ts
   import BetterDiscord from "@modules/core";
   import BdApi from "@api/index";
   
   // Set up global BdApi
   Object.defineProperty(window, "BdApi", {
       value: BdApi,
       writable: false,
       configurable: false
   });
   
   // Start BetterDiscord
   BetterDiscord.startup();
   
4. Core initialization

   The core module initializes all BetterDiscord systems in sequence:

   // Simplified from src/betterdiscord/modules/core.ts
   async startup() {
       // Inject BD styles
       DOMManager.injectStyle("bd-stylesheet", Styles);
       
       // Initialize managers
       AddonStore.initialize();
       LocaleManager.initialize();
       Settings.initialize();
       DOMManager.initialize();
       CommandManager.initialize();
       
       // Wait for Discord connection
       await this.waitForConnection();
       
       // Initialize UI
       FloatingWindows.initialize();
       Toasts.initialize();
       
       // Load builtins
       for (const module in Builtins) {
           Builtins[module].initialize();
       }
       
       // Load user addons
       PluginManager.initialize();
       ThemeManager.initialize();
       
       // Set up updates
       Updater.initialize();
   }
   
5. Builtins, plugins, and themes load

   Built-in features are enabled, followed by user plugins and themes.

Key modules

Core

The Core module (src/betterdiscord/modules/core.ts) orchestrates the entire startup process and manages the lifecycle of all BetterDiscord components.

Settings store

Manages all BetterDiscord settings, including:

• Builtin feature toggles
• User preferences
• Plugin and theme states
• Custom CSS configuration

Addon managers

Two specialized managers handle user content:

• PluginManager: Loads, enables, disables, and manages JavaScript plugins
• ThemeManager: Loads and applies CSS themes

Both extend the base AddonManager class which provides common functionality like file watching, state persistence, and error handling.

Patcher

The Patcher module enables modification of Discord’s code at runtime by hooking into functions with before, after, and instead methods.

DOMManager

Handles all DOM-related operations including:

• Injecting styles (BetterDiscord core, custom CSS, themes)
• Observing DOM changes
• Managing class names and attributes

Development workflow

For local development:

Build and inject

# Install dependencies and build
pnpm install && pnpm build

# Inject into desired Discord channel
pnpm inject <channel>
# channel can be: stable, canary, or ptb

Renderer changes are picked up on Discord reload, but preload and injector changes require a full Discord restart.

Next steps

Injection system

Learn how BetterDiscord injects into Discord

Addon system

Understand how plugins and themes work

Builtin features

Explore BetterDiscord’s built-in features