Discraft NPM | npm.io

Discraft is a modern, developer-friendly framework for building Discord bots with ease. It provides a robust CLI and a set of tools to streamline the development process, allowing you to focus on creating amazing bot experiences. Think of it as a "batteries-included" approach, letting you get started quickly and efficiently. It's like Next.js for Discord bots.

Note: If you are viewing this documentation on npm, check out the GitHub repository for more up-to-date documentation.

Looking for instructions on how to deploy to Vercel? Check out the Vercel Deployment Guide.

🚀 Getting Started

Installation

You can install Discraft locally in your project using npm, which is recommended for project-specific dependencies:

npm install discraft --save-dev

Alternatively, you can install Discraft globally to use the CLI from any directory:

npm install -g discraft

When installed globally, you can use the discraft command directly instead of npx discraft.

Creating a New Project

To get started quickly, use the discraft init command:

npx discraft init

Or, if Discraft is installed globally:

discraft init

This will guide you through creating a new Discraft bot project, asking for details such as the project directory, package manager, and template.

After initialization, you will need to copy the .env.example file to .env and then edit the .env file with your bot token and client ID.

# From `Bot > Token` | https://discord.com/developers/applications
DISCORD_TOKEN=''
# From `General Information > App ID` | https://discord.com/developers/applications
DISCORD_APP_ID=''

You can also specify options directly:

npx discraft init -d my-bot-dir -p bun -t ts # Initialize a project in 'my-bot-dir' using bun and the typescript template

See the CLI Reference for all options.

Running Your Bot

After creating your project, navigate into the project directory and use the following commands.

To start your bot in development mode:

npx discraft dev

Or, if Discraft is installed globally:

discraft dev

To start your bot in production mode:

npx discraft start

Or, if Discraft is installed globally:

discraft start

⚙️ Core Features

Discraft offers a range of features designed to make Discord bot development a breeze.

Command System

Discraft uses the Discord.js API to create robust slash commands, as well as message and user context menu commands. Place your command files in the commands directory, and Discraft will automatically register them with Discord on bot startup.

See examples of commands here.

Event Handling

Discraft simplifies registering event handlers. Place your event files in the events directory, and Discraft will register them when the bot starts.

Example event handler (events/ready.ts, which will be registered when the bot starts):

import { ActivityType, Client, Events } from "discord.js";
import { logger } from "../utils/logger";

export default {
  event: Events.ClientReady,
  handler: (client: Client) => {
    if (!client.user) {
      logger.error("Client user is not set.");
      return;
    }
    client.user.setPresence({
      activities: [
        {
          name: "Discraft",
          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
          // @ts-ignore Discord.js does not have this property, but it is valid
          state: "Created with Discraft",
          type: ActivityType.Custom,
        },
      ],
      status: "online",
    });
    logger.success("Client logged in.");
  },
};

See examples of more events here.

Hot Reloading

During development, Discraft supports hot reloading, meaning that your changes to command and event files will automatically restart your bot with the changes reflected. This allows for a more efficient and streamlined development process.

Flexible Build Options

Discraft allows you to choose your preferred builder when building and running your application in development mode.

esbuild: A fast and efficient JavaScript bundler.
bun: A fast all-in-one toolkit for JavaScript and Typescript

💻 CLI Reference

Discraft provides a set of powerful CLI commands to manage your bot development.

`discraft init`

Initializes a new Discraft project.

Options:

-d, --dir <directory>: Specify the project directory (defaults to current directory).
-p, --package-manager <pm>: Package manager to use (npm, yarn, pnpm, bun, or none).
--skip-install: Skip dependency installation.
-t, --template <template>: Template to use (js, ts, or vercel-ts-ai). Defaults to prompt.

Example:

npx discraft init -d my-bot -p bun --skip-install -t ts

Or, if Discraft is installed globally:

discraft init -d my-bot -p bun --skip-install -t ts

`discraft dev`

Starts the bot in development mode with hot reloading.

Options:

-b, --builder <builder>: Specify the builder to use (esbuild or bun). Defaults to auto-detect.
-r, --runner <runner>: Specify the runner to use (node or bun). Defaults to auto-detect.
-c, --clear-console: Clear the console on each rebuild.

Example:

npx discraft dev -b esbuild -r bun -c

Or, if Discraft is installed globally:

discraft dev -b esbuild -r bun -c

`discraft build`

Builds the bot for production.

Options:

-b, --builder <builder>: Specify the builder to use (esbuild or bun). Defaults to auto-detect.

Example:

npx discraft build -b bun

