discord-html-canvas

🎨 Discord HTML Canvas

Generate beautiful Discord images from HTML/CSS instead of tedious canvas manipulation.

💡 The Problem

Creating rank cards, welcome images, or custom graphics for Discord bots currently requires:

// ❌ The old way - tedious manual canvas work
const canvas = createCanvas(800, 400);
const ctx = canvas.getContext('2d');

ctx.fillStyle = '#7289DA';
ctx.fillRect(0, 0, 800, 400);
ctx.font = 'bold 42px Arial';
ctx.fillStyle = '#FFFFFF';
ctx.fillText('Username', 120, 80);
ctx.beginPath();
ctx.arc(60, 60, 50, 0, Math.PI * 2);
// ... 50 more lines of coordinate calculations

✨ The Solution

// ✅ The new way - write HTML/CSS, get an image
const html = `
    <div style="width: 800px; height: 400px; background: #7289DA; 
                display: flex; align-items: center; padding: 20px;">
        <img src="${avatar}" style="width: 100px; height: 100px; border-radius: 50%;" />
        <h1 style="color: white; margin-left: 20px;">Username</h1>
    </div>
`;

const buffer = await renderHtmlToBuffer(html);
// Done! Send to Discord

Save hours of development time. Build what you imagine, not what coordinates allow.

🚀 Features

• 🎨 Design with HTML/CSS - Use the tools you already know
• 📦 Pre-built Templates - Rank cards, welcome images, level-up cards
• 🔄 Library Agnostic - Works with discord.js v14+ and Eris v0.17+
• ⚡ Type-Safe - Full TypeScript support with comprehensive types
• 🎯 Production Ready - Powered by Satori (by Vercel)
• 🖼️ Image Optimization - Automatic PNG conversion with high quality
• 🔤 Custom Fonts - Load and use your own TTF/OTF/WOFF fonts
• 📊 Modern CSS - Gradients, flexbox, shadows, and more
• 🚀 Lightweight - Minimal dependencies, maximum performance
• 💾 Zero Dependencies - discord.js and Eris are optional peer deps

📦 Installation

npm install discord-html-canvas

Peer Dependencies

For Discord.js:

npm install discord.js@^14.0.0

For Eris:

npm install eris@^0.17.0

🎯 Quick Start

Simple Example

import { renderHtmlToBuffer } from 'discord-html-canvas';

const html = `
    <div style="width: 800px; height: 400px; background: linear-gradient(to right, #667eea, #764ba2); 
                color: white; display: flex; flex-direction: column; justify-content: center; 
                align-items: center; font-family: Arial;">
        <h1 style="font-size: 48px; margin: 0;">Welcome to the Server!</h1>
        <p style="font-size: 24px; margin-top: 20px;">You are member #1234</p>
    </div>
`;

const buffer = await renderHtmlToBuffer(html);
// Send buffer to Discord as attachment

Using Pre-built Templates

import { createRankCard, renderHtmlToBuffer } from 'discord-html-canvas';

const html = createRankCard({
    username: 'CoolUser',
    discriminator: '0001',
    avatar: 'https://cdn.discordapp.com/avatars/...',
    level: 42,
    currentXP: 7500,
    requiredXP: 10000,
    rank: 15,
    accentColor: '#7289DA',
});

const buffer = await renderHtmlToBuffer(html);

With Discord.js

import { Client, AttachmentBuilder } from 'discord.js';
import { createWelcomeCard, renderHtmlToBuffer } from 'discord-html-canvas';

client.on('guildMemberAdd', async (member) => {
    const html = createWelcomeCard({
        username: member.user.username,
        avatar: member.user.displayAvatarURL({ extension: 'png' }),
        guildName: member.guild.name,
        memberCount: member.guild.memberCount,
    });

    const buffer = await renderHtmlToBuffer(html);
    const attachment = new AttachmentBuilder(buffer, { name: 'welcome.png' });

    await member.guild.systemChannel?.send({
        content: `Welcome ${member}!`,
        files: [attachment],
    });
});

