djs-builder

Welcome to the ultimate Discord Bot Utilities package! 🥏 Boost your Discord bot development with ease, speed, and all-in-one features.

📑 Table of Contents

• 🎯 Starter – Initialize your bot with commands, events, presence, and more.
• ⚙️ Functions – Utilities like CreateRow, CreateBar, Wait, and GetUser.
• ⚡ Commands & Events – Easy setup with cooldowns, permissions, logging, and anti-crash.

🎯 STARTER

The starter function is the ultimate initializer for your Discord bot 🤖. It handles everything from logging in, loading commands/events, setting the bot presence, anti-crash protection, logging commands usage, and even checking for library updates.

Features:

• 🛠️ One-line loader for both Slash & Prefix commands 🔩
• 📜 Comprehensive terminal info display (commands, events, bot stats) 📊
• 🧰 Event handler loader in one line 🎉
• ⚠️ Anti-crash system with automatic webhook reporting 📃
• 🔋 MongoDB connection support 📥
• 📑 Command logger for both Slash and Prefix commands 🧭
• 💡 Supports custom prefixes per guild and cooldowns ⏳
• 🔼 Automatic update checker for djs-builder 📦

💡 Tip: Any option you don’t want, just remove it 🗑️.

Starter Usage ⚙️

const { starter } = require("djs-builder");
const { Client, GatewayIntentBits } = require("discord.js");

const client = new Client({
  intents: Object.keys(GatewayIntentBits).map((a) => GatewayIntentBits[a]),
});

// Define starter options
const starterOptions = {
  bot: {
    token: "YOUR_BOT_TOKEN", // 🔑 Discord bot token
    ownerId: "YOUR_USER_ID", // 👤 Bot owner ID
  },
  terminal: true, // 🖥️ Show bot info in terminal

  Status: {
    status: "online", // ✅ Presence state: online, dnd, idle, offline
    activities: ["Game 1", "Game 2"], // 🎮 Multiple activities
    type: 0, // 🎭 Activity type: (0=PLAYING, 1=STREAMING, 2=LISTENING, 3=WATCHING)
    time: 60000, // ⏱️ Rotate activities every X ms
    url: "https://twitch.tv/example", // 🌐 Twitch URL (only required for streaming)
  },

  database: {
    url: "mongodb://localhost:27017", // 💾 MongoDB connection
  },

  anticrash: {
    url: "https://your.crash.webhook.url", // 🚨 Webhook for crash reports
    mention_id: "YOUR_USER_ID", // 📣 Optional: mention user on crash
  },
};

// Start the bot
await starter(client, starterOptions);

📌 How Starter Works

1️⃣ Bot Login & Status

• Authenticates the bot using your token 🔑.
• Supports multiple rotating activities (e.g., Game 1 → Game 2 → …) ⏱️.
• Works with all Discord activity types: PLAYING, STREAMING, LISTENING, WATCHING 🎭.
• Twitch URL is supported for streaming mode 🌐.

2️⃣ Database Connection

• Connects automatically to MongoDB 💾.
• Useful for bots with persistent data storage.

3️⃣ Anticrash System

• Catches and logs:

  • unhandledRejection
  • uncaughtException
  • uncaughtExceptionMonitor
  • unhandledRejectionMonitor
  • warning ⚠️

• Sends error reports to a webhook 🚨.

• Optionally pings the owner 📣.

4️⃣ Terminal Info

• Displays colorful and structured information 🖥️:

  • Bot name, user, guild, and channel counts 📊.
  • Owner ID 👤.
  • Database connection status 💾.
  • Uptime ⏳.

• Powered by cli-table3 + chalk for a professional CLI look 🎨.

5️⃣ Auto Update Checker

• Monitors new versions of djs-builder automatically 🔄.
• Sends update notifications to the webhook 🎉.

6️⃣ Bot Files Information

• Access detailed stats about loaded files directly from the client:

  • Number of prefix commands ⚡.
  • Number of slash commands ⚔️.
  • Number of events 🎉.

• Available via client.files, useful for debugging or terminal display 🛠️.

💡 Tips

• Flexible: Delete any section you don’t need (anticrash, database, etc.) 🗑️.
• Multi-Status: Add as many activities as you want and let them rotate 🎮.
• Safe by Default: Anticrash system ensures your bot won’t go down easily 🛡️.
• Always Up-to-Date: Automatic update checker keeps your bot running on the latest version ⬆️.
• Transparent: Quickly check how many files your bot has loaded anytime 📊.

⚙️ functions

• Easyest ✨ / Fastest ⚡ /Clear 🧵

Than the discord.js

CreateRow 🔵

🔵 CreateRow – Easily create Discord Action Rows with Buttons & Select Menus ✨

