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

Create a Client and Handle Function

Next, create a handle function by passing a client factory to the createHandle function. The factory should return an array of plugins, the first being the client, and the rest being any other optional plugins you may want to add.

src/index.ts

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

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 handle = createHandle((env) => {
    const client = new Client(
        { ... },
        [new HelloCommand()]
    )
    return [client]
})

Automatic Setup

Manual Setup

Set Up a TypeScript Project

Install the Package

Create a Client and Handle Function

Create a Command

Use an Adapter

Cloudflare Workers

Next.js

Node.js

Bun

On this page