djs-marshal

A lightweight command handler for discord.js interactions

This package requires discord.js v13 or higher to be installed

Installation

# with npm
npm install djs-marshal --save
# with yarn
yarn add djs-marshal

# this package also requires discord.js
npm install discord.js --save

Documentation

You can find the full documentation here

Setup

You can set up your bot to handle commands in 2 ways:

initializeBot()

This is the recommended way to set up your bot. It sets up various things like commands' directory, logging and handlers for various events required.

import Marshal from 'djs-marshal';
import path from 'path';

const client = Marshal.initializeBot({
  // the path where slash commands are stored
  slashCommandsPath: path.join(__dirname, 'commands'),
  // the path where buttons are stored
  buttonsPath: path.join(__dirname, 'commands'),
  // the path where select menus are stored
  selectMenusPath: path.join(__dirname, 'commands'),
  // (optional) message to log on ready event
  readyMessage: 'Logged in as {tag}',
  // (optional) bot's token, will login if provided
  token: process.env.BOT_TOKEN,
  // (default: 'warn') the level of logs to log in the console
  logLevel: 'verbose',
  // (default: 'simple') how to style the logs
  logStyle: 'extended',
});

// if you didn't provide the token above, log in yourself
// client.login(process.env.BOT_TOKEN);

Slash Commands

Now in your commands' folder, you can start creating command files!

Examples

// ping.js|ts
import { defineSlashCommand } from 'djs-marshal';

// a pretty basic command. command is a discord.js
// CommandInteraction and you can use its methods like
// reply, defer, editReply, etc.
export default defineSlashCommmand({
  name: 'ping',
  description: 'Play ping-pong with me',
  commandType: 'global',
  execute (command) {
    command.reply('Pong!')
  }
});
// https://deathvenom54.github.io/djs-marshal/modules.html#SlashCommand

// guildPing.js|ts
import { defineSlashCommand } from 'djs-marshal';

// any command with a guildId specified is registered as
// as a guild command and will only work in that guild
export default defineSlashCommand({
  name: 'guildping',
  description: 'Play ping-pong with me in this server',
  commandType: 'guild',
  guildId: '873232757508157470',
  execute (command) {
    command.reply('Peng!');
  }
});

// deferredPing.js|ts
import { defineSlashCommand } from 'djs-marshal';

// you can pass in beforeExecute.defer as true to defer the interaction beforehand
export default defineSlashCommand({
  name: 'slothping',
  description: 'piiiiiinnnnnng',
  commandType: 'global',
  beforeExecute: {
    // you can also use deferEphemeral to mark the reply ephemeral
    defer: true,
  },
  execute (command) {
    setInterval(() =>{
      command.editReply('Pooooooonnnngg!');
    }, 3000)
  }
});

// secret.js|ts
import { defineSlashCommand } from 'djs-marshal';

export default defineSlashCommand({
  name: 'secret',
  description: 'Only for server moderators',
  // this command is registered in all the
  // guilds the bot is in
  commandType: 'allGuild',
  // this disables the command for anyone who
  // doesn't have any of these permissions
  allowWithPermission: ['MANAGE_SERVER'],
  async execute (command) {
    command.reply('Secret moderators stuff')
  }
});

Buttons

In your defined buttons directory, you can create message button interceptors in a similar manner to slash commands

import { defineButtonCommand } from 'djs-marshal';

export default defineButtonCommand({
  // can also be a regex, like /button-\d+/
  customId: 'my-button',
  // you can specify beforeExecute options 
  // just like in slash commands
  beforeExecute: {
    deferEphemeral: true
  },
  async execute(int) {
    await int.editReply('Beep boop!')
  }
});

Select Menus

In your defined select menus' directory, you can create select menu interceptors in a similar manner to slash commands

import { defineSelectMenuCommand } from 'djs-marshal';

export default defineSelectMenuCommand({
  // can also be a regex, like /menu-\d+/
  customId: 'my-menu',
  // you can specify beforeExecute options 
  // just like in slash commands
  beforeExecute: {
    deferEphemeral: true
  },
  async execute(int) {
    await int.editReply('Thank you, we have noted your choice!')
  }
});

Contributing

Please read CONTRIBUTING.md for the guidelines to contribute to this project.