Basic Usage

How to set up and configure a Carbon project, including both automatic and manual setup methods.

Automatic Setup

We recommend starting a new Carbon project using create-carbon, which will set everything up automatically for you. To create a project, run:

npx create-carbon@latest

You'll be prompted to enter a project name, select a runtime, and configure some other options. Once you've answered all the questions, create-carbon will generate a new project for you.

Manual Setup

If you prefer to set up a Carbon project manually, follow the steps below:

Set Up a TypeScript Project

First, set up a new TypeScript project. You can follow the official TypeScript Handbook for detailed instructions on how to get started.

Install the Package

Let's start by adding Carbon to your project:

npm install @buape/carbon

Next, create a new client instance by importing the Client class from the @buape/carbon package. The client requires a configuration object with your bot's credentials and an array of commands to register.

src/index.ts

import { Client } from "@buape/carbon";
 
const client = new Client({
  baseUrl: process.env.BASE_URL,
  deploySecret: process.env.DEPLOY_SECRET,
  clientId: process.env.DISCORD_CLIENT_ID,
  publicKey: process.env.DISCORD_PUBLIC_KEY,
  token: process.env.DISCORD_TOKEN,
}, [])

The deploySecret is your own secret key used to verify requests to protected endpoints, such as the deploy commands endpoint, an endpoint that you do not want to be spammed. Setting environment variables will be covered in a later step.

Create a Command

Now we'll create a simple command that responds with "Hello!" when invoked. This command will serve as a basic example to demonstrate how to set up and handle interactions with your bot.

src/commands/hello.ts

import { Command, type CommandInteraction } from "@buape/carbon";
 
export default class HelloCommand extends Command {
  name = "hello";
  description = "Say hello to the bot";
 
  async run(interaction: CommandInteraction) {
    await interaction.reply("Hello!");
  }
}

Then, mount the command to your client to make it available for use. This step involves importing the command and adding it to the client's configuration.

src/index.ts

import HelloCommand from './commands/hello'
 
const client = new Client(
  { ... },
  [new HelloCommand()]
)

Automatic Setup

Manual Setup

Set Up a TypeScript Project

Install the Package

Create a Client

Create a Command

Use an Adapter

Cloudflare Workers

Next.js

Node.js

Bun

More

On this page