djs-builder

Simple Text:

{
  type: "text",
  content: "Hello World! 👋",
}

Text with Markdown:

{
  type: "text",
  content: "# 📢 Announcement\n**Important:** Server maintenance tonight!",
}

Text with Multiple Lines:

{
  type: "text",
  content: `## 🎮 Game Stats
  
**Player:** Ahmed
**Level:** 50
**XP:** 12,500 / 15,000
**Rank:** Diamond 💎`,
}

Text with Emojis & Formatting:

{
  type: "text",
  content: ">>> 💡 **Tip:** Use `/help` to see all commands!\n\n*This message will auto-delete in 30 seconds*",
}

Separator – Add spacing and dividers between components

The separator component allows you to add visual breaks between other components with customizable spacing and divider lines.

Separator Options

Simple Divider Line:

{
  type: "separator",
  divider: true,
}

Result: A thin horizontal line appears between components.

Separator without Line (Spacing Only):

{
  type: "separator",
  divider: false,
  spacing: 2, // Large spacing
}

Result: Empty space without any visible line - useful for visual grouping.

Small Spacing with Divider:

{
  type: "separator",
  divider: true,
  spacing: 1, // Small spacing (default)
}

Result: A divider line with minimal padding above and below.

Large Spacing with Divider:

{
  type: "separator",
  divider: true,
  spacing: 2, // Large spacing
}

Result: A divider line with more padding - creates stronger visual separation.

When to Use Each Option:

Media Gallery – Display images in a beautiful gallery format

The media component creates an image gallery that can display one or multiple images. Each image can be a simple URL string or a detailed object with additional options.

Format 1: Simple String URLs

The simplest way - just pass image URLs as strings:

{
  type: "media",
  links: ["https://example.com/image.png"],
}

Format 2: Object with Full Options

For more control, use objects with url, description, and spoiler:

{
  type: "media",
  links: [
    {
      url: "https://example.com/image.png",
      description: "A beautiful sunset",
      spoiler: false,
    },
  ],
}

Single Image with Spoiler:

{
  type: "media",
  links: [
    {
      url: "https://example.com/spoiler.png",
      description: "⚠️ Spoiler Alert!",
      spoiler: true,
    },
  ],
}

Multiple Images (Simple Strings):

{
  type: "media",
  links: [
    "https://example.com/image1.png",
    "https://example.com/image2.png",
    "https://example.com/image3.png",
    "https://example.com/image4.png",
  ],
}

Result: A 2x2 gallery grid of images.

Mixed Format (Strings + Objects):

You can mix simple strings with detailed objects in the same array:

{
  type: "media",
  links: [
    // Simple string - just the URL
    "https://example.com/public-image.png",
    
    // Object with description
    {
      url: "https://example.com/special-image.png",
      description: "Limited Edition Art",
    },
    
    // Object with spoiler
    {
      url: "https://example.com/secret-image.png",
      description: "Secret Content",
      spoiler: true,
    },
    
    // Another simple string
    "https://example.com/another-image.png",
  ],
}

Meme/Artwork Gallery with Spoilers:

{
  type: "media",
  links: [
    {
      url: "https://example.com/meme1.png",
      description: "Funny meme #1",
      spoiler: false,
    },
    {
      url: "https://example.com/meme2.png",
      description: "Funny meme #2",
      spoiler: false,
    },
    {
      url: "https://example.com/nsfw-meme.png",
      description: "⚠️ Slightly inappropriate",
      spoiler: true, // Hidden behind blur
    },
  ],
}

Tips for Media Galleries:

• Use description for accessibility and context
• Use spoiler: true for sensitive/spoiler content
• Mix formats freely - strings for quick images, objects for detailed ones
• Images are displayed in the order provided

Simple File Attachment:

{
  type: "file",
  url: "attachment://document.pdf",
}

Full Example with File:

const { CreateComponents } = require("djs-builder");
const { AttachmentBuilder } = require("discord.js");

const file = new AttachmentBuilder("./myfile.txt", { name: "myfile.txt" });

const components = await CreateComponents("container", [
  {
    type: "text",
    content: "📄 **Here is your requested file:**",
  },
  {
    type: "file",
    url: "attachment://myfile.txt",
  },
]);

