or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdcomponents-v2.mdcontext-menu-commands.mdembeds.mdindex.mdmessage-components.mdmodals.mdselect-menus.mdslash-commands.mdutilities.md
tile.json

index.mddocs/

@discordjs/builders

@discordjs/builders is a TypeScript utility library providing type-safe builders for Discord API payloads. It offers a fluent, chainable API for constructing Discord components including slash commands, embeds, buttons, select menus, modals, and other message components with proper validation and type checking. Built for the Discord.js ecosystem, it ensures compliance with Discord API v10 specifications.

Package Information

  • Package Name: @discordjs/builders
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @discordjs/builders

Core Imports

import { 
  SlashCommandBuilder,
  EmbedBuilder,
  ButtonBuilder,
  ActionRowBuilder
} from "@discordjs/builders";

For CommonJS:

const { 
  SlashCommandBuilder,
  EmbedBuilder,
  ButtonBuilder,
  ActionRowBuilder
} = require("@discordjs/builders");

Basic Usage

import { SlashCommandBuilder, EmbedBuilder, ButtonBuilder, ActionRowBuilder } from "@discordjs/builders";

// Create a slash command
const pingCommand = new SlashCommandBuilder()
  .setName('ping')
  .setDescription('Replies with Pong!');

// Create an embed
const embed = new EmbedBuilder()
  .setTitle('Hello Discord!')
  .setDescription('This is a sample embed')
  .setColor(0x00AE86);

// Create a button
const button = new ButtonBuilder()
  .setCustomId('primary')
  .setLabel('Click me!')
  .setStyle(1); // Primary style

// Add button to action row
const row = new ActionRowBuilder()
  .addComponents(button);

Architecture

@discordjs/builders is organized around several key patterns:

  • Builder Pattern: All components use chainable methods for configuration
  • Type Safety: Full TypeScript support with Discord API v10 type definitions
  • Validation: Runtime validation using @sapphire/shapeshift for parameter checking
  • Mixins: Shared functionality through TypeScript mixins for slash commands
  • JSON Serialization: All builders implement toJSON() for Discord API compatibility

Capabilities

Slash Commands

Complete slash command builder system with support for options, subcommands, subcommand groups, and localization. Includes all Discord slash command option types.

class SlashCommandBuilder {
  setName(name: string): this;
  setDescription(description: string): this;
  addStringOption(input: (builder: SlashCommandStringOption) => SlashCommandStringOption): this;
  addIntegerOption(input: (builder: SlashCommandIntegerOption) => SlashCommandIntegerOption): this;
  addBooleanOption(input: (builder: SlashCommandBooleanOption) => SlashCommandBooleanOption): this;
  addUserOption(input: (builder: SlashCommandUserOption) => SlashCommandUserOption): this;
  addChannelOption(input: (builder: SlashCommandChannelOption) => SlashCommandChannelOption): this;
  addRoleOption(input: (builder: SlashCommandRoleOption) => SlashCommandRoleOption): this;
  addMentionableOption(input: (builder: SlashCommandMentionableOption) => SlashCommandMentionableOption): this;
  addNumberOption(input: (builder: SlashCommandNumberOption) => SlashCommandNumberOption): this;
  addAttachmentOption(input: (builder: SlashCommandAttachmentOption) => SlashCommandAttachmentOption): this;
  addSubcommand(input: (subcommandGroup: SlashCommandSubcommandBuilder) => SlashCommandSubcommandBuilder): this;
  addSubcommandGroup(input: (subcommandGroup: SlashCommandSubcommandGroupBuilder) => SlashCommandSubcommandGroupBuilder): this;
  toJSON(): RESTPostAPIApplicationCommandsJSONBody;
}

Slash Commands

Message Embeds

Rich embed builder for creating complex message embeds with fields, images, thumbnails, authors, and footers.

class EmbedBuilder {
  setTitle(title: string): this;
  setDescription(description: string): this;
  setURL(url: string): this;
  setTimestamp(timestamp?: Date | number | null): this;
  setColor(color: number | string | null): this;
  setThumbnail(url: string): this;
  setImage(url: string): this;
  setAuthor(options: EmbedAuthorOptions): this;
  setFooter(options: EmbedFooterOptions): this;
  addFields(...fields: APIEmbedField[]): this;
  spliceFields(index: number, deleteCount: number, ...fields: APIEmbedField[]): this;
  setFields(...fields: APIEmbedField[]): this;
  toJSON(): APIEmbed;
}

Embeds

Message Components

Interactive message components including buttons, select menus, text inputs, and action rows for organizing components.

class ButtonBuilder {
  setStyle(style: ButtonStyle): this;
  setURL(url: string): this;
  setCustomId(customId: string): this;
  setEmoji(emoji: APIMessageComponentEmoji): this;
  setDisabled(disabled?: boolean): this;
  setLabel(label: string): this;
  setSKUId(skuId: Snowflake): this;
  toJSON(): APIButtonComponent;
}

