Build every Discord Components V2 message and modal with strict TypeScript,
fast serialization, actionable errors, and zero runtime dependencies.
Install · Quick start · Code generator · Validation · Benchmarks · Components
Discord components are small payloads, but general-purpose builder libraries often put a runtime
schema between your code and every payload. @buncord/builders takes a narrower approach for Bun:
- invalid literal combinations fail in TypeScript;
- dynamic values are checked again at runtime;
- builders serialize directly to Discord's wire shape;
- every component validation error carries a stable machine-readable code;
- no runtime dependency is added to
bun.lock.
The package deliberately supports Bun only. It ships TypeScript source, exposes a Bun CLI, and fails early when imported from another runtime. That focus keeps the package small and its support surface explicit.
| 20 component types Messages and modals |
Types + runtime Two validation layers |
0 dependencies Only your package |
Bun native workflow Source, tests and CLI |
bun add @buncord/buildersRequirements: Bun 1.1 or newer and TypeScript 5.x for compile-time diagnostics.
import {
ActionRowBuilder,
ButtonBuilder,
ButtonStyle,
ContainerBuilder,
MessageFlags,
SeparatorBuilder,
TextDisplayBuilder,
} from '@buncord/builders';
const components = [
new ContainerBuilder({ accentColor: [49, 120, 198] }).addComponents(
new TextDisplayBuilder({
content: '# Release ready\nBuild rich Discord messages with less ceremony.',
}),
new SeparatorBuilder({ divider: true }),
new ActionRowBuilder({
components: [
new ButtonBuilder({
customId: 'release:confirm',
label: 'Confirm',
style: ButtonStyle.Success,
}),
new ButtonBuilder({
label: 'Documentation',
style: ButtonStyle.Link,
url: 'https://docs.discord.com/developers/components/reference',
}),
],
}),
).toJSON(),
];
await fetch(webhookUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
flags: MessageFlags.IsComponentsV2,
components,
}),
});Components V2 messages require MessageFlags.IsComponentsV2. When this flag is present, Discord
uses components as the message body instead of legacy content and embeds fields.
The constructor API keeps literal information long enough for TypeScript to reject invalid combinations:
new ButtonBuilder({
style: ButtonStyle.Link,
url: 'https://bun.sh',
customId: 'not-allowed',
// Type error: Link buttons cannot carry customId or custom_id.
});Values typed as a general string or number cannot always be checked by TypeScript. Setters and
toJSON() therefore validate them at runtime as well.
import { isComponentError } from '@buncord/builders';
try {
component.toJSON();
} catch (error) {
if (isComponentError(error)) {
console.error(error.code);
console.error(error.path);
console.error(error.fix);
}
}Every validation failure raised by a builder or by the component-tree validator is a regular
Error carrying non-enumerable metadata. Existing logging behavior stays familiar:
instanceof Error works, Object.keys(error) stays empty, and JSON.stringify(error) stays {}.
Rules explicitly linked across the builder and auditor use the same code. Every other builder
failure uses a stable builder-family code instead of falling back to unstructured prose.
Turn a raw Discord payload into editable constructor code:
bunx buncord-builders generate payload.json --name release --output Release.ts| Input payload | Generated TypeScript |
|---|---|
{
"type": 1,
"components": [
{
"type": 2,
"style": 1,
"custom_id": "confirm",
"label": "Confirm"
}
]
} |
export const component = new ActionRowBuilder({
components: [
new ButtonBuilder({
style: ButtonStyle.Primary,
customId: "confirm",
label: "Confirm",
}),
],
}); |
The generator uses real constructors, so generated files retain the same compile-time guards as handwritten code. Unknown component fields are rejected instead of being silently discarded. The round-trip test executes generated code for all 20 supported component types and compares the resulting payload.
You can also call the generator directly:
import { generateComponentCode } from '@buncord/builders';
const source = generateComponentCode(payload, {
variableName: 'release',
moduleName: '@buncord/builders',
});auditTree() collects every issue it can find without throwing. It is suitable for CI, migration
scripts, support tools, and debugging raw payloads.
import { BaseComponent } from '@buncord/builders';
const issues = BaseComponent.auditTree(payload, { structured: true });
for (const issue of issues) {
console.warn(`${issue.code} at ${issue.path || '(root)'}`);
console.warn(issue.fix);
}The same checks are available from the CLI:
bunx buncord-builders validate payload.json
bunx buncord-builders explain payload.json
bunx buncord-builders explain payload.json --json
bunx buncord-builders validate modal.json --context modal
cat payload.json | bunx buncord-builders validate -| Exit code | Meaning |
|---|---|
0 |
Valid payload |
1 |
Discord component validation failed |
2 |
Invalid command, unreadable file, or malformed JSON |
The auditor checks required fields, component and text budgets, duplicate custom_id values,
container layouts, section accessories, Action Row combinations, modal inputs, select defaults,
integer bounds, file uploads, and cyclic trees.
Discord does not publish a versioned component schema. The package therefore records when its constraints were checked and separates the official reference from community material:
import { SPEC_PROVENANCE } from '@buncord/builders';
SPEC_PROVENANCE.verifiedOn;
SPEC_PROVENANCE.primaryReference;
SPEC_PROVENANCE.secondaryReferences;
SPEC_PROVENANCE.exceptions;The authoritative source is the
Discord component reference. Any rule
that cannot be proven from that reference is listed explicitly in SPEC_PROVENANCE.exceptions and
pinned by a regression test.
Measure the workload you actually send. toJSON() produces a JavaScript object; encoding it with JSON.stringify() is a separate cost.
Sample generated on 2026-09-17 · Bun 1.4.2 · linux x64. Each trial builds 100000 rows: 50000 with one button and 50000 with one string select. The script warms up each library, alternates their order and reports measured medians and ranges. See the console output for trial counts and the CPU model. Installed comparison: @discordjs/builders 1.14.1.
| Work for 100000 rows | @discordjs/builders |
@buncord/builders |
|---|---|---|
| Construction | 94.59 ms | 14.92 ms |
Conversion with toJSON() |
33.84 ms | 13.16 ms |
| Construction + conversion | 122.77 ms | 28.08 ms |
That is approximately 4.4× throughput for construction and conversion on this sample, or 0.281 µs per row. Phase medians need not sum to the total median. Payload equality is checked before timing and encoded outputs are consumed. This excludes HTTP and Discord processing. Hardware, GC, runtime, payload and validation behavior affect results; this is not a latency guarantee or an equivalent-validation comparison.
bun run benchmark:ciBoth libraries produce byte-identical JSON for these rows, so JSON.stringify is the engine's cost rather than the library's and is not charted. Measured on its own, with the heap collected between runs and the order alternated, encoding lands at parity: 34.46 ms against 35.47 ms over 100000 rows.
For repeated static messages, build the payload and JSON body once and reuse them. A displayed 0.00 ms is rounding, not zero work.
graph LR
classDef root fill:#5865F2,color:#fff,stroke:none
classDef modal fill:#FF3B92,color:#fff,stroke:none
classDef layout fill:#2B2D31,color:#fff,stroke:#5865F2
classDef leaf fill:#1E1F22,color:#DBDEE1,stroke:#4E5058
Message([Message]):::root --> Container[Container]:::layout
Message --> Row[Action Row]:::layout
Container --> Section[Section]:::layout
Container --> Content[Text · Media · File · Separator]:::leaf
Container --> Row
Section --> Accessory[Text · Button · Thumbnail]:::leaf
Row --> Interactive[Buttons · Select menus]:::leaf
Modal([Modal]):::modal --> Label[Label]:::layout
Modal --> ModalText[Text Display]:::leaf
Modal --> LegacyRow[Legacy Action Row]:::layout
Label --> Inputs[Text · Select · Radio · Checkbox · File upload]:::leaf
| Context | Builders |
|---|---|
| Layout | ActionRowBuilder, SectionBuilder, ContainerBuilder, LabelBuilder |
| Content | TextDisplayBuilder, ThumbnailBuilder, MediaGalleryBuilder, FileBuilder, SeparatorBuilder |
| Interactive | ButtonBuilder, five select-menu builders |
| Modal inputs | TextInputBuilder, FileUploadBuilder, RadioGroupBuilder, CheckboxGroupBuilder, CheckboxBuilder |
| Utilities | ModalBuilder, SmartLayoutBuilder, ComponentFactory |
All 20 component types bots can currently send are implemented. Discord's non-sendable
CONTENT_INVENTORY_ENTRY (16) and CHECKPOINT_CARD (20) values remain available in
ComponentType, without builders that would imply bot support.
toJSON() returns a minimal Discord payload and never mutates the builder. Depending on the
component, it may return its internal data or construct a payload while serializing nested
builders. Treat returned payloads as read-only unless you explicitly clone them.
const first = new ButtonBuilder({
customId: 'page:1',
label: 'Page 1',
style: ButtonStyle.Primary,
});
const second = first.clone().setCustomId('page:2').setLabel('Page 2');Unset optional values are omitted. Nested builders are converted to Discord's snake_case wire format only when serialized.
The API intentionally resembles @discordjs/builders, while constructor options preserve literal
types for stronger diagnostics.
const familiar = new ButtonBuilder()
.setCustomId('confirm')
.setLabel('Confirm')
.setStyle(ButtonStyle.Success);
const inferred = new ButtonBuilder({
customId: 'confirm',
label: 'Confirm',
style: ButtonStyle.Success,
});
type ButtonIds = ExtractButtonIds<typeof inferred>; // 'confirm'Use ComponentFactory.from() when rebuilding runtime builders from raw payloads. Use the CLI when
you want editable TypeScript source with compile-time validation.
| File | Demonstrates |
|---|---|
quick-start.ts |
Complete Components V2 message |
smart-layout.ts |
Automatic Action Row packing |
modals.ts |
Current modal input components |
validation.ts |
Runtime validation and auditing |
webhook.ts |
Sending a webhook payload |
bun run exemples/quick-start.tsbun install
bun run typecheck
bun test
bun run benchmark:ci
bun run benchmark:payload -- --verify-onlyThe project uses strict TypeScript with exactOptionalPropertyTypes,
noUncheckedIndexedAccess, and isolatedModules. See CONTRIBUTING.md before
submitting a change.
Built by buncord's team.
The tests, JSDocs and code comments in this repository were generated by an AI and subsequently reviewed and reworked by a human.