🔥 CardForge

A powerful TypeScript library for generating beautiful, customizable card images

CardForge provides an easy-to-use API for creating stunning social media cards, welcome banners, music players, ranking systems, and relationship compatibility cards with professional designs and extensive customization options.

✨ Features

• 🎯 Welcome Cards - Futuristic cyber-themed welcome banners
• 🎵 Spotify Cards - Modern music player interfaces
• 📊 Rank Cards - Level/XP progress indicators
• 💕 Ship Cards - Relationship compatibility displays
• 🎨 Multiple Themes - Various pre-built design themes
• ⚙️ Full Customization - Colors, fonts, backgrounds, effects
• 🚀 TypeScript Support - Full type safety and intellisense
• 📱 High Quality Output - PNG images with crisp resolution

🖼️ Card Examples

Welcome Card

Futuristic cyber-themed welcome card with neon effects

Spotify Card

Modern music player with album art and progress bar

Rank Card

Level progression card with XP tracking

Ship Card

Relationship compatibility with modern glass design

📦 Installation

npm install cardforge

🚀 Quick Start

import { WelcomeCard, SpotifyCard, RankCard, ShipCard } from 'cardforge';
import fs from 'fs';

// Create a Welcome Card
const welcomeCard = new WelcomeCard()
  .setUsername('CyberUser')
  .setAvatar('https://example.com/avatar.jpg')
  .setWelcomeText('SYSTEM ONLINE')
  .setSubText('Welcome to the cybernetic network!')
  .setMemberCount(1337);

const buffer = await welcomeCard.build();
fs.writeFileSync('welcome.png', buffer);

📚 Card Types & Usage

🎯 Welcome Card

Create futuristic welcome banners with cyberpunk aesthetics.

const welcomeCard = new WelcomeCard()
  .setUsername('Username')
  .setAvatar('avatar-url')
  .setWelcomeText('Welcome!')
  .setSubText('Welcome message here')
  .setMemberCount(1234)
  .setTheme('cyber'); // cyber, neon, hologram, geometric, aurora

const buffer = await welcomeCard.build();

Available Themes:

• cyber - Blue/cyan cyberpunk (default)
• neon - Pink/green neon lights
• hologram - Purple holographic effects
• geometric - Green/teal geometric patterns
• aurora - Multi-color aurora effects

Customization Methods:

welcomeCard
  .setBackgroundColors(['#color1', '#color2'])
  .setTextColors('#welcome', '#sub', '#username')
  .setAvatarStyle('#borderColor', borderWidth)
  .setBackgroundImage('image-url');

🎵 Spotify Card

Modern music player interface with album art and controls.

const spotifyCard = new SpotifyCard()
  .setTrack('Song Name')
  .setArtist('Artist Name')
  .setAlbum('Album Name')
  .setAlbumArt('album-art-url')
  .setProgress(currentMs, totalMs)
  .setSpotifyLogo(true);

const buffer = await spotifyCard.build();

Features:

• Blurred album art background
• Progress bar with time display
• Official Spotify logo
• Custom background support
• 2000x565 optimal size for sharing

Customization Methods:

spotifyCard
  .setCustomBackground('background-url')
  .setBackgroundOpacity(0.7)
  .setSpotifyLogo(false);

📊 Rank Card

Level progression and XP tracking cards.

const rankCard = new RankCard()
  .setUsername('GameMaster')
  .setAvatar('avatar-url')
  .setLevel(42)
  .setXP(8750, 10000) // current, required
  .setRank(15);

const buffer = await rankCard.build();

Features:

• Animated progress bars
• Level badges
• XP tracking with abbreviations (K, M, B)
• Modern glass morphism design
• Customizable colors and effects

Customization Methods:

rankCard
  .setBackgroundColors(['#color1', '#color2'])
  .setProgressBarColors(['#progress'])
  .setTextColors('#username', '#xp', '#percentage')
  .setBadgeStyle(['#badge1', '#badge2'], '#border', '#text')
  .setAvatarStyle('#border', width)
  .setPattern(true, '#color', 0.1)
  .setEffects(true, true); // glow, shadow

💕 Ship Card

Relationship compatibility cards with modern design.

const shipCard = new ShipCard()
  .setUser1('Alice', 'avatar1-url')
  .setUser2('Bob', 'avatar2-url')
  .setShipPercentage(85);

const buffer = await shipCard.build();

Features:

• Glass morphism background
• Geometric connection elements
• Compatibility percentage
• Status labels in multiple languages
• Floating heart effects