Or, if Discraft is installed globally:

discraft build -b bun

`discraft start`

Starts the bot in production mode.

Options:

-r, --runner <runner>: Specify the runner to use (node or bun). Defaults to auto-detect.

Example:

npx discraft start -r node

Or, if Discraft is installed globally:

discraft start -r node

`discraft vercel build`

Builds the bot for deployment on Vercel. This command is a subcommand of discraft vercel.

Options:

-b, --builder <builder>: Specify the builder to use (esbuild or bun). Defaults to auto-detect.

Example:

npx discraft vercel build -b bun

Or, if Discraft is installed globally:

discraft vercel build -b bun

`discraft exec build`

Builds a standalone executable of your bot. This command is a subcommand of discraft exec.

Important notes:

You must run discraft build before running discraft exec build.
This command only works with the JavaScript and TypeScript templates (not the Vercel template).
The .env file should be in the same directory as the executable or the bot won't start.

Options:

--target <target>: Target platform for executable. Supported targets:
- linux-x64
- linux-arm64
- windows-x64
- darwin-x64
- darwin-arm64
--entry <entry>: Custom entry point (defaults to dist/index.js).
--outfile <outfile>: Output file name (defaults to dist/discraft-bot).

Targets:

Target	OS	Architecture
linux-x64	Linux	x64
linux-arm64	Linux	arm64
windows-x64	Windows	x64
darwin-x64	macOS	x64
darwin-arm64	macOS	arm64

You can find more information about targets in the Bun documentation.

Example:

npx discraft exec build --target linux-x64

Or, if Discraft is installed globally:

discraft exec build --target linux-x64

🚀 Deploying to Vercel

Check out the Vercel Deployment Guide for a more detailed, step-by-step guide.

To deploy your Discraft bot to Vercel, follow these steps:

Create a Vercel Project: If you haven't already, create a new project in your Vercel dashboard. You can import your project from GitHub, GitLab or Bitbucket.
Set Environment Variables: In your Vercel project settings, go to "Environment Variables" and add the following variables:
- DISCORD_TOKEN: Your Discord bot's token.
- DISCORD_APP_ID: Your Discord application's ID.
- For AI templates:
  - GOOGLE_AI_API_KEY: Your Google AI API key.
  - GOOGLE_AI_MODEL: The Google AI model you wish to use (e.g., gemini-2.0-flash-exp). You can find the project settings here.
Run a Discraft Vercel Build: In your project directory, run npm run vercel-build or discraft vercel build to create the API routes and files for your bot. This command prepares your bot for serverless deployment by generating the necessary API routes.
Deploy: You can deploy your bot to Vercel by running npm run deploy or using the vercel CLI. If using the CLI, you can run vercel and select the project you created. If you imported your project from a git repo, it should automatically deploy on commits. You can now set your bot's interactions endpoint to the https://<your-project>.vercel.app/api url.
- To setup the interactions endpoint, please see the 'Discord Bot Setup' section of the Vercel + TypeScript + Google AI template README.

📁 Project Structure

A typical Discraft project is structured as follows:

my-discraft-bot/
├── .discraft/            # Internal Discraft files (auto-generated)
├── clients/             # Discord.js client setup
│   └── discord.ts       # Discord.js client configuration
├── commands/            # Your bot's command files
│   ├── ping.ts           # Example ping command
│   └── ...             # Other commands
├── events/              # Event handlers
│   ├── error.ts          # Error handling
│   ├── messageCreate.ts  # Example message handler
│   └── ready.ts          # Client ready handler
├── utils/               # Utility functions
│   └── logger.ts        # Logging configuration
├── index.ts             # Main entry point for the bot
├── package.json         # Project dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── .env                 # Environment variables (e.g., bot token)

🛠️ Development

Dependencies

Discraft relies on the following key dependencies:

discord.js: A powerful JavaScript library for interacting with the Discord API.
commander: A library for building command-line interfaces.
consola: A modern console logger.
esbuild or bun: Fast JavaScript bundlers.
dotenv: To load environment variables.
chokidar: File watcher.
fs-extra: Extra file system methods.
glob: File globbing.
clack: Interactive CLI prompts.
kleur: Colorful console output.
- All of these are included as dependencies to discraft itself.

Configuration

Store your bot's token and client ID in a .env file at the root of your project:

DISCORD_TOKEN=your_bot_token_here
DISCORD_APP_ID=your_client_id_here

Commands and Events

Command files are located in the commands directory. They export an object with data and execute properties.
Event files are located in the events directory. They export an object with event and handler properties.