Discord Moderation Tool

A TypeScript Discord bot built with Discord.js v14, designed for server moderation with a clean, type-safe architecture.

Features

• Slash Commands: Traditional /command style interactions
• Context Menu Commands: Right-click context menus for users and messages
• Event-Driven Architecture: Modular event handling system
• Type-Safe: Full TypeScript support with discriminated unions
• Environment Configuration: Secure configuration management
• Command Helpers: Easy-to-use helpers for creating different command types

Installation

Prerequisites

• Node.js 22.20.0+
• pnpm (recommended) or npm
• A Discord bot token

Setup

1. Clone the repository

   git clone <repository-url>cd moderation-tool

2. Install dependencies

   pnpm install

3. Configure environment

   cp .env.local.example .env.local

   Edit .env.local with your bot credentials:

   DISCORD_TOKEN=your_bot_token_hereCLIENT_ID=your_client_id_hereSERVER_ID=your_guild_id_hereSPAM_DETECTION_CHANNEL_ID=your_spam_detection_channel_id_hereROLE_REGULAR_ID=your_regular_role_id_here

4. Build and run

   # Development (with hot reload)
   pnpm dev
   # Production build
   pnpm build:ci
   pnpm start:ci

Creating Commands

Slash Commands

Use createSlashCommand helper for traditional /command interactions:

import{createSlashCommand}from"../commands/helpers.js";exportconstping=createSlashCommand({data: {name: "ping",// Must be lowercasedescription: "Replies with Pong!",options: [// Optional: command options{name: "message",description: "Optional message to include",type: ApplicationCommandOptionType.String,required: false,}]},execute: async(interaction)=>{awaitinteraction.reply("Pong!");},});

Context Menu Commands

User Context Menu Commands

import{createUserContextMenuCommand}from"../commands/helpers.js";exportconstuserInfo=createUserContextMenuCommand({data: {name: "Get User Info",// Can contain spaces and capitals},execute: async(interaction)=>{consttargetUser=interaction.targetUser;awaitinteraction.reply(`User: ${targetUser.tag}`);},});

Message Context Menu Commands

import{createMessageContextMenuCommand}from"../commands/helpers.js";exportconstreportMessage=createMessageContextMenuCommand({data: {name: "Report to Moderators",},execute: async(interaction)=>{consttargetMessage=interaction.targetMessage;// Handle message reporting logicawaitinteraction.reply("Message reported!");},});

Registering Commands

Add your commands to src/commands/index.ts:

import{ping}from"./ping.js";import{reportMessage}from"./reportMessage.js";importtype{Command}from"./types.js";exportconstcommands=newMap<string,Command>([ping,reportMessage].flat().map((command)=>[command.data.name,command]));

Creating Events

Events are handled automatically through the event system. Create new events using the createEvent helper:

import{Events}from"discord.js";import{createEvent}from"../events/helpers.js";exportconstmessageCreateEvent=createEvent({name: Events.MessageCreate,},async(message)=>{if(message.author.bot)return;// Handle message logicconsole.log(`Message from ${message.author.tag}: ${message.content}`);});

Registering Events

Add your events to src/events/index.ts:

import{messageCreateEvent}from"./message-create/index.js";import{readyEvent}from"./ready/index.js";importtype{DiscordEvent}from"./types.js";exportconstevents: DiscordEvent[]=[readyEvent,messageCreateEvent];

Configuration

The bot uses a centralized configuration system in src/env.ts. Environment variables are validated and logged on startup.

Required Environment Variables

• DISCORD_TOKEN: Your Discord bot token
• CLIENT_ID: Your Discord application client ID
• SERVER_ID: Guild ID (Server ID) for guild-specific command registration

Development

Scripts

• pnpm dev - Start development server with hot reload
• pnpm build:ci - Build for production
• pnpm start:ci - Run production build
• pnpm typecheck - Run TypeScript type checking
• pnpm lint - Lint code with Biome
• pnpm format - Format code with Biome

Code Quality

This project uses:

• Biome for linting and formatting
• TypeScript for type safety
• Husky + lint-staged for pre-commit hooks

Adding New Features

1. Commands: Create in src/commands/ and register in src/commands/index.ts
2. Events: Create in src/events/ and register in src/events/index.ts
3. Utilities: Add to src/utils/
4. Configuration: Update src/env.ts for new environment variables

Deployment

This project includes automated deployment using GitHub Actions and Docker with direct SSH deployment to your VPS.

Prerequisites

• A VPS with Docker and Docker Compose installed
• SSH access to your VPS
• GitHub repository with Actions enabled
• Discord bot credentials

GitHub Actions Setup

1. Set up repository secrets
   • Go to Settings → Secrets and variables → Actions
   • Add the following secrets:
     • VPS_HOST: Your VPS IP address or hostname
     • VPS_USER: SSH username for your VPS
     • VPS_SSH_KEY: Private SSH key for authentication
     • DISCORD_TOKEN: Your Discord bot token
     • CLIENT_ID: Your Discord application client ID
     • SERVER_ID: Your Discord server (guild) ID

VPS Setup

The CI/CD pipeline handles all the setup automatically. The first deployment will:

• Create the moderation-tool-bot directory on your VPS
• Clone the repository and set up the environment
• Subsequent deployments will simply pull the latest changes

Automated Deployment

The GitHub Actions workflow will automatically:

• Build and test on every push/PR to main branch
• SSH directly to your VPS
• Create project directory if it doesn't exist
• Clone repository on first deployment
• Pull latest code changes on subsequent deployments
• Build Docker image on the VPS
• Deploy using Docker Compose with production profile
• Verify deployment success and show container status

Monitoring

# View logs
docker compose logs -f
# Check container status
docker compose ps
# Restart the bot
docker compose restart moderation-tool-bot
# Stop the bot
docker compose down

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT