Installation

From quickstart

1. Create github repo from template

   Go to the quickstart repository and click on the Use this template button.

2. Install dependencies

   bun install

3. Setup environment variables

   Rename the .env.example file to .env and set your Discord bot token (Discord Developer Portal):

   TOKEN=your_discord_bot_token

4. Start your bot

   bun run start

From scratch

Set up a new djs-core project from scratch with complete control over your project structure.

1. Initialize your project

   Create a new Bun project:

   bun init

   This creates a basic package.json and initializes your project structure.

2. Install dependencies

   Install djs-core packages:

   bun i -D @djs-core/dev
   bun i @djs-core/runtime discord.js

   • @djs-core/dev is a dev dependency providing build tools and CLI commands
   • @djs-core/runtime is the runtime library containing the framework logic
   • Make sure you also have discord.js installed: bun i discord.js

3. Add scripts to package.json

   Add the following scripts to your package.json:

   {
     "scripts": {
       "dev": "djs-core dev",
       "build": "djs-core build",
       "start": "djs-core start",
       "check": "djs-core check",
       "test": "djs-core test"
     }
   }

   devscript

   Runs the bot in development mode with hot reload for handlers under src/ (restart manually after djs.config.ts changes)

   buildscript

   Compiles TypeScript to JavaScript in the dist/ folder for production

   startscript

   Runs the compiled bot from the dist/ folder (use after build)

   checkscript

   Lints src/ for djs-core anti-patterns (djs-core check)

   testscript

   Runs colocated bun:test suites via djs-core test

4. Create configuration file

   Create a djs.config.ts file in your project root:

   import type { Config } from "@djs-core/dev";
   
   if (!process.env.TOKEN) {
     throw new Error("TOKEN environment variable is required");
   }
   
   export default {
     token: process.env.TOKEN,
     servers: ["YOUR_GUILD_ID"],
   } satisfies Config;

   tokenstring

   Your Discord bot token from the Discord Developer Portal

   serversstring[]

   Array of guild (server) IDs where commands should be registered. Use an empty array [] for global commands (takes up to 1 hour to propagate).

   Never commit your bot token to version control! Store it in a .env file and add .env to your .gitignore.

5. Setup environment variables

   Create a .env file in your project root:

   TOKEN=your_discord_bot_token_here

   Make sure to add .env to your .gitignore:

   .env
   node_modules/
   dist/

6. Create your first command

   Create the directory structure and your first command at src/interactions/commands/ping.ts:

   import { Command } from "@djs-core/runtime";
   
   export default new Command()
     .setDescription("Ping the bot")
     .run(async (interaction) => {
       await interaction.reply("Pong!");
     });

   The command name is automatically derived from the file path. src/interactions/commands/ping.ts becomes /ping in Discord.

7. Start your bot

   Run your bot in development mode:

   bun run dev

   Your bot should now be online and the /ping command should be available in Discord!

   In development mode, commands are automatically registered when the bot starts. You’ll see console output indicating which commands were registered.

Next Steps

Now that your bot is set up, here’s what to explore next: