Discord Bot TypeScript Template

Discord bot - A discord.js bot template written with TypeScript.

Introduction

This template was created to give developers a starting point for new Discord bots, so that much of the initial setup can be avoided and developers can instead focus on meaningful bot features. Developers can simply copy this repo, follow the setup instructions below, and have a working bot with many boilerplate features already included!

For help using this template, feel free to join our support server!

Features

Built-In Bot Features:

• Basic command structure.
• Rate limits and command cooldowns.
• Welcome message when joining a server.
• Shows server count in bot status.
• Posts server count to popular bot list websites.
• Support for multiple languages.

Developer Friendly:

• Written with TypeScript.
• Uses the discord.js framework.
• Built-in debugging setup for VSCode.
• Written with ESM for future compatibility with packages.
• Support for running with the PM2 process manger.
• Support for running with Docker.

Scales as Your Bot Grows:

• Supports sharding which is required when your bot is in 2500+ servers.
• Supports clustering which allows you to run your bot on multiple machines.

Commands

This bot has a few example commands which can be modified as needed.

Help Command

A /help command to get help on different areas of the bot or to contact support:

Info Command

A /info command to get information about the bot or links to different resources.

Test Command

A generic command, /test, which can be copied to create additional commands.

Dev Command

A /dev command which can only be run by the bot developer. Shows developer information, but can be extended to perform developer-only actions.

Welcome Message

A welcome message is sent to the server and owner when the bot is added.

Setup

1. Copy example config files.
   • Navigate to the config folder of this project.
   • Copy all files ending in .example.json and remove the .example from the copied file names.
     • Ex: config.example.json should be copied and renamed as config.json.
2. Obtain a bot token.
   • You'll need to create a new bot in your Discord Developer Portal.
     • See here for detailed instructions.
     • At the end you should have a bot token.
3. Modify the config file.
   • Open the config/config.json file.
   • You'll need to edit the following values:
     • client.id - Your discord bot's user ID.
     • client.token - Your discord bot's token.
   • Optional: replyBudget limits how much work Markov does before replying. He can chain up to maxToolRounds tool rounds per reply until he has used maxOutputTokens output tokens (reasoning included) or wrapUpAfterMs has passed; after that he has to answer. The budget is checked between rounds, so the round that crosses it and the final answer can go past maxOutputTokens. timeoutMs is the hard abort for the whole reply. kagi.maxToolRounds still caps how many of those rounds can use web research.
   • Intent detection (whether Markov replies to an unpinged mention or reacts to a message) runs on TypeSafe's Jev model. Provide TYPESAFE_API_KEY (or typesafe.apiKey); without a valid key Markov only replies to pings, replies, and DMs, and never reacts. Jev is text-only, so image messages are gated on their caption, and image posts without text get no reaction. typesafe.intentThresholds.reply and .react are the minimum yes-probabilities; tune them with npm run eval.
4. Install packages.
   • Navigate into the downloaded source files and type npm install.
   • To enable Kagi-backed web research, set kagi.enabled to true and provide KAGI_API_KEY (or kagi.apiKey). API keys from the environment take precedence over the config file.
   • Web research also requires moderation.webAssisted.enabled so every web-assisted reply is checked with OpenAI Moderation before it is sent.
   • Kagi search and extraction are billed separately by Kagi. Markov applies per-message and per-process safety limits; sharded processes have independent limits.
   • Markov stores the visible source links in the normal Discord context, but does not log or persist raw Kagi snippets/page Markdown. The existing OpenAI Responses conversation chain uses server-side response storage for previous_response_id, so enabling web research sends extracted content through that provider chain.
   • Set KAGI_ENABLED=false or kagi.enabled to false and restart the bot to disable new web requests.
   • To let Markov compose songs, install FluidSynth, ffmpeg, and a General MIDI soundfont (Ubuntu: sudo apt install fluidsynth ffmpeg fluid-soundfont-gm), then set music.enabled to true and point music.soundfontPath at the .sf2 file. Larger banks such as GeneralUser GS or Timbres of Heaven sound noticeably better. Songs are arranged from sections with per-track mixing, swing, and humanized timing, then rendered locally and attached as .mp3 and .mid files.
5. Register commands.
   • In order to use slash commands, they first have to be registered.
   • Important: Choose ONE approach (global OR guild-specific). Having both will show duplicate commands!
   • Global commands (recommended for production):
     • Type npm run commands:register to register commands globally.
     • Commands will appear in all servers, but may take up to 1 hour to propagate.
     • Run this script any time you change a command name, structure, or add/remove commands.
     • To clear guild-specific commands: npm run commands:clear <GUILD_ID> for each guild
   • Guild-specific commands (recommended for development/testing):
     • Type npm run commands:register <GUILD_ID> to register commands to a specific server.
     • Commands appear instantly in that server (no waiting period).
     • Replace <GUILD_ID> with your Discord server's ID (right-click server → Copy Server ID).
     • Example: npm run commands:register 123456789012345678
     • To clear global commands: npm run commands:clear (no guild ID)
   • View registered commands:
     • npm run commands:view - View global commands
     • npm run commands:view <GUILD_ID> - View guild-specific commands
   • Clear commands:
     • npm run commands:clear - Clear all global commands
     • npm run commands:clear <GUILD_ID> - Clear all guild-specific commands for a server

Start Scripts

You can run the bot in multiple modes:

1. Normal Mode
   • Type npm start.
   • Starts a single instance of the bot.
2. Manager Mode
   • Type npm run start:manager.
   • Starts a shard manager which will spawn multiple bot shards.
3. PM2 Mode
   • Type npm run start:pm2.
   • Similar to Manager Mode but uses PM2 to manage processes.

Bots Using This Template

A list of Discord bots using this template.

Bot	Servers
Birthday Bot
QOTD Bot
Friend Time
Bento
NFT-Info
Skylink-IF
Topcoder TC-101

Don't see your bot listed? Contact us to have your bot added!