await channel.send({ components, files: [file], flags: 32768 });

Button with Emoji:

{
  type: "button",
  components: [
    {
      id: "like_btn",
      style: 3, // Success (Green)
      label: "Like",
      emoji: "👍",
    },
  ],
}

Multiple Buttons in Row:

{
  type: "button",
  components: [
    { id: "btn_yes", style: 3, label: "Yes", emoji: "✅" },
    { id: "btn_no", style: 4, label: "No", emoji: "❌" },
    { id: "btn_maybe", style: 2, label: "Maybe", emoji: "🤔" },
  ],
}

All Button Styles:

{
  type: "button",
  components: [
    { id: "primary", style: 1, label: "Primary", emoji: "🔵" },    // Blue
    { id: "secondary", style: 2, label: "Secondary", emoji: "⚪" }, // Gray
    { id: "success", style: 3, label: "Success", emoji: "🟢" },    // Green
    { id: "danger", style: 4, label: "Danger", emoji: "🔴" },      // Red
    { style: 5, label: "Link", emoji: "🔗", url: "https://discord.com" }, // Link
  ],
}

String Select Menu (Basic):

{
  type: "menu",
  components: {
    type: "string",
    options: {
      id: "color_select",
      placeholder: "🎨 Choose a color",
      data: [
        { name: "Red", id: "red", icon: "🔴" },
        { name: "Blue", id: "blue", icon: "🔵" },
        { name: "Green", id: "green", icon: "🟢" },
      ],
      label: "name",
      value: "id",
      emoji: "icon",
    },
  },
}

String Select with Description:

{
  type: "menu",
  components: {
    type: "string",
    options: {
      id: "role_select",
      placeholder: "🎭 Select your role",
      data: [
        { name: "Gamer", id: "gamer", desc: "For gaming enthusiasts", icon: "🎮" },
        { name: "Artist", id: "artist", desc: "For creative people", icon: "🎨" },
        { name: "Developer", id: "dev", desc: "For coders & programmers", icon: "💻" },
        { name: "Music Lover", id: "music", desc: "For music fans", icon: "🎵" },
      ],
      label: "name",
      value: "id",
      description: "desc",
      emoji: "icon",
    },
  },
}

String Select with Min/Max:

{
  type: "menu",
  components: {
    type: "string",
    options: {
      id: "games_select",
      placeholder: "🎮 Select your favorite games (2-4)",
      min: 2,
      max: 4,
      data: [
        { name: "Minecraft", id: "mc", icon: "⛏️" },
        { name: "Fortnite", id: "fn", icon: "🔫" },
        { name: "Valorant", id: "val", icon: "🎯" },
        { name: "League of Legends", id: "lol", icon: "⚔️" },
        { name: "Rocket League", id: "rl", icon: "🚗" },
      ],
      label: "name",
      value: "id",
      emoji: "icon",
    },
  },
}

User Select (Multiple):

{
  type: "menu",
  components: {
    type: "user",
    options: {
      id: "users_select",
      placeholder: "👥 Select users to invite (1-5)",
      min: 1,
      max: 5,
    },
  },
}

Role Select Menu:

{
  type: "menu",
  components: {
    type: "role",
    options: {
      id: "role_select",
      placeholder: "🎭 Select a role",
      min: 1,
      max: 1,
    },
  },
}

Channel Select Menu:

{
  type: "menu",
  components: {
    type: "channel",
    options: {
      id: "channel_select",
      placeholder: "📢 Select a channel",
      min: 1,
      max: 1,
    },
  },
}

Channel Select with Type Filter:

const { ChannelType } = require("discord.js");

{
  type: "menu",
  components: {
    type: "channel",
    options: {
      id: "text_channel_select",
      placeholder: "💬 Select a text channel",
      channelTypes: [ChannelType.GuildText, ChannelType.GuildAnnouncement],
    },
  },
}

Menu with Default Values (User/Role/Channel):

{
  type: "menu",
  components: {
    type: "user",
    options: {
      id: "user_select_default",
      placeholder: "👤 Select users",
      min: 1,
      max: 3,
      defaultValues: [
        { id: "123456789012345678", type: "user" },
        { id: "987654321098765432", type: "user" },
      ],
    },
  },
}