CreateRow is a powerful utility to build Discord Action Rows. It supports:

• Buttons ✅
• Select Menus 🎯 (string, role, user, channel)
• Advanced options like defaultValues and channelTypes.

📌 Example Usage:

const { CreateRow } = require("djs-builder");

const actionRow = new CreateRow([
  //// For each new row, use [] for buttons or {} for a select menu

  // 🔹 Row #1: Buttons
  [
    {
      id: "button1", // customId for the button
      style: 1, // Button styles: Primary(1), Secondary(2), Success(3), Danger(4), Link(5)
      label: "Primary Button", // Text shown on button
      emoji: "😃", // Emoji displayed
      disabled: false, // true = disabled
    },
    {
      id: "button2",
      style: 2,
      emoji: "🚀",
      disabled: true, // Button is disabled
    },
  ],

  // 🔹 Row #2: Select Menu
  {
    type: "string", // Options: "string" | "role" | "user" | "channel"
    options: {
      id: "menu1", // customId for the select menu
      placeholder: "Select an option",
      min: 1, // Minimum selection
      max: 2, // Maximum selection

      // 🔸 Data for string select only
      data: [
        {
          name: "Option 1",
          id: "opt1",
          about: "First option",
          icon: "🌟",
          default: true,
        },
        { name: "Option 2", id: "opt2", about: "Second option", icon: "🚀" },
        { name: "Option 3", id: "opt3", about: "Third option", icon: "🔗" },
      ],

      // 🔸 Map keys
      label: "name", // Which field is the label
      value: "id", // Which field is the value
      description: "about", // Description for each option
      emoji: "icon", // Emoji for each option

      // 🔸 Extra options
      disabled: false, // Disable the entire menu
      defaultValues: [
        // For role/user/channel menus
        { id: "123456789012345678", type: "user" }, // Pre-selected
      ],
      channelTypes: [0, 2], // Only for ChannelSelectMenu (0 = Text, 2 = Voice)
    },
  },
]);

📖 Explanation

🔹 Buttons

• id → customId for the button
• style → 1: Primary, 2: Secondary, 3: Success, 4: Danger, 5: Link
• label → Button text
• emoji → Displayed emoji
• disabled → true = button is unclickable

🔹 Select Menus

• type → "string" | "user" | "role" | "channel"

• id → customId for menu

• placeholder → Text shown before selection

• min / max → Min/Max selectable values

• data → Options array (for string select only)

  • label → Visible text
  • value → Internal value
  • description → Short description
  • emoji → Option emoji
  • default → Pre-selected option

• disabled → Disable menu completely

• defaultValues → Pre-selected user/role/channel options

• channelTypes → Restrict selectable channel types

CreateBar 🧾

🧾 CreateBar – Text-based Progress Bar for Discord ✨

CreateBar allows you to display a customizable progress bar with optional percentages and partial symbols. Perfect for showing progress, loading, or stats in messages.

📌 Basic Example:

const { CreateBar } = require("djs-builder");

const bar = new CreateBar(7, 10, {
  length: 20, // Total length of the bar
  fill: "💚", // Filled portion
  empty: "🖤", // Empty portion
  partialChar: "💛", // Partial fill
  showPercent: true, // Show percentage
  left: "❰", // Left bracket
  right: "❱", // Right bracket
});

console.log(bar);
// Output: ❰💚💚💚💚💚💚💚💛🖤🖤🖤🖤🖤🖤🖤🖤🖤🖤❱ 70%

📌 Another Example with different symbols:

console.log(
  CreateBar(3.7, 5, {
    fill: "🟦",
    empty: "⬛",
    partialChar: "🟨",
    length: 10,
    left: "❰",
    right: "❱",
    showPercent: true,
  })
);

// Output: ❰🟦🟦🟦🟨⬛⬛⬛⬛⬛⬛❱ 74%

📌 Minimalist example without percentage:

console.log(
  CreateBar(4, 8, {
    fill: "🔵",
    empty: "⚪",
    showPercent: false,
  })
);

// Output: 🔵🔵🔵🔵⚪⚪⚪⚪

📌 Fun Emoji example:

console.log(
  CreateBar(6, 10, {
    length: 12,
    fill: "🔥",
    empty: "❄️",
    partialChar: "🌟",
    showPercent: true,
    left: "«",
    right: "»",
  })
);

// Output: «🔥🔥🔥🔥🔥🔥🌟❄️❄️❄️❄️» 60%

🔹 Options Summary

• length → Total number of symbols
• fill → Symbol for filled portion
• empty → Symbol for empty portion
• partialChar → Symbol for partial fill (e.g., half-filled)
• showPercent → Show percentage at the end
• left / right → Brackets or edges for the bar

🔹 Notes

