Rhidium has been released! Even though this template will be maintained as a token of appreciation, you should definitely check our Rhidium. It's the upgraded, modern, version of this template - and all in TypeScript.

discord.js-bot-template

This is a bot template using discord.js for quickly and easily creating powerful Discord bots. You don't need much Javascript experience to get started on a project using this template. Not sure where to start? Come join my Discord Server, where I'll try and answer all the questions you have.

With Message Content Access becoming a privileged intent I thought I'd build a template where you're ready to start working on commands after installing it. This template currently doesn't listen to the messageCreate event. Update Slash Commands by using the /deploy command or altering the environmental variables. It also uses the latest Discord features, like auto-complete, buttons, modals, and other components.

Uses Semantic Release so you can easily determine if it's appropriate for you to update the bot

Showcase
Documentation
Features
Notes
Installation & Usage
- Prerequisites
- Docker
- Node
- Updating

Showcase / Projects using this template

Green Mountain Trader - over 300,000 users
DayZ Leaderboard bot
Create an issue if you want to have your project showcased here

Documentation

The client (bot) code is documented at djs.mirasaki.dev
The API is documented at djs.mirasaki.dev/api-docs
Source code is well documented with comments, explaining what's going on
With the use of JSDoc for client documentation, enjoy code-completion (IntelliSense) in your favorite code editor

Features

Dynamic Command Handler

This template comes with a powerful, yet simple to understand and modify, dynamic command handler. You can go straight to adding new commands without having to worry about client internals.
Message Content Access is becoming a privileged intent and that's why this template focuses on Discord's Application Commands. In fact, we don't even activity listen to the messageCreate event.
Every module in the command root folder will be loaded as a ChatInputCommand, taking care of default configuration.
1. Default command name is the name of the file without extension.
2. Default command category is the name of the parent folder.
Every module in the context-menus folder will be loaded as either a UserContextCommand or a MessageContextCommand, depending on which folder it's located in.
Deep nest to your heart's content. Deep nesting files in folders for all ChatInputCommand, and any API Components is supported for 25 levels.
Configure internal permission levels, and define any additional (optional) Discord permissions required to execute the command. Useful for Moderation tools.
Enable commands globally, restrict them to a single testing server, or even disable it all together if you've discovered a major bug in your code.
Throttle your command usage, configure a {{usages}} in {{duration}} cooldown to individual commands. With the 5 different available cooldown types (user, member, channel, guild, global), you can configure an appropriate cooldown for all your commands and components.
Configure aliases for all your Application Commands. (ChatInput, UserContextMenu, and MessageContextMenu)

Dynamic Component Handler

Ignores component actions where the custom id starts with @ - so you can use in-command listeners along side the built-in component handler
Supports, and uses, all the latest Discord API features, like buttons, modals, context-menus, select-menus, and is autocomplete-enabled!
The same configuration as your command files. Apply a cooldown to any component, and manage permissions and all the other configuration you're used to from this template.
Examples on how to implement all the different API components.
1. /info - User Context Menu Command, displays detailed information about the user. (Right-click a user -> Apps)
2. /print-embeds - Message Context Menu Command, grabs and prints raw Embed JSON data from a message and sends it to the member. (Right-click a message -> Apps)
3. Autocomplete-enabled /help command - The template is auto-complete enabled, just return an array of any size in the files run() function
4. /eval button-integration - Manage buttons and button-groups easily, and apply additional permissions and cooldown for all components. (except autocomplete)
5. /eval modal-integration - Manage modals, we have unique identifier declared in our constants file to make sure we use the same customId field across all components and different files. Not required, but strongly recommended.
6. /help select-menu-integration - Integrating seamlessly with the code in our main /help command

Dynamic Event Handler

Every file in the listeners folder will be registered as an event listener where the file name without extension is the name of the event. Creating a file named messageCreate.js will listen to the messageCreate event, achieving the same as using client.on(). It listens for events, not much more to say about it.

RESTful API

This template comes with a REST API (OpenAPI spec 3.0.0). By default, this only serves the client's command data, which can be used to easily fetch your command data and build a dynamic command table/overview on your personal website. As this project is meant to be newbie-friendly, I thought I would include a very basic API template, so new developers are free to play around with it without having to set-up anything themselves. Change USE_API to true in the env file to enable this feature.

Others

Supports VSCode IntelliSense for auto-complete during local development.
Uses Discord's Autocomplete API, and showcases it in the /help command.
All the template files have comments explaining what's going on, making it easy for new JavaScript developers to jump in.
Comes with a utility file, which exports utility functions to make your common tasks easier/faster.
Extensions to discord.js have been containerized. Everything is documented in the typings file, or check out the client-extension file, which is served as client.container.
Automatically (environmental variable dependent) deploy changes to your API commands, or use the /deploy command.

Notes