📚 Pre-built Templates

Rank Card

Perfect for leveling systems and leaderboards.

import { createRankCard } from 'discord-html-canvas';

const html = createRankCard({
    username: 'EliteGamer',
    discriminator: '1337',
    avatar: 'https://...',
    level: 99,
    currentXP: 15000,
    requiredXP: 20000,
    rank: 3,
    backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    accentColor: '#FFD700',
});

Features:

• User avatar with styled border
• Username and discriminator
• Level and rank display
• Progress bar with XP stats
• Customizable colors and gradients
• Optional background image

Welcome Card

Beautiful welcome images for new members.

import { createWelcomeCard } from 'discord-html-canvas';

const html = createWelcomeCard({
    username: 'NewMember',
    avatar: 'https://...',
    guildName: 'Awesome Server',
    memberCount: 5000,
    message: 'Welcome to our community!',
    backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
});

Features:

• User avatar
• Custom welcome message
• Guild name and member count
• Customizable background
• Professional styling

Level Up Card

Celebrate level milestones.

import { createLevelUpCard } from 'discord-html-canvas';

const html = createLevelUpCard({
    username: 'ProPlayer',
    avatar: 'https://...',
    oldLevel: 49,
    newLevel: 50,
    backgroundColor: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
    accentColor: '#FFD700',
});

🎨 Advanced Usage

Custom Styling

Use modern CSS features:

const html = `
    <div style="width: 1000px; height: 600px; 
                background: linear-gradient(135deg, #1e3c72 0%, #7e8ba3 100%);
                border-radius: 20px; 
                padding: 40px; 
                display: flex; 
                flex-direction: column;
                font-family: Arial;">
        
        <div style="display: flex; gap: 20px;">
            <div style="flex: 1; 
                        background: rgba(255,255,255,0.1); 
                        border-radius: 15px; 
                        padding: 25px;
                        box-shadow: 0 8px 16px rgba(0,0,0,0.2);">
                <h2 style="color: #FFD700; font-size: 24px;">Wins</h2>
                <p style="color: white; font-size: 64px; font-weight: bold;">1,234</p>
            </div>
            
            <div style="flex: 1; 
                        background: rgba(255,255,255,0.1); 
                        border-radius: 15px; 
                        padding: 25px;">
                <h2 style="color: #FF6B6B; font-size: 24px;">Losses</h2>
                <p style="color: white; font-size: 64px; font-weight: bold;">567</p>
            </div>
        </div>
    </div>
`;

Custom Fonts

Load and use your own fonts:

import { HtmlCanvas } from 'discord-html-canvas';
import { readFileSync } from 'fs';

const canvas = new HtmlCanvas();

// Load custom font
const fontData = readFileSync('./fonts/MyCustomFont.ttf');
await canvas.loadFont({
    name: 'CustomFont',
    data: fontData,
    weight: 400,
    style: 'normal',
});

const html = `
    <div style="font-family: CustomFont; font-size: 48px; color: white;">
        Using my custom font!
    </div>
`;

const buffer = await canvas.render(html);

Using the Adapter Pattern

For easier integration with Discord libraries:

import { HtmlCanvas, DiscordJSAdapter } from 'discord-html-canvas';
import { Client } from 'discord.js';

const client = new Client({ ... });
const canvas = new HtmlCanvas();
const adapter = new DiscordJSAdapter(client);

// Send image to channel
await adapter.sendImageToChannel('channel-id', buffer, 'image.png');

// Reply to message
await adapter.replyWithImage(message, buffer, 'reply.png');

// Reply to interaction
await adapter.sendImageAsAttachment(interaction, buffer, 'response.png');

📖 API Reference

renderHtmlToBuffer(html, options?)

Simple function to convert HTML to PNG buffer.

Parameters:

• html: string - HTML string to render
• options?: RenderOptions - Optional rendering options

Returns: Promise<Buffer> - PNG image buffer

Example:

const buffer = await renderHtmlToBuffer(html, {
    width: 800,
    height: 400,
    backgroundColor: '#ffffff',
});

class HtmlCanvas

Main rendering class with advanced options.

Constructor

new HtmlCanvas(defaultOptions?: RenderOptions)

Methods

• render(html: string, options?: RenderOptions): Promise<Buffer | string> - Render HTML to image
• setDefaultOptions(options: RenderOptions): void - Set default render options
• loadFont(font: FontOptions): Promise<void> - Load and cache a font
• clearFontCache(): void - Clear cached fonts

RenderOptions

interface RenderOptions {
    width?: number;          // Default: 800
    height?: number;         // Default: 400
    fonts?: FontOptions[];   // Custom fonts
    backgroundColor?: string; // Default: '#ffffff'
    format?: 'png' | 'svg';  // Default: 'png'
}

FontOptions

interface FontOptions {
    name: string;                    // Font family name
    data: ArrayBuffer | Buffer;      // Font file data
    weight?: number;                 // Font weight (100-900)
    style?: 'normal' | 'italic';    // Font style
}

Template Functions

• createRankCard(data: RankCardData): string
• createWelcomeCard(data: WelcomeCardData): string
• createLevelUpCard(data: LevelUpData): string

See TypeScript definitions for complete data interfaces.

🎯 Use Cases

Leveling Systems

• Rank cards showing XP and progress
• Level-up announcements
• Leaderboard graphics

Welcome Systems

• Custom welcome images
• Server rules cards
• Member milestone celebrations

Statistics

• Gaming stats cards
• Server analytics
• User profiles

Notifications

• Achievement unlocked
• Role assignments
• Event announcements

🔄 Migration from Manual Canvas

Before (with @napi-rs/canvas):

const canvas = createCanvas(800, 400);
const ctx = canvas.getContext('2d');

// Background
ctx.fillStyle = '#7289DA';
ctx.fillRect(0, 0, 800, 400);

// Avatar (requires loading image first)
const avatarImg = await loadImage(avatarURL);
ctx.save();
ctx.beginPath();
ctx.arc(100, 100, 50, 0, Math.PI * 2);
ctx.closePath();
ctx.clip();
ctx.drawImage(avatarImg, 50, 50, 100, 100);
ctx.restore();

// Text (manual positioning)
ctx.font = 'bold 42px Arial';
ctx.fillStyle = '#FFFFFF';
ctx.fillText('Username', 170, 90);

// Progress bar (manual calculations)
const barWidth = 500;
const barHeight = 30;
const progress = (7500 / 10000) * barWidth;
ctx.fillStyle = '#2C2F33';
ctx.fillRect(50, 250, barWidth, barHeight);
ctx.fillStyle = '#3BA55C';
ctx.fillRect(50, 250, progress, barHeight);

After (with discord-html-canvas):

const html = createRankCard({
    username: 'Username',
    avatar: avatarURL,
    level: 42,
    currentXP: 7500,
    requiredXP: 10000,
    rank: 15,
});

const buffer = await renderHtmlToBuffer(html);

Result: Same output, 90% less code, infinitely more maintainable.

⚡ Performance

• Fast: Satori is optimized for server-side rendering
• Efficient: Cached fonts reduce repeated file reads
• Scalable: Handle concurrent requests easily
• Lightweight: Minimal bundle size

🤝 Contributing

Contributions are welcome! Please check out the Contributing Guide.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Satori by Vercel
• Powered by @resvg/resvg-js for PNG conversion
• Created with ❤️ by Jersuxs

🔗 Links

• NPM Package
• GitHub Repository
• Issue Tracker
• Discord.js Documentation
• Eris Documentation

⭐ Star us on GitHub if you find this helpful!

Stop calculating coordinates. Start creating beautiful images.