• Supports fractional values for partial fill
• Fully customizable with any emoji or character 🎨
• Great for progress, stats, experience bars, or loading indicators

Wait ⏰

⏰ Wait – Await messages, buttons, select menus or modals easily ✨

Wait is a replacement for traditional collectors. It supports:

• Awaiting messages 📝
• Awaiting interactions (buttons / select menus) 🎛️
• Awaiting modal submissions 📋
• Filtering by user and timeout

📌 Example Usage:

const { Wait } = require("djs-builder");

const response = await Wait({
  context: message, // Message or Interaction object
  userId: message.author.id, // Optional: filter by user
  type: "both", // "message" | "interaction" | "both"
  time: 30000, // Time in ms
  message_Wait: message, // Required if waiting for buttons/selects
});

if (!response) return console.log("⏱️ Timeout!");
console.log("✅ Collected:", response);

🔹 Options

• context → The message or interaction context
• userId → Only collect from this user (optional)
• type → "message" | "interaction" | "both"
• time → Timeout in milliseconds
• message_Wait → Message containing buttons/select menus (for interaction/both type)

🔹 Notes

• Supports automatic cleanup of collectors after completion
• Can return Message, Interaction, or ModalSubmitInteraction

GetUser 👤

👤 GetUser – Fetch a GuildMember easily from a message ✨

GetUser helps to detect a target member in multiple ways:

• Mention (@User)
• User ID (123456789012345678)
• Reply to another message

📌 Example Usage:

const { GetUser } = require("djs-builder");

const data = await GetUser(message);

if (!data) return message.reply("❌ Could not find the user.");

const member = data.user; // GuildMember object
const args = data.args; // Remaining arguments
const reason = args.join(" ") || "No reason provided";

await member.ban({ reason });
message.reply(`🚫 ${member.user.tag} was banned for: ${reason}`);

🔹 Returns

{
  user: <GuildMember>,  // Targeted member
  args: [ "arg1", "arg2" ] // Remaining message arguments
}

🔹 Detection Methods

• Mention: !ban @Ahmed Spamming
• User ID: !ban 123456789012345678 Spamming
• Reply: Reply to user's message with !ban

🔹 Notes

• Automatically handles missing users
• Returns null if user not found
• Works in any text channel of the guild

Logging System 🛡️

The Logging System is a powerful feature that keeps track of almost everything happening inside your Discord server 🔍.
From messages 📝 to channels 📂, roles 🎭, invites 🔗, and even voice state changes 🎙️ – nothing goes unnoticed!

✨ Features

• 📝 Messages – Deleted & edited messages are logged with details.
• 📂 Channels – Creation, deletion, and updates are tracked.
• 🎭 Roles – Created, deleted, and updated roles, including member role changes.
• 🎙️ Voice State – Joins, leaves, and moves between channels.
• 🔗 Invites – Created invites & usage tracking.
• 😀 Emojis & Stickers – Added, removed, or updated.
• 🚨 Audit Log Integration – Fetches the executor (who did what).
• 🎨 Beautiful Embeds – Every log is shown in a clean, styled embed with timestamps.

⚙️ Setup Example

Using the log function is very simple ⚡.
Just place this code inside an event (like clientReady) to start logging:

const { log } = require("djs-builder");

module.exports = {
  name: "clientReady",
  async run(client) {
    await log(
      client,
      "GUILD_ID", // 🏠 Guild ID (server)
      "CHANNEL_ID" // 📢 Channel ID for logs
    );
  },
};

💡 How It Works

• ✅ Pass your Client, Guild ID, and Log Channel ID.
• 🔔 Instantly starts tracking events and sending them to the log channel.
• 🧰 No extra setup required – plug and play!

Level System 🏆

🏆 Level System – XP, Levels & Leaderboard

The Level System module lets you track user experience points (XP) in text 💬 and voice 🎙️, handle level-ups ⬆️, and display leaderboards 🏅. Perfect for gamifying your Discord server! 🎮✨

📦 Module Exports

const { addXP, UserLevel, leaderboard } = require("djs-builder");

• addXP(userId, guildId, options) → Adds XP for a user and handles level-ups 🎲.
• UserLevel(userId, guildId) → Fetch a user's XP and level 👤.
• leaderboard(guildId, type, limit) → Get top users 🏅.

🎲 addXP – Add Experience Points

Adds XP to a user and automatically handles level-ups.

const result = await addXP("USER_ID", "GUILD_ID", {
  type: "text", // "text" 💬 | "voice" 🎙️
  minXP: 5, // Minimum random XP 🟢
  maxXP: 15, // Maximum random XP 🔵
  amount_add: 10, // Optional: fixed XP 💎
  level_add: 1, // Optional: direct level boost ⬆️
});

