kira-arts 💞

A TypeScript library for generating Discord-style visual cards — profiles, welcome/leave events, level-ups, achievements, leaderboards, compatibility "ship" cards, now-playing music cards, and giveaways — rendered natively for speed and zero runtime dependencies on a browser or headless Chromium.

📚 Full documentation, live examples, and a Playground: documentation

✨ Features

• 🖼️ Profile, Welcome/Leave, Level Up, Achievement, Leaderboard, Ship (compatibility), Now Playing, Giveaway, Birthday, Marriage, Weekly Recap, and Code Snippet cards
• 🎵 Now Playing card ships with adapters for moonlink.js, Lavalink-based clients (erela.js, Shoukaku, Kazagumo, Riffy, Magmastream, lavalink-client), discord-player, and distube
• 💻 Code Snippet card renders syntax-highlighted code screenshots (JavaScript, TypeScript, Python, Java, C#, JSON, Bash, plaintext) in 6 built-in editor themes, without needing a Discord user ID
• 🎨 8 built-in themes (discord, midnight, sunset, neon, forest, sakura, monochrome, gold), Nitro/role-color aware borders, and up to 4 custom border colors with linear, mixed, or random blending
• 🧾 Output as png, jpeg, or webp, ready to use as a discord.js AttachmentBuilder via toAttachment()
• ⚡ Built-in, configurable in-memory cache for fetched user data (setCacheOptions, clearCache, getCacheSize)
• 🛡️ Typed error handling with KiraError and KiraErrorCode, instead of opaque runtime failures
• 📦 Dual package: ESM and CommonJS builds, both with full type declarations, no extra config needed
• 📐 Selectable size (compact, standard, wide) for Level Up cards, rendered as vectors so every size stays sharp
• 🏷️ Optional "NEW MEMBER" / "MEMBER LEFT" pill on Welcome/Leave cards, which can be hidden with showKindLabel: false

📦 Installation

npm install kira-arts
yarn add kira-arts
pnpm add kira-arts
bun add kira-arts

Requires Node.js >= 20 and a project with discord.js ^14.27.0 already installed (peer dependency).

🚀 Quick usage

import { Client, GatewayIntentBits } from "discord.js";
import { setClient, profileImage, toAttachment } from "kira-arts";

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});

client.once("clientReady", () => {
  setClient(client); // 👈 required before generating any card
});

client.on("messageCreate", async (message) => {
  if (message.author.bot || message.content !== "!card") return;

  const buffer = await profileImage(message.author.id, {
    guildId: message.guild?.id,
    useRoleColor: true,
    presenceStatus: message.member?.presence?.status,
    badgesFrame: true,
  });

  await message.reply({ files: [toAttachment(buffer, { name: "profile", extension: "png" })] });
});

client.login(process.env.TOKEN);

Every other card, the music adapters, theming, caching, error handling, and output options are documented with live examples at documentation.

🃏 Cards at a glance

| Card | Function | What it's for | | ------------ | ------------------------------------------------- | ----------------------------------------------------------- | | Profile | profileImage(userId, options) | Avatar, badges, nameplate, server tag, rank | | Welcome | welcomeImage(userId, guildName, options) | Member join events, with an optional hideable kind pill | | Leave | leaveImage(userId, guildName, options) | Member leave events, with an optional hideable kind pill | | Level Up | levelUpImage(userId, level, options) | XP progress bar on level-up, in compact/standard/wide sizes | | Achievement | achievementImage(userId, title, options) | Unlockable achievements with rarity tiers | | Leaderboard | leaderboardImage(entries, options) | Server ranking table | | Ship | shipImage(leftUserId, rightUserId, options) | Compatibility between two users | | Now Playing | nowPlayingImage(track, options) | Music player card with source detection | | Giveaway | giveawayImage(prize, options) | Prize, host, entry count, winners on end | | Birthday | birthdayImage(userId, options) | Balloons, confetti, and an optional age/years counter | | Marriage | marriageImage(leftUserId, rightUserId, options) | Certificate-style card with automatic days-together count | | Weekly Recap | weeklyRecapImage(userId, options) | Wrapped-style weekly summary with a 7-day activity chart | | Code Snippet | codeSnippetImage(code, options) | Carbon-style syntax-highlighted code screenshot |

🛠️ Utilities

| Function | What it's for | | ----------------------------------------------- | ---------------------------------------------------------------------- | | setClient(client) | Registers your discord.js client — required before generating any card | | toAttachment(buffer, name, format) | Wraps a card buffer into a discord.js AttachmentBuilder | | encodeCanvas(canvas, options) | Encodes a raw canvas to png / jpeg / webp | | extensionForFormat(format) | Returns the file extension for an OutputFormat | | setCacheOptions(options) | Configures the internal user-data cache (enable, TTL) | | clearCache() | Clears the internal user-data cache | | getCacheSize() | Returns the number of entries currently cached | | computeCompatibility(leftUserId, rightUserId) | Deterministic compatibility percentage for the Ship card | | pickShipMessage(leftId, rightId, percentage) | Flavor text matching a compatibility percentage | | getThemePalette(theme) | Resolves a KiraThemeName to its full color palette | | fromMoonlinkTrack(track) | Adapter: moonlink.js track → NowPlayingTrack | | fromLavalinkTrack(track) | Adapter: Lavalink-based clients → NowPlayingTrack | | fromDiscordPlayerTrack(track) | Adapter: discord-player track → NowPlayingTrack | | fromDistubeTrack(song) | Adapter: distube song → NowPlayingTrack | | extractRequesterId(track) | Pulls the requester's user ID out of any supported track |

THEMES (all 8 built-in palettes), KiraError / KiraErrorCode, and lower-level canvas/validation helpers (loadImageSafe, hexToRgb, hexToRgba, drawGradientBorder, drawCoverImage, parseHex, decimalToHex, parseImg, parsePng, isString, isNumber) are also exported for advanced use — see the documentation for details.

📄 License

Kira-Arts is released under the Apache-2.0 License.

Copyright © worddevs

🔗 Links

• 📚 Documentation: https://guide.worddevs.dev/docs/kira-arts
• 📦 NPM: https://www.npmjs.com/package/kira-arts
• 💻 Repository: https://github.com/worddevs/kira-arts
• 🐛 Issues: https://github.com/worddevs/kira-arts/issues
• 🔀 Contributing: https://github.com/worddevs/kira-arts/blob/main/CONTRIBUTING.md