gnukbot

A Discord bot written in TypeScript with discord.js v14 and a hexagonal architecture.

What it does

gnukbot exposes slash commands for greeting, fun replies, and trivia.

Requirements

• Node.js 24.x or newer
• A Discord application with a bot user
• A bot token
• The application client ID
• Optionally, a Discord guild ID for faster command registration during development

Setup and usage

Create a .env file from .env.example, fill in the Discord credentials, and configure the bot in the Discord Developer Portal. The bot uses the bot and applications.commands scopes.

If no .env file is present, the bot reads DISCORD_TOKEN, DISCORD_CLIENT_ID, and DISCORD_GUILD_ID directly from the process environment (useful for non-dev installs and hosting platforms).

This project uses mise as the preferred entry point for local development. The available tasks are defined in mise.toml.

Build and package

The build output is generated in dist/ and can be packaged as an npm tarball in one flow through the mise tasks.

The published package exposes a CLI command named gnukbot.

Bot permissions

Keep permissions as small as possible when generating the invite URL from the Developer Portal. For the current feature set, the bot only needs View Channels, Send Messages, and Embed Links.

Project structure

src/
  domain/       # framework-free business logic
  primary/      # inbound Discord adapters
  secondary/    # outbound adapters
  index.ts      # bootstrap and Discord client startup
tests/          # mirrors src/

Notes

• The codebase follows a hexagonal architecture: primary adapters depend on the domain, and the domain never depends on Discord or infrastructure.
• The package is licensed under MIT.
• Tests are written with Vitest.
• Coverage is expected to stay at 100%.