class ActionRowBuilder<T extends AnyComponentBuilder> {
  addComponents(...components: T[]): this;
  setComponents(...components: T[]): this;
  spliceComponents(index: number, deleteCount: number, ...components: T[]): this;
  toJSON(): APIActionRowComponent;
}

Message Components

Select Menus

Various select menu types for user selection including string, user, role, channel, and mentionable select menus.

class StringSelectMenuBuilder {
  setCustomId(customId: string): this;
  setPlaceholder(placeholder: string): this;
  setMinValues(minValues: number): this;
  setMaxValues(maxValues: number): this;
  setDisabled(disabled?: boolean): this;
  addOptions(...options: StringSelectMenuOptionBuilder[]): this;
  setOptions(...options: StringSelectMenuOptionBuilder[]): this;
  toJSON(): APIStringSelectComponent;
}

Select Menus

Modals

Modal dialog builders with text input components for collecting user input.

class ModalBuilder {
  setTitle(title: string): this;
  setCustomId(customId: string): this;
  addComponents(...components: ActionRowBuilder<ModalActionRowComponentBuilder>[]): this;
  setComponents(...components: ActionRowBuilder<ModalActionRowComponentBuilder>[]): this;
  toJSON(): APIModalInteractionResponseCallbackData;
}

Modals

Context Menu Commands

Builder for application context menu commands (user and message context menus).

class ContextMenuCommandBuilder {
  setName(name: string): this;
  setType(type: ContextMenuCommandType): this;
  setNameLocalizations(localizations: LocalizationMap): this;
  setDefaultMemberPermissions(permissions: Permissions | bigint | number | null | undefined): this;
  setDMPermission(enabled: boolean | null | undefined): this;
  toJSON(): RESTPostAPIContextMenuApplicationCommandsJSONBody;
}

Context Menu Commands

Components v2

Enhanced Discord Components v2 for rich media and content display including containers, media galleries, files, and advanced text display.

class ContainerBuilder {
  setAccentColor(color?: RGBTuple | number): this;
  clearAccentColor(): this;
  addActionRowComponents(...components: RestOrArray<ActionRowBuilder<AnyComponentBuilder>>): this;
  addFileComponents(...components: RestOrArray<FileBuilder>): this;
  addMediaGalleryComponents(...components: RestOrArray<MediaGalleryBuilder>): this;
  addTextDisplayComponents(...components: RestOrArray<TextDisplayBuilder>): this;
  setSpoiler(spoiler?: boolean): this;
  toJSON(): APIContainerComponent;
}

class MediaGalleryBuilder {
  addItems(...items: RestOrArray<MediaGalleryItemBuilder>): this;
  setItems(...items: RestOrArray<MediaGalleryItemBuilder>): this;
  toJSON(): APIMediaGalleryComponent;
}

Components v2

Assertion Modules

Validation functions and error checking for all builder types, providing early validation before Discord API calls.

namespace EmbedAssertions {
  function validateColor(color: RGBTuple | number | null): void;
  function validateTitle(title: string | null): void;
  function validateDescription(description: string | null): void;
}

namespace ComponentAssertions {
  function validateButtonLabel(label?: string): void;
  function validateCustomId(customId: string): void;
  function validateEmoji(emoji: APIMessageComponentEmoji): void;
}

Assertions

Utilities and Types

Utility functions, validation helpers, and TypeScript type definitions for working with Discord components.

function embedLength(data: APIEmbed): number;
function normalizeArray<T>(arr: RestOrArray<T>): T[];
function isValidationEnabled(): boolean;
function disableValidators(): void;
function enableValidators(): void;

type RestOrArray<T> = T[] | readonly T[];
type RGBTuple = [red: number, green: number, blue: number];

Utilities

Types

type MessageComponentBuilder = 
  | ActionRowBuilder<MessageActionRowComponentBuilder>
  | MessageActionRowComponentBuilder;

type ModalComponentBuilder = 
  | ActionRowBuilder<ModalActionRowComponentBuilder> 
  | ModalActionRowComponentBuilder;

type MessageActionRowComponentBuilder =
  | ButtonBuilder
  | ChannelSelectMenuBuilder
  | MentionableSelectMenuBuilder
  | RoleSelectMenuBuilder
  | StringSelectMenuBuilder
  | UserSelectMenuBuilder;

type ModalActionRowComponentBuilder = TextInputBuilder;

type AnyComponentBuilder = MessageActionRowComponentBuilder | ModalActionRowComponentBuilder;

type ContextMenuCommandType = ApplicationCommandType.Message | ApplicationCommandType.User;

interface EmbedAuthorOptions {
  name: string;
  url?: string;
  iconURL?: string;
}

interface EmbedFooterOptions {
  text: string;
  iconURL?: string;
}

interface IconData {
  iconURL?: string;
  proxyIconURL?: string;
}