console.log(result);
/* Example output:
{
  newLevel: 3,
  oldLevel: 2,
  totalXP: 250,
  leveledUp: true
}
*/

🧑‍🤝‍🧑 UserLevel – Fetch User Data

Fetch a user's text XP, voice XP, total XP, and current level.

const data = await UserLevel("USER_ID", "GUILD_ID");
console.log(data);
/* Example output:
{
  text: 120 💬,
  voice: 50 🎙️,
  totalXP: 170 ⭐,
  level: 2 ⬆️
}
*/

Returns default values if the user is not found.

🏅 Leaderboard – Top Users

Get a sorted list of users based on XP or level.

const topUsers = await leaderboard("GUILD_ID", "totalXP", 5);
console.log(topUsers);
/* Example output:
[
  { userId: "123", totalXP: 500, level: 5 },
  { userId: "456", totalXP: 400, level: 4 },
  ...
]
*/

Parameters:

• guildId → Server ID 🏠
• type → "totalXP", "text" 💬, "voice" 🎙️, or "level" ⬆️. Default = "totalXP"
• limit → Number of top users to return 🔢. Default = 10

⚡ Practical Example: messageCreate Event

const { addXP, UserLevel, leaderboard } = require("djs-builder");

module.exports = {
  name: "messageCreate",
  run: async (msg, client) => {
    if (msg.author.bot) return;

    // 🎲 Add XP on every message
    const result = await addXP(msg.author.id, msg.guild.id, {
      type: "text",
      minXP: 5,
      maxXP: 15,
    });

    // 🎉 Level-up notification
    if (result.leveledUp) {
      msg.channel.send(
        `🎊 ${msg.author} new level **${result.newLevel}** ⬆️`
      );
    }

    // 📊 Check your rank
    if (msg.content === "!rank") {
      const data = await UserLevel(msg.author.id, msg.guild.id);
      msg.reply(`📈 **level ** ${data.level} ⬆️ – **XP:** ${data.totalXP} ⭐`);
    }

    // 🏅 Display top users
    if (msg.content === "!top") {
      const lb = await leaderboard(msg.guild.id, "totalXP", 5);
      msg.reply(
        lb
          .map(
            (u, i) =>
              `#${i + 1} <@${u.userId}> – Lv.${u.level} ⬆️ (${u.totalXP} ⭐)`
          )
          .join("\n")
      );
    }
  },
};

💡 Notes & Tips

• 💬 Text XP – Add XP for messages automatically.
• 🎙️ Voice XP – Add XP for voice activity.
• ⬆️ Level Up – Trigger notifications when leveling up.
• 🏅 Leaderboard – Display the top users in server using embeds for better look.
• 🎮 Gamify your server easily with XP rewards, mini-games, and custom commands.

⚡ Commands & Events

💡 Commands & Events made easy! With djs-builder, handling commands and events is smooth, fast, and fully customizable. You get built-in features like:

• ⚠️ Anti-crash protection – your bot won’t crash unexpectedly.
• ⏳ Cooldowns – prevent spam and control usage.
• 🛡️ Permissions & owner/dev only checks – secure your commands.
• ⚡ Fast Use & custom prefixes – run commands easily across guilds.
• 📝 Logging – track every command usage for prefix or slash.

Below are all the available properties you can use for your commands and events:

⚡ Commands & Events Options

⚡ COMMAND OPTIONS (Prefix & Slash)

name: 'string',                // 🏷️ Command name (required)
aliases: ['string'],           // 🔁 Alternative names (Prefix only)
description: 'string',         // ✍️ Short description of the command
cooldown: 5,                   // ⏳ Cooldown in seconds before reusing the command
Permissions: ['ADMINISTRATOR'],// 🛡️ Required permissions to execute the command
ownerOnly: true,               // 👑 Only server owner can use this command
devOnly: true,                 // 🛠️ Only bot developer can use this command
guildOnly: true,               // 🏠 Command works only in servers
dmOnly: true,                  // ✉️ Command works only in DMs
fastUse: true,                 // ⚡ Allow command to be executed without prefix (Prefix only)
run: Function,                 // 🏃‍♂️ Main function to run the command
execute: Function,             // 🏃‍♂️ Alternative function to run the command

⚡ EVENT OPTIONS

name: 'string',                // 🏷️ Event name (e.g., messageCreate, guildMemberAdd)
once: true,                    // 🎯 If true, the event will be executed only once
run: Function,                 // 🏃‍♂️ Function to run when the event triggers
execute: Function              // 🏃‍♂️ Alternative function to run the event

💡 Tip: Use these properties to fully control command behavior, access, and event handling.

💌 Support

We welcome contributions! If you have any suggestions, bug reports, or feature requests, feel free to reach out to us on Discord.

💬 Contact Me: <@679036538511687711>

🌐 Join our Discord: