whirlybird
Warning whirlybird is experimental software. Use at your own risk!
About
A modern JavaScript library for building Discord bots.
- Runtime-agnostic. Works on any JavaScript runtime that implements the Web API.
- Actually fast. No unnecessary abstractions or "type" checking.
- Full-on development ecosystem. A very nice logger (with colors!), low- and high-level interfaces for maximum control, shard clusters, etc.
Core Modules
Learn more about the core modules in their respective READMEs.
Installing
Using Node.js
You will need Node.js v19.x.x or higher.
Install with the package manager of your choice:
$ npm i whirlybird
$ pnpm i whirlybird
$ yarn add whirlybird
You can also install from @whirlybird for a specific core module.
$ npm i @whirlybird/http
$ pnpm i @whirlybird/http
$ yarn add @whirlybird/http
Enable ECMAScript modules (ESM) for your project:
{
"type": "module"
}Using Deno
You will need Deno v1.26.x or higher.
Import for GitHub:
export * from "https://github.com/apacheli/whirlybird/raw/dev/core/whirlybird/lib.js";Use the import map provided below (or continue reading to just generate one using the CLI):
{
"imports": {
"@whirlybird/cache": "https://github.com/apacheli/whirlybird/raw/dev/core/cache/lib.js",
"@whirlybird/gateway": "https://github.com/apacheli/whirlybird/raw/dev/core/gateway/lib.js",
"@whirlybird/http": "https://github.com/apacheli/whirlybird/raw/dev/core/http/lib.js",
"@whirlybird/interactions": "https://github.com/apacheli/whirlybird/raw/dev/core/interactions/lib.js",
"@whirlybird/util": "https://github.com/apacheli/whirlybird/raw/dev/core/util/lib.js",
"whirlybird": "https://github.com/apacheli/whirlybird/raw/dev/core/whirlybird/lib.js"
}
}If you are feeling a bit lazy, you can just import from npm:whirlybird or
npm:@whirlybird/http (not recommended).
Getting Started
A rather simple example:
import { Bot } from "whirlybird";
const token = globalThis.process?.env["BOT_TOKEN"] ?? Deno.env.get("BOT_TOKEN");
const bot = new Bot(token, {
intents: [
"GuildMessages",
"MessageContent",
],
});
bot.listen("MESSAGE_CREATE", async (message) => {
if (message.content === "!ping") {
await bot.createMessage(message.channelId, "pong!");
}
});
await bot.connect();The Bot interface provides high-level usability such as permission checking
(e.g. checks for BAN_MEMBERS before sending out a request) and interactions
handling.
Make sure to tick the message content intent option for your bot application.
You can also run the whirlybird CLI to initialize a new project:
$ ./node_modules/.bin/whirlybird init
$ deno run --allow-read --allow-write https://github.com/apacheli/whirlybird/raw/dev/core/whirlybird/init.jsA slightly more complex example:
import { WhirlyCache } from "@whirlybird/cache";
import { Gateway, GatewayIntents } from "@whirlybird/gateway";
import { Http } from "@whirlybird/http";
const token = globalThis.process?.env["BOT_TOKEN"] ?? Deno.env.get("BOT_TOKEN");
const cache = new Cache();
const http = new Http(token);
const gateway = new Gateway(token, "wss://gateway.discord.gg/?v=10", {
handle_event: async (event, data) => {
cache.update(event, data);
switch (event) {
case "MESSAGE_CREATE": {
if (data.content === "!ping") {
await http.createMessage(data.channel_id, {
content: "pong!",
});
}
break;
}
}
},
identify: {
intents: GatewayIntents.GuildMessages | GatewayIntents.MessageContent,
},
});
gateway.connect();See more examples here.
Warning whirlybird does not prefix your token. Make sure to prepend your token with
Bot $BOT_TOKEN!
Contributing and Development
Run these tools (or just let the CI do it):
Resources
Come hang out with us at our Discord server! You can also find me at the Discord API server.
