BdBrowser

BdBrowser is a Chrome extension that loads BetterDiscord in Discord's web client.

🗺 Table of Contents

• Features
• Installation
  • Installing Prebuilt Version
  • Building It Yourself
• Using BdBrowser
  • First Launch
  • Installing Plugins and Themes
  • Updating Plugins or Themes
  • Updating BetterDiscord
  • Updating BdBrowser
  • Uninstalling BdBrowser
  • Extension Options
  • Backing up the Virtual Filesystem
  • Restoring from a Backup
  • Formatting the Virtual Filesystem
  • Deleting Files in the Virtual Filesystem
  • Restricting Extension Site Access
• Using VfsTool
  • Extracting Backup Files
  • Creating Backup Files

 

👓 Features

• Manifest V3 extension for Chromium-based browsers.

• Enables the use of BetterDiscord's unmodified betterdiscord.asar in a web browser.

• Emulates a virtual filesystem in memory and persists changes in an IndexedDB.

  Plugins do not have access to your real filesystem.

• Service Worker handles outgoing web requests from BetterDiscord components to prevent CORS issues.

• Compatible with all BetterDiscord themes.

• Compatible with most* BetterDiscord plugins.

 

🛠 Installation

You can either use the ready-made files present in this repository or build BdBrowser yourself. The latter is useful if you want to audit the code or make changes to it.

 

Installing Prebuilt Version

Since the extension is intentionally not available on the Chrome Web Store, you have to download and install it manually by downloading a prebuilt release from the GitHub releases page, extracting the archive and loading the resulting folder as an unpacked Chrome extension while developer mode is enabled:

1. Download the latest prebuilt extension release as a zip archive.

2. Extract the contents of the zip archive into an empty folder.

3. Open your Chrome extensions page.

4. Make sure the "Developer mode" toggle on the extension page is enabled. This enables you to load unpacked extensions from a local folder.

5. Click the Load unpacked button in the toolbar:

   

   Now select the folder from step 2 you extracted the archive contents into.

6. Congratulations, you should see the extension loaded and working! Once you reload your Discord tab, BetterDiscord should load and show the changelog.

 

Building It Yourself

Building BdBrowser yourself comes with a few prerequisites:

• Git
• Node.js
• pnpm
• A terminal or command prompt

 

Step 1: Clone the BdBrowser repository

git clone https://github.com/tsukasa/BdBrowser.git BdBrowser

Step 2: Install BdBrowser's dependencies

cd BdBrowser
pnpm install

Step 3: Build BdBrowser

pnpm run build-prod

Step 4: Load the Extension

1. Open your Chrome extensions page.

2. Make sure the "Developer mode" toggle on the extension page is enabled. This enables you to load unpacked extensions from a local folder.

3. Click the Load unpacked button in the toolbar:

   

   Now select the dist folder in the BdBrowser repository.

 

🎨 Using BdBrowser

Using BdBrowser is almost exactly the same as using BetterDiscord on your desktop.

First Launch

After enabling the extension and reloading Discord's web client, BdBrowser will initialize its internal virtual filesystem and download a copy of the latest betterdiscord.asar from BetterDiscord's official GitHub releases page.

BetterDiscord will be loaded from within the asar file in the virtual filesystem afterwards.

Subsequent starts will be quicker because no initialization or download needs to take place.

 

Installing Plugins and Themes

You can install plugins/themes by pressing the Open [...] Folder button in the plugins/themes category of BetterDiscord's settings.

Instead of opening the folder containing your plugins/themes, a file picker will open. Choose one or multiple files of the same type (plugins or themes).

The files will get installed into the virtual filesystem and will be available through their respective category immediately afterwards.

 

Updating Plugins or Themes

You can use the normal ways of updating plugins or themes:

• Use the Updater in the settings.
• Use plugin-specific update routines.
• Use the Plugin Repo or Theme Repo plugins.

Of course, you can also download a copy of the updated file manually and add it to the virtual filesystem again. You do not need to remove the old file, following the instructions for installing plugins/themes automatically overwrites a file if it already exists.

 

Updating BetterDiscord

BetterDiscord got updated? Updating within BdBrowser is just as simple as on the desktop:

• Recommended: Create a VFS backup!
• Open the Discord settings.
• Navigate to BetterDiscord's "Updates" category.
• Install the available BetterDiscord update by clicking the Update! button.
• You will be prompted to reload the site.

In case BetterDiscord does no longer work after the update, you should restore the old version from a backup and check if there might be a new version of BdBrowser available that addresses the issue.

If a new version of the extension is available, please follow the instructions to update BdBrowser.

 

Updating BdBrowser

BetterDiscord is no longer working within BdBrowser? BdBrowser got updated? Then it might be time to update your local BdBrowser installation to ensure you have all the latest compatibility improvements and bug fixes.

Updating the extension is pretty much a repeat of installing it with a few notable differences:

• Use the same folder as you did for the installation.
• You do not need to load the unpacked folder again because it is already loaded. Uninstalling the old version does not delete your BdBrowser settings or filesystem.
• Instead, please click the Update button on your Chrome extension page.
• After updating, please perform a hard reload of Discord's page (Shift + F5).

Note: Simply replacing the files/folder and restarting Chrome is not sufficient.

 

Uninstalling BdBrowser

To uninstall BdBrowser, simply remove the extension as you would with every other Chrome extension.

The data stored within the virtual filesystem will be kept.

 

Extension Options

BdBrowser has a few extension options that you can access either by right-clicking the extension icon in your toolbar or the Details button on Chrome's extensions page.

 

Do not load BetterDiscord Renderer

When loading a Discord tab while the option is active, BdBrowser will initialize the virtual filesystem but not inject BetterDiscord's renderer into the active page.

This is useful if you are stuck in a reload loop or experience crashes due to a BetterDiscord or plugin failure and want to diagnose, backup, or import data in the virtual filesystem.

 

Disable all Plugins on Reload

On the next load of a Discord tab, BetterDiscord's plugin.json will be altered by BdBrowser to disable all BetterDiscord plugins before injecting BetterDiscord's renderer.

This option automatically turns itself off again after it was used.

 

Delete Asar from VFS on Reload

Automatically deletes the betterdiscord.asar file from the virtual filesystem on the next load of a Discord tab. Doing so will prompt BdBrowser's asar updater to download a fresh copy of BetterDiscord's latest asar file from BetterDiscord's GitHub releases.

Using this option is tantamount to re-installing BetterDiscord on a regular desktop client and is sometimes the only option to fix crashes caused by incompatibilities between BetterDiscord's renderer and the Discord web application.

User data like plugins, themes, or settings are unaffected by this option and stay untouched.

This option automatically turns itself off again after it was used.

 

Backing up the Virtual Filesystem

Backups are great. You can download a serialized copy of your virtual filesystem through the console:

require("fs").exportVfsBackup();

 

Restoring from a Backup

If you made a backup of your virtual filesystem, you can restore it at any point.

Open the console and use the following command:

require("fs").importVfsBackup();

A file picker will open. Choose a backup file.

All files contained within the backup will be restored to the version serialized in the backup. Files that do not exist in the backup stay untouched.

After importing the backup, please refresh the page.

 

Formatting the Virtual Filesystem

If you want to format the virtual filesystem and start over from scratch, you can manually trigger this via the console:

require("fs").formatVfs(true);

Entering this command will immediately wipe the virtual filesystem.

Please reload the page after using the command.

 

Deleting Files in the Virtual Filesystem

In some rare cases you might want to remove orphaned or ill-behaving files from the extension's virtual filesystem but cannot find/uninstall them through BetterDiscord's settings.

You can perform these operations via your browser's developer tools console:

/* Read the contents of the virtual plugins folder */
require("fs").readdirSync(BdApi.Plugins.folder)
/* Removes the file named "SomePluginName.plugin.js" from the virtual plugins folder */
require("fs").unlinkSync(require("path").join(BdApi.Plugins.folder, "SomePluginName.plugin.js"))

Reload the Discord tab afterwards.

 

Restricting Extension Site Access

By default, BdBrowser is allowed to read and change all your data on all sites through the extension's "Site access" setting (accessible through Chrome's extension page and clicking the Details button for an extension).

The default is set liberally so that all web requests handled by the service worker will work out of the box. Otherwise, the user would manually have to configure the allowed domains beforehand as part of the onboarding/installation.

If you know exactly which domains your specific set of themes/plugins query, you can harden the configuration by changing the Site Access setting from On all sites to On specific sites and adding the allowed domains manually.

 

🧰 Using VfsTool

BdBrowser comes with the VfsTool.ps1 Powershell script that allows you to create and extract virtual filesystem files.

The script is located under assets/scripts/VfsTool.ps1 in the extension directory.

 

Extracting Backup Files

If you have an existing backup file, you can extract its contents with this command:

.\VfsTool.ps1 -Operation Extract -Path C:\path\to\your\bdbrowser_backup.json -OutputPath C:\temp

The output path has to exist already, otherwise the script will fail.

 

Creating Backup Files

You can create a virtual filesystem backup file for use in BdBrowser from your real filesystem - whether this is from using your existing BetterDiscord appdata or a tailor-made structure of files to inject files into the virtual filesystem.

The resulting files can be imported into the virtual filesystem.

 

Create a Backup from your real AppData

Using the VfsTool you can easily create a backup that contains your current BetterDiscord configuration (themes, plugins and BetterDiscord settings) for use in BdBrowser.

.\VfsTool.ps1 -Operation Create -Path "$($env:APPDATA)\betterdiscord" -OutputPath C:\temp\bdbrowser_backup_MyRealBdConfig.json

 

Create a Backup containing a custom BetterDiscord asar File

Since a restore only overwrites files present in the backup itself, you can create handy partial backup files to up- or downgrade BetterDiscord via VfsTool:

Step 1: Create an empty root directory.

mkdir bdtemp

Step 2: Create a "data" directory within the root directory.

cd bdtemp
mkdir data

Step 3: Place a betterdiscord.asar from GitHub in the data directory.

Step 4: Create the backup file through the VfsTool.

.\VfsTool -Operation Create -Path C:\temp\bdtemp -OutputPath C:\temp\bdbrowser_backup_bdasar.json

Note: Please make sure you mind the folder and file names, as the virtual filesystem is case-sensitive!

---

Back to Top