Customization Methods:

shipCard
  .setTheme('romantic') // romantic, modern, minimal, neon
  .setBackgroundColors(['#color1', '#color2'])
  .setHeartColors(['#heart1', '#heart2'])
  .setConnectionLineColor('#line')
  .setAvatarStyle('#border', width)
  .setFloatingHearts(true, '#color')
  .setStatusLabels({
    perfectMatch: 'Mükemmel Eşleşme',
    greatChemistry: 'Harika Kimya',
    // ... other labels
  });

🎨 Theme System

Each card type supports multiple built-in themes:

Welcome Card Themes

• Cyber: Dark blue cyberpunk with cyan accents
• Neon: Black background with pink/green neon
• Hologram: Purple holographic effects
• Geometric: Teal/green geometric patterns
• Aurora: Multi-color gradient effects

Spotify Card Themes

• Modern: Clean minimal design (default)
• Classic: Traditional Spotify green
• Neon: Bright neon aesthetics

Rank Card Themes

• Blue: Professional blue gradients (default)
• Green: Nature-inspired greens
• Purple: Royal purple themes
• Orange: Energetic orange accents
• Red: Bold red styling

Ship Card Themes

• Modern: Clean glass morphism (default)
• Romantic: Warm pink/red tones
• Minimal: Simple black/white
• Neon: Bright cyberpunk colors

🛠️ Advanced Customization

Custom Backgrounds

// Image backgrounds
card.setBackgroundImage('https://example.com/bg.jpg');

// Gradient backgrounds
card.setBackgroundColors(['#ff6b6b', '#4ecdc4', '#45b7d1']);

Text Styling

// Custom text colors
welcomeCard.setTextColors('#ffffff', '#cccccc', '#00ffff');

// Custom fonts are supported via system fonts

Effects & Styling

// Enable/disable effects
rankCard.setEffects(true, true); // glow, shadow

// Pattern overlays
rankCard.setPattern(true, '#ffffff', 0.1); // show, color, opacity

// Avatar styling
card.setAvatarStyle('#ffffff', 6); // border color, width

📐 Output Specifications

| Card Type | Dimensions | Format | Typical Size | |-----------|------------|--------|--------------| | Welcome Card | 1000x450 | PNG | ~280KB | | Spotify Card | 2000x565 | PNG | ~320KB | | Rank Card | 800x200 | PNG | ~55KB | | Ship Card | 700x350 | PNG | ~55KB |

🔧 API Reference

Base Methods (All Cards)

card.build(): Promise<Buffer>        // Generate the card image

Welcome Card Methods

setUsername(username: string)
setAvatar(avatar: string)
setWelcomeText(text: string)
setSubText(text: string)
setMemberCount(count: number)
setTheme(theme: string)
setBackgroundColors(colors: string[])
setBackgroundImage(imageUrl: string)
setTextColors(welcome?, sub?, username?)
setAvatarStyle(borderColor?, borderWidth?)

Spotify Card Methods

setTrack(track: string)
setArtist(artist: string)
setAlbum(album: string)
setAlbumArt(albumArt: string)
setProgress(current: number, total: number)
setCustomBackground(background: string)
setSpotifyLogo(show: boolean)
setBackgroundOpacity(opacity: number)

Rank Card Methods

setUsername(username: string)
setAvatar(avatar: string)
setLevel(level: number)
setXP(current: number, required: number)
setRank(rank: number)
setBackground(background: string)
setBackgroundColors(colors: string[])
setProgressBarColors(colors: string[])
setTextColors(username?, xp?, percentage?)
setBadgeStyle(colors?, borderColor?, textColor?)
setAvatarStyle(borderColor?, borderWidth?)
setPattern(show: boolean, color?, opacity?)
setEffects(glow?: boolean, shadow?: boolean)

Ship Card Methods

setUser1(username: string, avatar: string)
setUser2(username: string, avatar: string)
setShipPercentage(percentage: number)
setBackground(background: string)
setTheme(theme: string)
setBackgroundColors(colors: string[])
setHeartColors(colors: string[])
setConnectionLineColor(color: string)
setPercentageCircleColors(colors: string[])
setUsernameTagColors(colors: string[])
setAvatarStyle(borderColor?, borderWidth?)
setFloatingHearts(show: boolean, color?)
setEffects(glow?: boolean, shadow?: boolean)
setStatusLabels(labels: object)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with @napi-rs/canvas for high-performance image generation
• Inspired by modern UI/UX design principles
• Special thanks to the TypeScript community