@eliware/discord

An ESM-first Discord app framework for Node.js, with built-in support for slash commands, localization, and event-driven architecture.

Table of Contents

• Features
• Requirements
• Installation
• Usage
  • ESM Example
• API
• TypeScript
• Errors / Troubleshooting
• Development
• Security
• Support
• License
• Links

Features

• Simple, opinionated Discord app setup for Node.js
• Slash command registration and handler auto-loading
• Event handler auto-loading for all Discord Gateway events
• Built-in localization system with easy locale file management
• TypeScript type definitions included
• Application-owned commands, events, and locales live in the consuming project (see @eliware/discord-template for a starter layout)
• Dependency injection and testability for all major components
• Logging and error handling hooks
• Extensible and modular directory structure

Requirements

• Node.js 26 or newer
• A Discord application, bot token, and configured intents for live connections

Installation

npm install @eliware/discord

Usage

ESM Example

import { createDiscord } from '@eliware/discord';

try {
  await createDiscord({
    intents: { Guilds: true }
  });
} catch (err) {
    console.error('Failed to start app:', err);
}

Set DISCORD_CLIENT_ID and DISCORD_TOKEN in the process environment before starting the application. The library does not load .env files itself; an application may use its own environment or dotenv setup. Gateway intents are disabled by default, so enable only the intents the application needs. The Discord developer portal must also allow privileged intents such as MessageContent, GuildMembers, and GuildPresences.

API

createDiscord(options): Promise<DiscordClient>

Creates and logs in a Discord client, auto-registers commands, loads event handlers, and sets up localization.

Options:

• clientId (string): Discord application client ID (required)
  • client_id remains supported as a compatibility alias
• token (string): Discord bot token (required)
• log (Logger): Logger instance (optional)
• rootDir (string): Root directory for events, commands, and locales (default: autodetect)
• localesDir (string): Directory for locale files (default: <rootDir>/locales)
• commandsDir (string): Directory for command definitions and handlers (default: <rootDir>/commands)
• eventsDir (string): Directory for event handlers (default: <rootDir>/events)
• intents (object): Discord Gateway Intents. All intents are disabled by default and must be explicitly enabled.
• partials (object): Partial flags keyed by Discord.js partial name (default: Message, Channel, and Reaction)
• clientOptions (object): Additional Discord.js client options
• ClientClass (constructor): Custom Discord.js Client class (for testing)
• setupEventsFn, setupCommandsFn, registerCommandsFn, setupLocalesFn: Dependency injection for advanced use/testing
• context (object): Additional arbitrary data to be injected into all event and command handlers

Returns: A logged-in Discord.js Client instance with an idempotent shutdown() method. Call await client.shutdown() during application cleanup.

splitMsg(msg, maxLength = 2000): string[]

Splits a message into chunks of up to maxLength characters, attempting to split at newlines or periods for readability.

• msg (string): The message to split
• maxLength (number, optional): The maximum length of each chunk (default: 2000)
• Returns: An array of message chunks, each no longer than maxLength.

purgeCommands(options): Promise<void>

Deletes all registered application commands. Without guildId, it deletes global commands; with guildId, it deletes commands for that guild. It requires clientId and token (or the corresponding environment variables). This is a destructive administrative operation and is never run automatically by createDiscord().

Command and Event Structure

• Commands: Place .json definitions and matching .mjs handlers in the configured commandsDir.
• Events: Place .mjs handlers in the configured eventsDir, named after Discord Gateway events (e.g., ready.mjs, messageCreate.mjs).

Localization

• Place locale files in the configured localesDir (e.g., en-US.json, es-ES.json).
• Each file should be a flat key-value JSON object for that locale.

TypeScript

Type definitions are included and cover all public APIs and options:

import type { CreateDiscordOptions, DiscordClient } from '@eliware/discord';

declare function createDiscord(options?: CreateDiscordOptions): Promise<DiscordClient>;

Errors / Troubleshooting

createDiscord() requires a valid application client ID and bot token. Connection, command-loading, event-loading, and localization failures are surfaced through the configured logger. Keep credentials out of source control and use dependency injection for tests. Process signal and exception integrations are opt-in; call the client shutdown method during application cleanup.

Development

npm test
npm run lint
npm run typecheck
npm audit --omit=dev --audit-level=moderate
npm run pack

Tests inject Discord client and loader dependencies, so a live Discord connection is not required.

Security

Keep Discord tokens and application credentials in environment variables or secret storage. Do not log tokens, credential-bearing URLs, private data, or full sensitive event payloads. Review intents and permissions before deployment.

Support

For help, questions, or to chat with the author and community, visit:

eliware.org on Discord

License

MIT © 2025 Eli Sterling, eliware.org

Links

• Home Page
• GitHub (Module)
• GitHub (Org)
• GitHub (Personal)
• npm
• Discord

Complete example

For a complete working application, see the @eliware/discord-template repository. It demonstrates commands, events, locales, testing, Docker, and systemd deployment. This package README focuses on the reusable library API.

Lifecycle integrations

Process integrations are opt-in:

await createDiscord({
  signals: true,
  processHandlers: true,
  signalOptions: { exit: false },
  processHandlerOptions: { events: ['uncaughtException', 'unhandledRejection'] }
});

Signal and process-handler registrations are removed during client.shutdown(). The library never enables global process handlers by default.