Honocord - Imagine an interactions bot
Honocord is a powerful, type-safe library for building Discord bots using interactions with the Hono web framework.
No, this ain't abandoned - I'm just busy with other projects and life stuff. If you want something added or want to help out, open an issue or PR and I'll try to get to it when I can. Thanks for understanding!
Contents
- What is Honocord?
- Key Features
- Install
- Usage
- Getting Help
- Examples
- Testing
- Contributing
- Caveats
- License
What is Honocord?
Honocord bridges Discord's Interaction API with Hono's lightweight web framework, allowing you to build fast, serverless Discord bots that run on edge platforms like Cloudflare Workers, or traditional Node.js environments.
Key Features
- Edge-First Design - Optimized for Cloudflare Workers with async interaction handling
- Fully Type-Safe - Built with TypeScript using
discord-api-typesfor excellent type safety (I hope at least) - Handler-Based Architecture - Clean, modular system for commands, components, modals, and webhooks
- Hono Integration - Leverages Hono's lightweight, fast routing capabilities
- Flexible Deployment - Works with Cloudflare Workers, Bun, Node.js, and more
- Rich Builders - Re-exports Discord.js builders for creating embeds, buttons, modals, and more
- Autocomplete Support - Built-in autocomplete helper for slash commands
- Secure by Default - Automatic signature verification for Discord interactions and webhooks
- Direct Webhook Support - Handle Discord webhook events alongside interactions
- Caching Support - Caching system with adapters for in-memory, Durable Objects, Mongo and custom implementations
Disclaimer: Yes, AI helped me build this - with the focus on helped.
Refer to the docs for detailed guides, API reference, and examples.
Also get familiar with Discord.js and Discord API Concepts.
Install
pnpm add honocord hono
# or: npm install honocord hono / bun add honocord hono
hono is a peer dependency. mongoose is an optional peer dependency, only needed for
honocord/cache/mongo. Requires Node.js 24+ (or Cloudflare Workers / Bun).
Usage
import { Honocord, SlashCommandHandler } from "honocord";
export const pingCommand = new SlashCommandHandler()
.setName("ping")
.setDescription("Replies with Pong!")
.addHandler(async (interaction) => {
await interaction.reply("š Pong!");
});
const bot = new Honocord();
bot.loadHandlers(pingCommand);
// POST / and POST /interactions handle Discord interactions
export default bot.getApp();
Honocord reads DISCORD_PUBLIC_KEY and DISCORD_TOKEN from the Hono context's env bindings.
Register commands with registerCommands(token, applicationId, ...handlers). The
Quick Start covers the full setup.
Getting Help
If you encounter issues or have questions:
- Check the Examples repo
- Review the documentation pages
- Open an issue on GitHub
Examples
Browse the Examples repo for complete, working implementations:
- cloudflare-workers - Bot on Cloudflare Workers with commands, autocomplete, buttons, modals, context menus, middleware and Durable Object caching
- node-server - Integration with an existing Hono app on Node.js, with in-memory caching
- webhook-events - Handling Discord webhook events on Cloudflare Workers and sending files with
AttachmentBuilder - dynamic-commands - Per-guild custom commands created at runtime, handled by dynamic command handlers
Testing
Tests are located in src/tests/ and follow the directory structure of the modules they test:
src/
āāā tests/
ā āāā interactions/
ā ā āāā BaseInteraction.test.ts
ā āāā utils/
ā āāā Autocomplete.test.ts
āāā interactions/
āāā utils/
āāā ...
Run tests with:
pnpm test # Run all tests
pnpm test --watch # Run in watch mode
Tests use Vitest for fast unit testing with TypeScript support.
Contributing
See CONTRIBUTING.md and CONVENTIONS.md. Releases are described in RELEASING.md.
The repository is organized as a monorepo with the following structure:
src/- Core Honocord library, including the cache adapters (src/cache, exposed ashonocord/cache,honocord/cache/memory,honocord/cache/doandhonocord/cache/mongo)docs/- Documentation site (Astro)
Building
pnpm build # Build the root package
pnpm typecheck # Type check the root package
The package uses tsdown for zero-config builds.
Caveats
- Interactions and webhook events only: there is no Gateway connection, so no presence, message events or other gateway events.
- On Cloudflare Workers, handlers run after the response via
waitUntiland are bound by Workers CPU and duration limits. reply()anddeferReply()are ephemeral by default; passfalseas the second argument for a public reply.- The in-memory cache adapter does not work on Workers, and the Durable Object adapter only works on Workers.
License
MIT The-LukeZ