Section with Thumbnail (Product):

{
  type: "section",
  content: "🛒 **iPhone 15 Pro**\n💰 Price: $999\n⭐ Rating: 4.8/5\n📦 In Stock: Yes",
  accessory: {
    type: "thumbnail",
    url: "https://example.com/iphone.png",
    description: "iPhone 15 Pro Image",
  },
}

Section with Button :

{
  type: "section",
  content: "🎁 **Daily Reward**\nClick to claim your daily reward!\n💎 **+100 Coins**",
  accessory: {
    type: "button",
    id: "claim_daily",
    style: 3, 
    label: "Claim",
    emoji: "🎁",
  },
}

Color – Set an accent color for the container (Requires Container Mode)

You can add an accent color line to your container. The color can be an integer or a hexadecimal string (#ff0000).

Container with Color:

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

const components = await CreateComponents(true, [
  {
    type: "text",
    content: "Welcome to our server! 🎉",
  },
  {
    type: "color",
    color: "#ff0000", // You can use Hex strings like "#ff0000" or an integer like 0xff0000
  }
]);

await interaction.reply({ components, flags: 32768 });

Supported Event Types

Using MongoDB Database

This method stores log configuration in MongoDB, allowing dynamic management via commands.

Setup in clientReady Event:

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

module.exports = {
  name: "clientReady",
  async run(client) {
    // Start logging with database mode
    await log(client, {
      database: true, // 🗄️ Uses MongoDB to store/fetch config
    });

    console.log("✅ Logging system started with database mode!");
  },
};

How It Works

• The system automatically fetches log configuration for each guild from MongoDB.
• You can manage settings via slash commands (see management command below).
• Supports per-guild customization for channels, colors, and disabled events.
• Important: If you use database mode, see the Log Management Command below to edit data.

Using Custom Data Array

This method uses a predefined array of configurations – perfect for simple setups or testing.

Setup in clientReady Event:

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

module.exports = {
  name: "clientReady",
  async run(client) {
    // Define your log configurations
    const logData = [
      {
        guildId: "123456789012345678", // 🏠 Server ID
        channelId: "987654321098765432", // 📢 Default log channel
        channels: {
          // 📂 Custom channels (optional)
          messageDelete: "111111111111111111",
          voiceStateUpdate: "222222222222222222",
        },
        colors: {
          // 🎨 Custom colors (optional)
          messageDelete: "DarkRed",
          channelCreate: "DarkGreen",
        },
        disable: ["inviteCreate"], // 🚫 Disabled events (optional)
      },
      // Add more guild configurations...
      {
        guildId: "999888777666555444",
        channelId: "444555666777888999",
      },
    ];

    // Start logging with custom data
    await log(client, {
      database: false, // 📋 Uses custom array
      Data: logData, // 📊 Your configurations
    });

    console.log("✅ Logging system started with custom data!");
  },
};

Supported Colors

Default, White, Aqua, Green, Blue, Yellow, Purple, LuminousVividPink, Fuchsia, Gold, Orange, Red, Grey, Navy, DarkAqua, DarkGreen, DarkBlue, DarkPurple, DarkVividPink, DarkGold, DarkOrange, DarkRed, DarkGrey, DarkerGrey, LightGrey, DarkNavy, Blurple, Greyple, DarkButNotBlack, NotQuiteBlack, Random, or any Hex Color like #FF5733.

Multi-Guild Support

Tip: You can add configurations for multiple guilds in the same array. Each guild can have its own unique settings for channels, colors, and disabled events!

Using the Log Model Directly

You can import the Log Mongoose model to create, update, or delete log configurations programmatically.

Import the Model:

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

Create New Configuration:

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

// Create a new log configuration for a guild
const newConfig = await Log.create({
  guildId: "123456789012345678",
  channelId: "987654321098765432",
  channels: {
    messageDelete: "111111111111111111",
  },
  colors: {
    messageDelete: "Red",
  },
  disable: [],
});

console.log("✅ Log configuration created!", newConfig);

Update Existing Configuration:

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

// Update log channel
await Log.findOneAndUpdate(
  { guildId: "123456789012345678" },
  { channelId: "NEW_CHANNEL_ID" },
  { upsert: true } // Create if doesn't exist
);

// Add event to disable list
await Log.findOneAndUpdate(
  { guildId: "123456789012345678" },
  { $push: { disable: "voiceStateUpdate" } }
);

// Remove event from disable list
await Log.findOneAndUpdate(
  { guildId: "123456789012345678" },
  { $pull: { disable: "voiceStateUpdate" } }
);

// Update specific channel for an event
await Log.findOneAndUpdate(
  { guildId: "123456789012345678" },
  { $set: { "channels.messageDelete": "NEW_CHANNEL_ID" } }
);

// Update specific color for an event
await Log.findOneAndUpdate(
  { guildId: "123456789012345678" },
  { $set: { "colors.messageDelete": "DarkRed" } }
);

Delete Configuration:

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

await Log.findOneAndDelete({ guildId: "123456789012345678" });
console.log("🗑️ Log configuration deleted!");

Fetch Configuration:

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

const config = await Log.findOne({ guildId: "123456789012345678" });
if (config) {
  console.log("📢 Log Channel:", config.channelId);
  console.log("📂 Custom Channels:", config.channels);
  console.log("🎨 Custom Colors:", config.colors);
  console.log("🚫 Disabled Events:", config.disable);
}

Web Dashboard for Log Management

When you use database mode (database: true), you can manage the logging system directly from the djs-builder Dashboard!

Dashboard Features for Logs

How to Access

1. Navigate to your dashboard (e.g., http://localhost:3000)
2. Log in with Discord OAuth2
3. Select a server
4. Click on "سجلات المراقبة" (Logs) in the sidebar

Important Notes

When database: true:

• Full editing capabilities from dashboard
• Changes are saved automatically to MongoDB
• Real-time updates

When database: false (Custom Data Array):

• Dashboard shows read-only mode
• A warning banner appears at the top
• You must edit settings in your code

Complete Log Management Slash Command

This command allows server administrators to manage the logging system via Discord.

Important: This command requires database: true mode to work properly.

const { Log, getLogConfigData } = require("djs-builder");
const {
  SlashCommandBuilder,
  PermissionFlagsBits,
  EmbedBuilder,
  ChannelType,
} = require("discord.js");

// All supported event types (21 events)
const EVENT_TYPES = [
  { name: "Message Delete", value: "messageDelete" },
  { name: "Message Update", value: "messageUpdate" },
  { name: "Channel Create", value: "channelCreate" },
  { name: "Channel Delete", value: "channelDelete" },
  { name: "Channel Update", value: "channelUpdate" },
  { name: "Member Join", value: "guildMemberAdd" },
  { name: "Member Leave", value: "guildMemberRemove" },
  { name: "Member Ban", value: "guildBanAdd" },
  { name: "Member Unban", value: "guildBanRemove" },
  { name: "Role Create", value: "roleCreate" },
  { name: "Role Delete", value: "roleDelete" },
  { name: "Role Update", value: "roleUpdate" },
  { name: "Member Role Update", value: "guildMemberUpdate" },
  { name: "Voice State", value: "voiceStateUpdate" },
  { name: "Invite Create", value: "inviteCreate" },
  { name: "Emoji Create", value: "emojiCreate" },
  { name: "Emoji Delete", value: "emojiDelete" },
  { name: "Emoji Update", value: "emojiUpdate" },
  { name: "Sticker Create", value: "stickerCreate" },
  { name: "Sticker Delete", value: "stickerDelete" },
  { name: "Sticker Update", value: "stickerUpdate" },
];

// Helper function to clear cache after updates
function clearLogCache(guildId) {
  const logData = getLogConfigData();
  if (logData.clearCache) logData.clearCache(guildId);
}

module.exports = {
  data: new SlashCommandBuilder()
    .setName("logs")
    .setDescription("🛡️ Manage the server logging system")
    .setDefaultMemberPermissions(PermissionFlagsBits.Administrator)
    .addSubcommand((sub) =>
      sub
        .setName("setup")
        .setDescription("📢 Set up the default log channel")
        .addChannelOption((opt) =>
          opt
            .setName("channel")
            .setDescription("The channel to send logs to")
            .addChannelTypes(ChannelType.GuildText)
            .setRequired(true)
        )
    )
    .addSubcommand((sub) =>
      sub
        .setName("channel")
        .setDescription("📂 Set a specific channel for an event type")
        .addStringOption((opt) =>
          opt
            .setName("event")
            .setDescription("The event type")
            .setRequired(true)
            .addChoices(...EVENT_TYPES)
        )
        .addChannelOption((opt) =>
          opt
            .setName("channel")
            .setDescription("The channel for this event")
            .addChannelTypes(ChannelType.GuildText)
            .setRequired(true)
        )
    )
    .addSubcommand((sub) =>
      sub
        .setName("color")
        .setDescription("🎨 Set a custom color for an event type")
        .addStringOption((opt) =>
          opt
            .setName("event")
            .setDescription("The event type")
            .setRequired(true)
            .addChoices(...EVENT_TYPES)
        )
        .addStringOption((opt) =>
          opt
            .setName("color")
            .setDescription("Color name or hex code (e.g., Red, #FF5733)")
            .setRequired(true)
        )
    )
    .addSubcommand((sub) =>
      sub
        .setName("toggle")
        .setDescription("🔄 Enable or disable an event type")
        .addStringOption((opt) =>
          opt
            .setName("event")
            .setDescription("The event type")
            .setRequired(true)
            .addChoices(...EVENT_TYPES)
        )
        .addStringOption((opt) =>
          opt
            .setName("action")
            .setDescription("Enable or disable")
            .setRequired(true)
            .addChoices(
              { name: "Enable", value: "enable" },
              { name: "Disable", value: "disable" }
            )
        )
    )
    .addSubcommand((sub) =>
      sub.setName("view").setDescription("📊 View current log configuration")
    )
    .addSubcommand((sub) =>
      sub
        .setName("reset")
        .setDescription("🗑️ Reset all log settings for this server")
    ),

  async run(client, interaction) {
    await interaction.deferReply({ ephemeral: true });

    const subcommand = interaction.options.getSubcommand();
    const guildId = interaction.guild.id;

    // ═══════════════════════════════════════════════════════
    // 📢 SETUP - Set default log channel
    // ═══════════════════════════════════════════════════════
    if (subcommand === "setup") {
      const channel = interaction.options.getChannel("channel");

      await Log.findOneAndUpdate(
        { guildId },
        { guildId, channelId: channel.id },
        { upsert: true, new: true }
      );

      clearLogCache(guildId); // Clear cache to apply changes immediately

      const embed = new EmbedBuilder()
        .setTitle("✅ Logging System Setup")
        .setDescription(`Logs will now be sent to ${channel}`)
        .setColor("Green")
        .setTimestamp();

      return interaction.editReply({ embeds: [embed] });
    }

    // ═══════════════════════════════════════════════════════
    // 📂 CHANNEL - Set specific channel for event
    // ═══════════════════════════════════════════════════════
    if (subcommand === "channel") {
      const event = interaction.options.getString("event");
      const channel = interaction.options.getChannel("channel");

      await Log.findOneAndUpdate(
        { guildId },
        { $set: { [`channels.${event}`]: channel.id } },
        { upsert: true }
      );

      clearLogCache(guildId);

      const eventName =
        EVENT_TYPES.find((e) => e.value === event)?.name || event;
      const embed = new EmbedBuilder()
        .setTitle("📂 Event Channel Updated")
        .setDescription(`**${eventName}** logs will now be sent to ${channel}`)
        .setColor("Blue")
        .setTimestamp();

      return interaction.editReply({ embeds: [embed] });
    }

    // ═══════════════════════════════════════════════════════
    // 🎨 COLOR - Set custom color for event
    // ═══════════════════════════════════════════════════════
    if (subcommand === "color") {
      const event = interaction.options.getString("event");
      const color = interaction.options.getString("color");

      await Log.findOneAndUpdate(
        { guildId },
        { $set: { [`colors.${event}`]: color } },
        { upsert: true }
      );

      clearLogCache(guildId);

      const eventName =
        EVENT_TYPES.find((e) => e.value === event)?.name || event;
      
      // Try to use the color, fallback to Blue if invalid
      let embedColor;
      try {
        embedColor = color;
      } catch {
        embedColor = "Blue";
      }

      const embed = new EmbedBuilder()
        .setTitle("🎨 Event Color Updated")
        .setDescription(
          `**${eventName}** embeds will now use color: \`${color}\``
        )
        .setColor(embedColor)
        .setTimestamp();

      return interaction.editReply({ embeds: [embed] });
    }

    // ═══════════════════════════════════════════════════════
    // 🔄 TOGGLE - Enable/Disable event
    // ═══════════════════════════════════════════════════════
    if (subcommand === "toggle") {
      const event = interaction.options.getString("event");
      const action = interaction.options.getString("action");

      if (action === "disable") {
        await Log.findOneAndUpdate(
          { guildId },
          { $addToSet: { disable: event } },
          { upsert: true }
        );
      } else {
        await Log.findOneAndUpdate(
          { guildId },
          { $pull: { disable: event } },
          { upsert: true }
        );
      }

      clearLogCache(guildId);

      const eventName =
        EVENT_TYPES.find((e) => e.value === event)?.name || event;
      const embed = new EmbedBuilder()
        .setTitle(
          action === "disable" ? "🚫 Event Disabled" : "✅ Event Enabled"
        )
        .setDescription(`**${eventName}** logging has been ${action}d`)
        .setColor(action === "disable" ? "Red" : "Green")
        .setTimestamp();

      return interaction.editReply({ embeds: [embed] });
    }

    // ═══════════════════════════════════════════════════════
    // 📊 VIEW - Show current configuration
    // ═══════════════════════════════════════════════════════
    if (subcommand === "view") {
      const config = await Log.findOne({ guildId });

      if (!config) {
        return interaction.editReply({
          content:
            "❌ No logging configuration found for this server. Use `/logs setup` first!",
        });
      }

      const channelsList = config.channels
        ? Object.entries(config.channels)
            .map(([k, v]) => {
              const eventName = EVENT_TYPES.find((e) => e.value === k)?.name || k;
              return `• **${eventName}**: <#${v}>`;
            })
            .join("\n") || "None"
        : "None";

      const colorsList = config.colors
        ? Object.entries(config.colors)
            .map(([k, v]) => {
              const eventName = EVENT_TYPES.find((e) => e.value === k)?.name || k;
              return `• **${eventName}**: \`${v}\``;
            })
            .join("\n") || "None"
        : "None";

      const disabledList =
        config.disable?.length > 0
          ? config.disable.map((e) => {
              const eventName = EVENT_TYPES.find((ev) => ev.value === e)?.name || e;
              return `• ${eventName}`;
            }).join("\n")
          : "None";

      const enabledCount = EVENT_TYPES.length - (config.disable?.length || 0);

      const embed = new EmbedBuilder()
        .setTitle("📊 Log Configuration")
        .setDescription(`**${enabledCount}/${EVENT_TYPES.length}** events are enabled`)
        .setColor("Blue")
        .addFields(
          {
            name: "📢 Default Channel",
            value: config.channelId ? `<#${config.channelId}>` : "Not set",
            inline: true,
          },
          {
            name: "📂 Custom Channels",
            value: channelsList.slice(0, 1024) || "None",
            inline: false,
          },
          {
            name: "🎨 Custom Colors",
            value: colorsList.slice(0, 1024) || "None",
            inline: false,
          },
          {
            name: "🚫 Disabled Events",
            value: disabledList.slice(0, 1024) || "None",
            inline: false,
          }
        )
        .setFooter({ text: `Guild ID: ${guildId}` })
        .setTimestamp();

      return interaction.editReply({ embeds: [embed] });
    }

    // ═══════════════════════════════════════════════════════
    // 🗑️ RESET - Delete all configuration
    // ═══════════════════════════════════════════════════════
    if (subcommand === "reset") {
      await Log.findOneAndDelete({ guildId });
      
      clearLogCache(guildId);

      const embed = new EmbedBuilder()
        .setTitle("🗑️ Configuration Reset")
        .setDescription(
          "All logging settings have been deleted for this server."
        )
        .setColor("Red")
        .setTimestamp();

      return interaction.editReply({ embeds: [embed] });
    }
  },
};