@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