@lunedusk/json2discord

Build discord.js embeds and Components V2 messages from plain JSON-like TypeScript objects. The package is framework-independent and returns discord.js builders or serialized component payloads ready for a send or reply call.

Install

npm install @lunedusk/json2discord discord.js

Requires Node.js 18 or newer and discord.js ^14.14.0.

Choose a path

Need	Start here
Build one or more embeds	Embed usage
Build a Components V2 layout	Components V2 usage
Use {{variables}} in a layout	Interpolation
Send local files or attachment URLs	Assets
Reuse configuration across builds	Reusable engines
Convert discord.js builders back to JSON	Round trips
Look up every exported type and function	API reference
Check Discord-facing limits	Limits and validation

Quick start

import { buildEmbedsFromJson } from '@lunedusk/json2discord';

const result = buildEmbedsFromJson({
  embeds: [{
    title: 'Hello {{user}}',
    description: 'Welcome to the server.',
    color: 0x5865f2,
    fields: [{ name: 'Latency', value: '{{latency}}ms', inline: true }],
  }],
}, { variables: { user: 'Vedant', latency: 42 } });

await channel.send({ embeds: result.embeds, files: result.files });

Components V2 builders return the flags value needed by Discord:

import { buildComponentsV2 } from '@lunedusk/json2discord';

const result = buildComponentsV2({
  version: 1,
  components: [{
    type: 'container',
    accentColor: 0x5865f2,
    children: [
      { type: 'text', content: '**{{title}}**' },
      { type: 'separator', spacing: 'small' },
      { type: 'text', content: '{{body}}' },
    ],
  }],
}, { variables: { title: 'Done', body: 'All good.' } });

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

Design notes

• Embed builds are lenient by default: long text is sanitized, field lists can be split, and output is clipped to Discord's message limits.
• buildEmbedsStrict rejects invalid or oversized input with EmbedEngineError.
• Components V2 validates its component tree and limits. Use buildComponentsV2AutoWrap when buttons and select menus should be grouped automatically; the default and strict helpers expect explicit rows.
• Unresolved variables remain unchanged, for example {{missing}}.

See usage for complete workflows and API reference for the public types. Contributions and support information are in CONTRIBUTING.md, SUPPORT.md, and SECURITY.md.

License

MIT