Discord Hono

Install the core package using npm. If you are using TypeScript, you should also install discord-api-types for type definitions. You may also need @types/node depending on your environment.

npm i discord-hono
npm i -D discord-api-types # When using TypeScript
# npm i -D @types/node # As needed

The JsonBuilder has built-in logic for Discord's custom_id pattern. If your target type M contains both custom_id and custom_value, calling toJSON() will merge them into a single string.

• The format is: {custom_id}{SEPARATOR}{custom_value}.
• If custom_value is undefined, only custom_id is returned.
• If the resulting string exceeds 100 characters, an error is thrown.

This allows you to build complex interaction payloads easily while maintaining type safety for the individual components.

interface InteractionPayload {
  custom_id: string;
  custom_value: string;
  other: string;
}

const builder = createJsonBuilder<{}, InteractionPayload>({});

const payload = builder
  .custom_id("my_action")
  .custom_value("123")
  .other("data")
  .toJSON();

// Result: { custom_id: "my_action_123", other: "data" }

To use DiscordHono in a runtime like Cloudflare Workers, mount the .fetch method to your worker's entry point.

• GET requests: The .fetch method automatically responds with Operational🔥 for health checks.
• POST requests: The method handles signature verification using DISCORD_PUBLIC_KEY and routes the interaction to the appropriate handler based on the interaction type and custom_id or command name.
• Error Handling: If a handler is missing for a valid interaction, it throws a handler error (resulting in a 500 response). If signature verification fails, it returns a 401 response.

// Example Cloudflare Worker entry point
export default {
  fetch: (request, env, ctx) => app.fetch(request, env, ctx),
  scheduled: (event, env, ctx) => app.scheduled(event, env, ctx),
};

Use the DiscordHono class to define your bot's logic. You can register slash commands using the .command() method, which provides a context object c to send responses via c.res().

import { DiscordHono } from 'discord-hono'

const app = new DiscordHono()
  .command('hello', c => c.res('Hello, World!'))

export default app

To make your slash commands available in Discord, use the register function along with makeSlashCommand. You will need your DISCORD_APPLICATION_ID and DISCORD_TOKEN (typically from environment variables).

import { makeSlashCommand, register } from 'discord-hono'

const commands = [
  makeSlashCommand('hello', 'Hello, World!'),
]

register(
  commands,
  process.env.DISCORD_APPLICATION_ID,
  process.env.DISCORD_TOKEN,
  //process.env.DISCORD_TEST_GUILD_ID,
)

The Env interface defines how environment variables and bindings are structured in your application (e.g., in Cloudflare Workers).

• Bindings: An optional object containing environment bindings.
• Variables: An optional record of string-keyed environment variables.

export interface Env {
  Bindings?: object
  Variables?: Record<string, unknown>
}

When calling createJsonBuilder, you can provide an optional JsonBuilderOptions object to control how data is copied.

const builder = createJsonBuilder(initialData, { clone: true });

If you attempt to use createRest without a valid token, it will throw an error with the following details:

• Error Type: REST
• Error Code/Message: DISCORD_TOKEN

For grouping multiple choices, use:

• Radio Group: Use makeRadioGroup(custom_id, options) where options is an array of [value, label] tuples.
• Checkbox Group: Use makeCheckboxGroup(custom_id, options) where options is an array of [value, label] tuples.
• Single Checkbox: Use makeCheckbox(custom_id) for an individual checkbox.

// Radio Group
const radioGroup = makeRadioGroup('choice_id', [
  ['red', 'Red'],
  ['blue', 'Blue'],
]);

// Checkbox Group
const checkboxGroup = makeCheckboxGroup('prefs_id', [
  ['notifications', 'Enable Notifications'],
  ['updates', 'Get Updates'],
]);