Don't like the folder structure? Jump into the environmental file and configure where your commands and components are loaded from
Every embed color code and emoji are grabbed from their respective configuration file, meaning you can personalize the bot without having to go over a plethora of files
Comes with a constants file to manage your unique ids and previously hard-coded values
Comes with many example scripts for pm2 and docker, including a docker development build - to get you started using these awesome services
And lastly...

You don't have to use the built-in component command (buttons, modals, etc) handler. Alternatively, you can use the following (vanilla discord.js) code to achieve the same, but within a ChatInput/UserContextMenu/MessageContextMenu command file:

// In any scope with a valid interaction object
const { ComponentType } = require('discord.js');
// Fetching the message attached to the received interaction
const interactionMessage = await interaction.fetchReply();

// Button reply/input collector
const acceptEvalCollector = interactionMessage.createMessageComponentCollector({
    filter: (i) => (
        // Filter out custom ids
        i.customId === 'customId' || i.customId === 'customIdTwo'
    ) && i.user.id === interaction.user.id, // Filter out people without access to the command
    componentType: ComponentType.Button,
    time: 60000
});

// And finally, running code when it collects an interaction (defined as "i" in this callback)
acceptEvalCollector.on('collect', (i) => { /* The callback to run */ });

Installation & Usage

Prerequisites

A Discord Bot account
1. Head over to the page linked above
2. Click "New Application" in the top right
3. Give it a cool name and click "Create"
4. Click "Bot" in the left hand panel
5. Click "Add Bot" -> "Yes, do it!"
6. Click "Reset Token" and copy it to your clipboard, you will need it later

If you're planning on hosting the backend, be sure to run the command npm run docs after installing, otherwise the root/index at http://localhost:3000/ will return a 404 | Not Found error.

Run as a Docker container (preferred)

The quickest, and easiest, way to host/use this bot is by deploying it inside of a Docker container.

Clone this repository: git clone https://github.com/Mirasaki/discord.js-bot-template.git
Navigate inside the new folder: cd discord.js-bot-template
Rename .env.example to .env and provide your environmental variables
Rename config.example.js to config.js and provide your configuration
- Alternatively, you can now use the docker compose up command to finish setting up the project if you have the Docker Compose CLI installed
Build the project: docker build --tag my-discord-bot .
Start the bot: docker run -it --env-file .env --name my-discord-bot mirasaki/discord-bot-template:main

There's a plethora of Docker scripts included in the /package.json file, including a development environment - take a look to get started if you've never used Docker before!

Run as a plain NodeJS app

Prerequisites

NodeJS (if you're running as a plain NodeJS app)
1. Head over to the download page
2. Download the current build (latest features) available for your OS
3. Be sure to check the box that says "Automatically install the necessary tools" when you're running the installation wizard

You can also clone this repository or download a release, and host the project directly. You will need Node/NodeJS (Be sure to check the box that says "Automatically install the necessary tools" when you're running the installation wizard)

Head over to the download page
- Alternatively, clone this repository by using git clone https://github.com/Mirasaki/discord.js-bot-template.git and skip to step 4 if you have Git installed.
Download either the zip or zip.gz source code
Extract it using your favorite zip tool
Open a new console/terminal/shell window in the newly created project folder.
Run npm i --include-dev to install all dependencies, including development dependencies.
Rename .env.example to .env and configure your environmental variables
Rename config.example.js to config.js and go through your bot configuration
Use the command node . to start the application, or alternatively:
- npm run start to keep the process alive with PM2, suitable for production environments. (npm i -g pm2 to install)
- npm run start:dev if you have nodemon installed for automatic restarts on changes, suitable for development environments.

Updating

This project uses Semantic Release so you can update your own bot to the new standards of the template using a relatively simple and easy workflow:

Add a new remote repository, called upstream here
- git remote add upstream git@github.com:Mirasaki/discord.js-bot-template.git
Pull changes from the upstream repo:
- git pull upstream main --allow-unrelated-histories
- --allow-unrelated-histories is a dangerous flag, and you should only use this if you know what you're doing!
- Now, you should see some merge conflicts - I recommended resolving the merge in the VSCode Merge Editor
- If you just want it to download the changes without automatically merging, use git fetch instead of git pull
If you want to disable/prevent pushing to the remote repository, set the push URL to an invalid URL using something like
- git config remote.upstream.pushurl "PREVENTS_PUSH_TO_REMOTE_UPSTREAM"

That's it! You're done! If you know of a better workflow to pull remote changes, like git merge -/- --squash etc (not ideal) - please let us know by creating an issue or pull request.

Open source, self-hosted, and MIT licensed, meaning you're in full control.

Mirasaki/discord.js-bot-template

discord.js-bot-template

Table of Contents

Showcase / Projects using this template

Documentation

Features

Dynamic Command Handler

Dynamic Component Handler

Dynamic Event Handler

RESTful API

Others

Notes

Installation & Usage

Prerequisites

Run as a Docker container (preferred)

Run as a plain NodeJS app

Prerequisites

Updating