TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published


    npm version

    A simple framework with an intuitive interface for creating Discord bots using Node.

    import Discord from 'discord.js';
    import { Solaire } from "solaire-discord";
    const client = new Discord.Client({
      intents: [ Discord.Intents.FLAGS.GUILDS, Discord.Intents.FLAGS.GUILD_MESSAGES ]
    const bot = Solaire.create({
      discordClient: client,
      token: process.env.TOKEN,
      commandPrelude: "!",
      commands: {
        // In a Discord channel...
        // > !ban @someUser being mean
        "ban <user:GuildMember> <...reason>": {
          execute({ args, message }) {
            // args.user: Discord.js::GuildMember(someUser)
            // args.offense: ["being", "mean"]
  `Banning ${args.user.displayName} for ${args.reason.join(' ')}!`;


    Solaire interacts heavily with Discord.js, and many of the objects exposed from the Solaire API will be directly from Discord.js.

    Example Bot

    Install · Example Config · Defining Commands · Command Configuration · Events


    npm install solaire-discord


    Property Required Type Desc
    discordClient Yes Discord.js::Client A Discord.js Client object. This client must have the GUILD_MESSAGES intent enabled for Solaire to work properly.
    token Yes string Your bot's Discord token (see
    commandPrelude No string The string that must precede a command's name in a Discord message for the command to be invoked. Common values are !, ?, ;;, but any string would technically work.
    commandCooldown No number The amount of time in milliseconds that a command is un-invokable after being used. This cooldown is per-command.
    commands Yes Record<string, CommandConfiguration> See Defining commands and Command configuration

    Defining commands

    In Solaire, bot commands are defined using a definition string that resembles how you would actually use the command in Discord. For example, a command that is used like !ban @someAnnoyingUser being mean, would be defined using the string ban <user:GuildMember> [...reason].

    This string, along with associated configuration for the command, is passed in via your Solaire config's commands property.

       const bot = Solaire.create({
        commands: {
          'ban <user:GuildMember> <...reason>': {

    Command Name & Aliases

    A command's name is defined as the first word in your command definition string

    ban <user>
    ^------ "ban" is the command's name

    You can define aliases for a command by appending the command's name with |<alias>, e.g.

    ban|b|banMember <user>
    ^---- "ban is the command's name, but "b" and "banMember" can also be used to invoke the command

    Command Arguments

    After your command's name, you can define any number of arguments that can be passed into your command.

    Required Arguments

    Required arguments are denoted in the definition string by being wrapped in <>, e.g.

    ban <user>
          ^---- "user" is a required argument for the "ban" command

    Optional Arguments

    Optional arguments are denoted by being wrapped in [], e.g.

    ban <user> [reason]
                 ^---- "reason" is an optional argument

    When an optional argument is defined, the remaining arguments in the command must also be optional.

    ban [reason> <user>
                   ^----- INVALID - since "reason" is optional, all arguments after it must also be optional           

    Rest Arguments

    A "rest" argument is an arg whose value is defined as all remaining words in a message. They are denoted by the arg's name being preceded with .... e.g.

    ban <user> [reason]
    > !ban @someAnnoyingUser being mean
                              ^----- "reason" arg has value "being"
    ban <user> [...reason]
    > !ban @someAnnoyingUser being mean
                              ^----- "reason" arg has value "being mean"

    A rest argument must be the last argument of a command. When accessing the argument in your execute, guard, etc. functions, the value of the argument will be an array.

    Argument Types

    An argument's value can be constrained by defining an explicit type for that argument, denoted in the command definition string by appending the argument's name with :<argType>, e.g.

    ban <user:GuildMember>
               ^---- "user" arg value must be parseable into a "GuildMember" type

    Defining an argument type has a few benefits

    • It validates that the passed in value is valid
    • It automatically parses the argument and fits it to its type, transforming the value to a more convenient data type for use when processing and executing the command
    • It provides documentation for how our command is supposed to be used

    The available argument types are:

    Argument Type Validation Resolved JS Type
    Int Validates using parseInt Number
    Float Validates using parseFloat Number
    GuildMember Validates that ID passed in resolves to a member of the message's server Discord.js::GuildMember
    Date Validates using new Date() Date

    Command Configuration

    Command Execute Function

    When your command is invoked, the command's execute function gets called.

       const bot = Solaire.create({
        commandPrelude: '!',
        commands: {
          'ban <user:GuildMember> [...reason]': {
            async execute({ args, message }) {
             // message: Discord.js::Message
             // args.user: Discord.js::GuildMember
             // args.reason: string[]
             const fullReason = args.reason.join(' ');
   `Banning ${args.user.displayName} for ${fullReason}`;
             user.ban({ reason: fullReason })
    > !ban @someAnnoyingUser mean
    < Banning Some Annoying User for mean

    The payload that gets passed into the execute function contains the following properties

    Property Type Desc
    args Record<string, any> The arguments passed into the command
    message Discord.js::Message The message that triggered the command

    Command Authorization

    You can restrict which users can invoke a command by defining a guard function for a command.

       const bot = Solaire.create({
        commandPrelude: '!',
        commands: {
          'ban <user:GuildMember> [...reason]': {
            async execute({ args, message }) {...},
            async guard({ error, ok, message, args}) {
              if(!message.member.roles.cache.some(r => === 'admin'){
                error('Member must be an admin');
              } else {

    The payload provided to the guard function is the same as the one given to the execute function, with the addition of two new callback properties ok and error. If a guard function is provided, the command will be exected only if guard calls the ok function, and the error function is not called. If neither is called, the command will default closed and not execute.

    Command Prelude

    It is heavily suggested that you assign a commandPrelude to your bot, which is the string that is required at the start of any command invocation. Otherwise, Solaire has to process every single message for the possibility that it's invoking a command. It's also just nan extremely common practice for chat bots.

       const bot = Solaire.create({
        // To invoke a command in chat, the message has to start with '!'
        // e.g. ❌  ban @someUser being mean WON'T work
        //      ✅ !ban @someUser being mean WILL work
        commandPrelude: '!',
        commands: {
          'ban <user> <reason>': {
    > !ban @someAnnoyingUser mean
    > !ban @someAnnoyingUser being mean
    < Banning Some Annoying User for being mean


    The Solaire class extends EventEmitter, and emits events that you can listen to.


    This event gets emitted after a bot command is invoked and Solaire has finished processing the invocation. The object that is passed to the listener has the following properties

    Property Type Desc
    success boolean Whether or not the command executed successfully
    command Command The Command that was invoked
    message Discord.js::Message The message that invoked the command
    error CommandInvocationError See command-invocation-error.ts for all possible values




    npm i solaire-discord

    DownloadsWeekly Downloads






    Unpacked Size

    98.4 kB

    Total Files


    Last publish


    • wwselleck