@Wump/framework

A clean Discord bot framework that gets out of your way.

wump is a modern Discord bot framework built on top of Discord.js, designed to make bot development cleaner, faster and less verbose — with built-in command handling, guards, collectors, voice support and more.

Installation

npm install @wump/framework

Voice support requires an additional package:

npm install @discordjs/voice

Quick Start

import { Client, Intents } from '@wump/framework';

const client = new Client({
    intents: [Intents.Guilds, Intents.GuildMessages, Intents.MessageContent]
});

client.event.clientReady({ once: true, run: () => {
    console.log(`Logged in as ${client.user.tag}`);
}});

await client.connect('YOUR_TOKEN');

Commands

Slash Command

import { SlashCommand, CommandOptions } from '@wump/framework';

export default SlashCommand({
    name: 'ping',
    description: 'Replies with Pong!',
    execute: (interaction) => {
        interaction.reply('Pong!');
    }
});

Slash Command with Options

import { SlashCommand, CommandOptions } from '@wump/framework';

export default SlashCommand({
    name: 'say',
    description: 'Say something',
    options: {
        'text': { type: CommandOptions.String, description: 'Text to say', required: true },
        'user': { type: CommandOptions.User, description: 'User to mention', required: false },
    },
    execute: (interaction) => {
        const text = interaction.options.getString('text');
        interaction.reply(text!);
    }
});

Slash Command with Subcommands

import { SlashCommand, CommandOptions } from '@wump/framework';

export default SlashCommand({
    name: 'user',
    description: 'User commands',
    subcommands: {
        'info': {
            description: 'Get user info',
            options: {
                'user': { type: CommandOptions.User, description: 'User', required: true }
            },
            execute: (interaction) => {
                const user = interaction.options.getUser('user');
                interaction.reply(`User: ${user?.username}`);
            }
        },
        'search': {
            description: 'Search group',
            subcommands: {
                'guild': {
                    description: 'Search in guild',
                    options: {
                        'user': { type: CommandOptions.User, description: 'User', required: true }
                    },
                    execute: (interaction) => {
                        interaction.reply('Searching in guild...');
                    }
                }
            }
        }
    }
});

Prefix Command

import { PrefixCommand } from 'wump';

export default PrefixCommand({
    name: 'ping',
    aliases: ['p'],
    execute: (ctx) => {
        ctx.reply('Pong!');
    }
});

Events

Inline

client.event.messageCreate({ once: false, run: (message) => {
    console.log(message.content);
}});

// PascalCase alias (mirrors Discord.js)
client.event.MessageCreate({ once: false, run: (message) => {
    console.log(message.content);
}});

File-based

// events/ready.ts
import { Event, Events } from '@wump/framework';

export default Event({
    name: Events.ClientReady,
    once: true,
    execute: (client) => {
        console.log(`Logged in as ${client.user.tag}`);
    }
});

File-based Handlers

await client.settings.handlers({
    commands: ['./commands'],
    events: ['./events'],
});

Handlers are recursive — all .ts and .js files in subdirectories are loaded automatically.

Settings

// Prefix commands
client.settings.prefix({
    prefix: '!',
    caseInsensitive: true,
    mention: true, // also triggers on @bot ping
});

// Guild-specific slash commands (instant deploy)
client.settings.guild({
    enabled: true,
    guildId: 'YOUR_GUILD_ID',
});

Guards

import { SlashCommand, Guards } from 'wump';

export default SlashCommand({
    name: 'ban',
    description: 'Ban a user',
    guards: [Guards.InGuild, Guards.HaveAdmin],
    options: {
        'user': { type: CommandOptions.User, description: 'User to ban', required: true }
    },
    execute: (interaction) => {
        interaction.reply('Banned!');
    }
});

Available Guards

| Guard | Description | |---|---| | Guards.InGuild | Must be used in a server | | Guards.IsDM | Must be used in DMs | | Guards.IsNSFW | Must be in an NSFW channel | | Guards.InVoiceChannel | User must be in a voice channel | | Guards.HaveAdmin | User must be an administrator | | Guards.HavePermission(...perms) | User must have specific permissions | | Guards.BotHavePermission(...perms) | Bot must have specific permissions | | Guards.IsOwner(id) | Must be the specified user | | Guards.Cooldown(ms) | Cooldown per user in milliseconds |

Collectors

Collector (continuous)

ctx.channel.collector({
    type: 'message',
    filter: (m) => m.author.id === ctx.author.id,
    time: 30000,
    max: 10,
    collect: { once: false, run: (m) => {
        console.log(m.content);
    }},
    end: { run: (collected) => {
        console.log(`Collected ${collected.size} messages`);
    }}
});

Await (one-shot)

// await a message
const msg = await ctx.channel.awaitMessage({
    filter: (m) => m.author.id === ctx.author.id,
    time: 15000,
});

// await a reaction
const reaction = await ctx.message.awaitReaction({
    filter: (r) => r.emoji.name === '✅',
    time: 15000,
});

// await a component (button/select)
const component = await ctx.message.awaitComponent({
    filter: (i) => i.user.id === ctx.author.id,
    time: 15000,
});

// await a modal
const modal = await ctx.message.awaitModal({ time: 15000 });

Get

const user    = await client.get.user({ method: 'fetch', user: '123456789' });
const guild   = await client.get.guild({ method: 'cache', guild: '987654321' });
const channel = await client.get.channel({ method: 'fetch', channel: '111222333' });
const member  = await client.get.member({ method: 'cache', guild: '987654321', member: '123456789' });
const role    = await client.get.role({ method: 'cache', guild: '987654321', role: '444555666' });
const message = await client.get.message({ method: 'fetch', channel: '111222333', message: '777888999' });

Voice

import { VoiceManager } from '@wump/framework';

const connection = VoiceManager.join({
    channelId: 'CHANNEL_ID',
    guildId: 'GUILD_ID',
    adapterCreator: guild.voiceAdapterCreator,
});

await connection.waitUntilReady();

await connection.play({
    input: 'https://example.com/audio.mp3',
    volume: 0.5,
    onStart: () => console.log('Playing!'),
    onFinish: () => connection.disconnect(),
});

connection.pause();
connection.resume();
connection.stop();
connection.disconnect();

Sharding

import { ShardManager } from '@wump/framework';

const manager = new ShardManager({
    file: './dist/bot.js',
    token: 'YOUR_TOKEN',
    totalShards: 'auto',
});

manager.onShardCreate((shard) => {
    console.log(`Shard ${shard.id} created`);
});

await manager.spawn();

Components

wump re-exports all Discord.js builders:

import {
    EmbedBuilder,
    ButtonBuilder,
    ButtonStyle,
    ActionRowBuilder,
    StringSelectMenuBuilder,
    ModalBuilder,
    TextInputBuilder,
    TextInputStyle,
    // Components v2
    ContainerBuilder,
    SectionBuilder,
    TextDisplayBuilder,
    ThumbnailBuilder,
    MediaGalleryBuilder,
    SeparatorBuilder,
    SeparatorSpacingSize,
    // Utils
    Colors,
    MessageFlags,
} from '@wump/framework';

License

GPL-3.0 © ghostxbit

If you fork or modify wump, you must keep credits to the original author and license your work under GPL-3.0. See NOTICE.md for details.