-
Notifications
You must be signed in to change notification settings - Fork 1
Getting Started
To install BundleBD, simply create a new folder, open it in VSCode or your preferred editor/terminal, and run:
npm i bundlebd -D
First make sure you read the BetterDiscord Plugin Docs and know at least the basics of making plugins.
By default, the bundler will look in the src directory for the plugin's files. Create a new src folder, and inside of it create an index.js file, exporting a simple BetterDiscord Plugin without the meta. For example:
// src/index.js
export default class MyAmazingPlugin {
start() {
console.log("Plugin started");
}
stop() {
console.log("Plugin stopped");
}
}Now you can run...
npx bundlebd
...in the terminal to bundle the plugin. The bundler will, by default, place the bundled plugin in the dist folder, creating it if necessary.
Now that you have your bundled plugin, you might want to configure it beyond the defaults. The default name 'Plugin' doesn't sound very appealing or descriptive.
Luckily, customizing the plugin's name is easy.
To start, create a config.json file in the same folder as your plugin's main file. So in our example, the file would be in src. In this configuration file, you can add information to the plugin's meta, like it's name:
// src/config.json
{
"meta": {
"name": "MyAmazingPlugin"
}
}The name in the meta will also be stripped of any whitespace and used as the bundled plugin's filename'.
In the config.json file, you can specify more information about your plugin as well. For example, the contents of the file might look like:
// src/config.json
{
"meta": {
"name": "MyAmazingPlugin",
"author": "Neodymium",
"description": "A plugin that does absolutely nothing",
"version": "1.0.0"
}
}Now when you bundle your plugin, the bundler will detect the configuration file and use its information instead of the defaults. For all configuration options, see Plugin Configuration.
Of course, the real appeal of using a bundler is the ability to bundle multiple modules into one plugin file. To use multiple files/modules, just use Javascript's ES module syntax. As an example, let's say there are two files in the src folder with the following contents:
// src/index.js
import { helloWorld } from "./utils";
export default class MyAmazingPlugin {
start() {
helloWorld();
}
stop() {
console.log("Plugin stopped");
}
}// src/utils.js
export function helloWorld() {
console.log("Hello world!");
}Now, when the bundler sees that the plugin's main file imports from utils.js, it will bundle it into the plugin.
Using Typescript
Using Typescript is very simple. Just include a Typescript file in your plugin, and the bundler will automatically transpile it for you. For example, the following will result in a plugin similar to the previous example, with no additional configuration:
// src/index.ts
import { hello } from "./utils";
export default class MyAmazingPlugin {
start() {
let message: string;
message = hello("Neodymium");
console.log(message);
}
stop() {
console.log("Plugin stopped");
}
}// src/utils.ts
export function hello(name: string): string {
return `Hello ${name}!`;
}To resolve issues with typings for BdApi, Zlibrary, and more, see here.
Using JSX
Just like Typescript, JSX is very easy to use. Just include some JSX elements in your code, and the bundler will automatically transpile them into React.createElement calls. For example:
// src/index.jsx
export default class MyAmazingPlugin {
start() {
const element = <div className="class">Hello World!</div>;
console.log(element);
}
stop() {
console.log("Plugin stopped");
}
}Using JSX alongside Typescript is still simple, but may result in some errors.
First, if you use JSX in Typescript, make sure the file has a .tsx extension. Not doing so will result in errors, and the plugin will not bundle successfully.
Additionally, you may get a warning along the lines of:
'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.
You can safely ignore this warning, as the bundler will include a reference to Discord's React instance in the bundled plugin. However, there are two ways to get rid of it. The first is to include...
import React from "react";...at the top of your file. The second is to create a tsconfig.json file in the project's root directory with the following contents:
{
"compilerOptions": {
"jsx": "react-jsx"
}
}See Typescript Configuration for more recommended TSConfig options.
Utilizing functions and utilities from BdApi is easy, just import them from betterdiscord.
// src/index.js
import { Webpack } from "betterdiscord";
export default class MyAmazingPlugin {
start() {
const UserPopoutBody = Webpack.getModule((m) => m.default?.displayName === "UserPopoutBody");
console.log(UserPopoutBody);
}
stop() {}
}The bundler includes typings/autocomplete for BdApi. If they are not being detected in Typescript, see here.
(Currently BundleBD supports CSS, SCSS, and Sass, but more CSS extension languages may be added in the future)
As should be expected by this point, stylesheets are also easy to use. Importing a stylesheet will give you a string of the stylesheet's processed CSS, which you can then inject like normal CSS.
// src/index.js
import styles from "./index.css";
import { injectCSS, clearCSS } from "betterdiscord";
export default class MyAmazingPlugin {
start() {
injectCSS("MyAmazingPlugin", styles);
console.log("Plugin started");
}
stop() {
clearCSS("MyAmazingPlugin");
console.log("Plugin stopped");
}
}Local @imports and URLs included in imported stylesheets will be bundled with the plugin. For more information on how imports and URLs are handled, see here, and for information on how local files like images will be bundled, see Other File Types.
A great feature included with the bundler is the ability to use CSS modules. You might already be familiar with them, but if not, here's a quick scenario:
Let's say two plugins inject styles, and both include the same class. This will result in conflicts between the two plugins, and the styling might not work as intended. You could change all the class names in the plugins to be unique, or you could use CSS modules instead.
When importing CSS modules, the bundler will take the normal stylesheet with local class like this:
/* A local class */
.class {
color: red;
}And turn it into something like this with global classes:
/* A global class that will be used in the injected stylesheet */
.Plugin-index-class {
color: red;
}This makes conflicts much less likely. CSS modules have many more use cases and features, but they won't be covered here. For more info see here.
Using CSS modules is very similar to using regular stylsheets:
The bundler will treat any files with the extention .module.css, .module.scss, .module.sass, etc. as CSS modules. Also, if you include a query string of ?module to any normal stylesheet, it will be treated as a CSS module.
The one difference is that the imported CSS module will export an object with the local class names as keys to get the global class names. It will also export a content variable with a string of the processed CSS.
/* src/index.module.css */
.redText {
color: red;
}// src/index.jsx
import styleModule, { content } from "./index.module.css";
import { injectCSS, clearCSS } from "betterdiscord";
export default class MyAmazingPlugin {
start() {
injectCSS("MyAmazingPlugin", content);
// Now the content of the element will be red!
const element = <div className={styleModule.redText}>Hello World!</div>;
console.log("Plugin started");
}
stop() {
clearCSS("MyAmazingPlugin");
console.log("Plugin stopped");
}
}Or with the query string option (my personal preference):
/* src/index.css */
.redText {
color: red;
}// src/index.jsx
import styleModule, { content } from "./index.css?module";
import { injectCSS, clearCSS } from "betterdiscord";
//... Rest of the Code ...Often, it will be required to import multiple stylesheets, or import stylesheets in multiple files. BundleBD has a simple tool to deal with this: the styles module.
Importing from styles will give you a function that returns a string of all of the imported stylsheets from every file in your plugin.
(Note: If you're only using the styles module to inject your stylesheets, you don't need to import from the stylesheet or import content from the CSS module, as seen in the example.)
// src/component.jsx
// There's no need to import content here, since the contents will be included when importing from styles
import styleModule from "./component.css?module";
export default function MyComponent() {
return <div className={styleModule.class}>Hello World</div>;
}// src/index.jsx
// There's no need to import a value here, since the contents will be included when importing from styles
import "./index.css";
import importedStyles from "styles";
import { injectCSS, clearCSS } from "betterdiscord";
import MyComponent from "./component.jsx";
export default class MyAmazingPlugin {
start() {
// importedStyles will return the contents of both index.css and component.css
injectCSS("MyAmazingPlugin", importedStyles());
const element = <MyComponent />;
console.log("Plugin started");
}
stop() {
clearCSS("MyAmazingPlugin");
console.log("Plugin stopped");
}
}The bundler includes typings/autocomplete for the styles module, CSS modules and stylesheets. If they are not being detected in Typescript, see here.
ZeresPluginLibrary Support
The bundler can easily bundle plugins that use Zlibrary. All you need to do is set zlibrary to true in your plugin's config.json file:
// src/config.json
{
"meta": {
"name": "MyAmazingPlugin",
"author": "Neodymium",
"description": "A plugin that does absolutely nothing",
"version": "1.0.0"
},
"zlibrary": true
}Using the library in your plugin itself is very simple as well, just import the library from zlibrary and the base Plugin class from zlibrary/plugin and use them as you would normally.
// src/index.js
import Plugin from "zlibrary/plugin";
import { DiscordModules } from "zlibrary";
export default class MyAmazingPlugin extends Plugin {
onStart() {
const UserStore = DiscordModules.UserStore;
console.log(UserStore.getCurrentUser());
}
onStop() {
console.log("Plugin stopped");
}
}When bundling, BundleBD will warn you if you import the library without setting the config option to true, or if you use the library without extending your plugin from the base Plugin class, both of which will prevent your plugin from working properly.
BundleBD includes typings/autocomplete for ZLibrary. If they are not being detected in Typescript, see here.
Using JSON files is pretty simple as well. Just import the file like normal, and you can access the object stored in it:
// src/strings.json
{
"hello": "Hello World!",
"goodbye": "Bye Bye!"
}//src/index.js
import strings from "./strings.json";
export default class MyAmazingPlugin {
start() {
console.log(strings.hello); // Will log 'Hello World!'
}
stop() {
console.log(strings.goodbye); // Will log 'Bye Bye!'
}
}To make sure you have type validation and autocomplete for JSON files in Typescript, see here, and confirm you have resolveJsonModule set to true.
Plain old text files are also supported, and can be imported as strings:
src/message.txt:
Hello World!//src/index.js
import message from "./message.txt";
export default class MyAmazingPlugin {
start() {
console.log(message); // Will log 'Hello World!'
}
stop() {}
}PNG, JPG, and JPEG image are supported as well, and can be imported as Base64 encoded urls:
//src/index.jsx
import image from "./image.png";
export default class MyAmazingPlugin {
start() {
const image = <img src={image} />;
}
stop() {}
}This behavior also appies to CSS files:
/* src/index.css */
.class {
background-image: url(./image.png);
}SVGs are treated a little differently than normal images. Importing an SVG in a Javascrript or Typescript file will, by default, give you a React Component to use with JSX:
//src/index.jsx
import Icon from "./icon.svg";
export default class MyAmazingPlugin {
start() {
const svg = <Icon width="18" height="18" />;
}
stop() {}
}If you instead want to import it as a Base64 string, you can use the ?url resource query:
//src/index.jsx
import url from "./icon.svg?url";
export default class MyAmazingPlugin {
start() {
const image = <img src={url} />;
}
stop() {}
}In CSS files, SVGs will be treated the same as normal images.