Cloudflare Workers

Learn how to set up and deploy your Carbon bot using Cloudflare Workers, including development and production environments.

Automatic Setup

Quickly set up your Carbon bot with minimal configuration using the automatic setup guide.

Other Runtimes

Explore how to set up and deploy your Carbon bot using different runtimes.

Manual Setup

This is a continuation of the Basic Setup guide. If you haven't already, make sure to follow the steps in the guide before proceeding.

Create a Fetch Handler

Using the @buape/carbon/adapters/fetch package, you can create a handler that you can then export for Cloudflare Workers. This server will handle incoming interactions and route them to your bot.

src/index.ts

import { createHandler } from '@buape/carbon/adapters/fetch'

const client = new Client( ... )

const handler = createHandler(client)
export default { fetch: handler }

To access environment variables globally in a Cloudflare Worker, Carbon uses a workaround by assigning the process.env object to the globalThis object before importing the main handler file. This approach allows you to access environment variables at the top level of your handler file, something that is not normally possible in Cloudflare Workers.

src/entry.ts

import type { ExecutionContext } from '@cloudflare/workers-types'

export default {
	fetch(req: Request, env: Record<string, string>, ctx: ExecutionContext) {
		Reflect.set(globalThis, 'process', { env })
		const handle = await import('./index.js')
		return handle.default.fetch(req, ctx)
	}
}

Add a Wrangler Configuration

You'll need to create a wrangler.toml file in the root of your project to configure your Cloudflare Worker to use the entry point file you created. This file should look something like this:

wrangler.toml

name = " ... "
main = "src/entry.ts"
compatibility_date = " ... "

Running in Development

Start a Proxy

Discord requires a public URL to route interactions to your project. To achieve this, you'll need to set up a proxy. The simplest way to do this is by using localtunnel. This created public URL will be referred to as PUBLIC_URL in the following steps.

npx localtunnel

pnpm dlx localtunnel

yarn dlx localtunnel

bunx localtunnel

You can use the --subdomain flag to specify a custom subdomain for your proxy.

Set Environment Variables

First things first, you'll need to grab your Discord application's secrets from the Developer Portal and paste them in your .dev.vars file.

Configure Portal URLs

Now that you have a public URL, navigate back to the Discord Developer Portal and set the "Interactions Endpoint URL" to <BASE_URL>/interactions.

Invite your App

You'll need to invite your app to your server to interact with it. To do so, navigate to the Installation tab of your app in the Discord Developer Portal.

Run the Bot

You can now run your bot using:

npm run dev

pnpm run dev

yarn run dev

bun run dev

Deploy Your Commands to Discord

Finally, to deploy your commands to Discord, navigate to <BASE_URL>/deploy?secret=<DEPLOY_SECRET> in your browser. This will send your command data to Discord to register them with your bot.

To deploy commands to specific guilds, add a guildIds property to your command classes with an array of guild IDs. To deploy all commands to certain guilds during development, set the devGuilds option in your client config (e.g., from an environment variable). Commands with guildIds are only available in those guilds; commands without are deployed globally. If devGuilds is set, all commands are deployed to those guilds instead of globally.

Deploying to Production

Prepare Environment

Before deploying your bot, you'll need to set your environment variables. This can be done using the Wrangler CLI.

npx wrangler secret put BASE_URL
npx wrangler secret put DISCORD_PUBLIC_KEY
npx wrangler secret put DISCORD_CLIENT_ID
npx wrangler secret put DISCORD_BOT_TOKEN

pnpm dlx wrangler secret put BASE_URL
pnpm dlx wrangler secret put DISCORD_PUBLIC_KEY
pnpm dlx wrangler secret put DISCORD_CLIENT_ID
pnpm dlx wrangler secret put DISCORD_BOT_TOKEN

yarn dlx wrangler secret put BASE_URL
yarn dlx wrangler secret put DISCORD_PUBLIC_KEY
yarn dlx wrangler secret put DISCORD_CLIENT_ID
yarn dlx wrangler secret put DISCORD_BOT_TOKEN

bunx wrangler secret put BASE_URL
bunx wrangler secret put DISCORD_PUBLIC_KEY
bunx wrangler secret put DISCORD_CLIENT_ID
bunx wrangler secret put DISCORD_BOT_TOKEN

Remember to configure your portal URLs to the URL of your Cloudflare Worker.

Deploy to Cloudflare

Once you've set your environment variables, you can deploy your bot with the following command:

npx wrangler deploy

pnpm dlx wrangler deploy

yarn dlx wrangler deploy

bunx wrangler deploy

Remember to deploy your commands to Discord using <BASE_URL>/deploy?secret=<DEPLOY_SECRET>.