██████╗ ██╗███████╗ ██████╗ ██████╗ ██████╗ ███████╗
██   ██ ██║██   ██║██   ██║██   ██║██   ██║██   ██║
██████╔╝██║███████║██   ██║██████╔╝██████╔╝███   ██║
██   ██ ██║██   ██║██   ██║██   ██║██   ██║██   ██╝
██████╔╝██║███████║ ██████╔╝██████╔╝██████╔╝███████║
╚═════╝ ╚═╝╚══════╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚══════╝

discord-embed-builder

Fluent, validation-aware embeds. Emits pure Discord JSON.

zero dependencies - framework agnostic - node + bun

why a bare JSON builder?

Every Discord library has its own embed class. We always need:

• the same embed in Seyfert, discord.js, nextcord or a raw gateway payload
• limits checked before Discord rejects the message
• clean, testable object literals

So this package does one thing only - build and validate a plain embed object.

import { embed } from "@knownasrazi/discord-embed-builder";

const payload = embed()
  .setAuthor("Nazha", { iconURL: "https://cdn.nazha.bot/logo.png" })
  .setTitle("Now playing")
  .setDescription("**Midnight City** - M83")
  .setColor("#5865F2")
  .setThumbnail("https://cdn.nazha.bot/album.png")
  .addField("Progress", "1:42 / 4:04", true)
  .addField("Requested by", "razi", true)
  .setFooter("Powered by Nazha")
  .setTimestamp()
  .toJSON();

install

bun add @knownasrazi/discord-embed-builder
npm install @knownasrazi/discord-embed-builder

api

methods

| method | what it sets | | ------ | ------------ | | setTitle(text) | embed title | | setDescription(text) | embed description | | setURL(url) | title URL | | setColor(number \| hex) | #5865F2, 0x5865f2 or a color int | | setAuthor(name, { url, iconURL }) | author row | | setFooter(text, { iconURL }) | footer row | | setTimestamp(date?) | ISO timestamp (defaults to now) | | setThumbnail(url) | corner thumbnail | | setImage(url) | large image | | addField(name, value, inline?) | one field | | addFields(...fields) | several at once | | setFields(fields) | replace all fields | | clone() | deep, isolated copy | | size() | Discord character count | | validate() | list of problems (empty when ok) | | assertValid() | throws when invalid | | toJSON() | the embed object |

limits checked

| part | max | | ---- | --- | | author name | 256 | | title | 256 | | description | 4096 | | field name | 256 | | field value | 1024 | | fields | 25 | | footer | 2048 |

const issues = embed().setDescription("x".repeat(5000)).validate();
// [{ path: "description", message: "must be at most 4096 characters" }]

embed().setDescription("x".repeat(5000)).assertValid();
// throws Error: Invalid embed: [description] must be at most 4096 characters

output shape

toJSON() returns exactly what Discord's API expects - snake_case keys included:

{
  "title": "Now playing",
  "description": "**Midnight City** - M83",
  "color": 5793266,
  "author": { "name": "Nazha", "icon_url": "https://cdn.nazha.bot/logo.png" }
}

integration

// Seyfert
import { embed } from "@knownasrazi/discord-embed-builder";

await ctx.editOrReply({
  embeds: [embed().setTitle("Ping").setDescription(`${Math.round(ctx.client.gateway.latency)}ms`).toJSON()],
});

// discord.js
message.channel.send({
  embeds: [embed().setTitle("Ping").setDescription("pong").toJSON()],
});

development

git clone https://github.com/knownasrazi/discord-embed-builder.git
cd discord-embed-builder
bun install
bun test
bun run build
bun run lint

license

MIT + Razi

validated embeds. no surprises.