A TypeScript-based CLI tool that creates beautiful circular badges with icons and text. Perfect for generating custom badges for projects, achievements, or any visual identification needs.
- 🎨 Beautiful circular badges with customizable colors
- 🎯 Rich icon library powered by Lucide icons
- 📝 Custom text labels with automatic sizing
- 🎭 Interactive CLI for easy badge creation
- 🖼️ PNG output with high-quality rendering
- 🎨 Predefined color palette for consistent styling
- 📁 Organized output saves badges to
my-badges/folder
This is a personal hobby project. While contributions are welcome, please don't expect:
- Regular updates or releases
- Immediate responses to issues/PRs
- Long-term maintenance commitments
Feel free to fork and adapt for your own needs!
Perfect for a consistent development environment:
# Prerequisites: VS Code + Dev Containers extension + Docker
git clone https://github.com/leejsinclair/badge-cli-generator.git
cd badge-cli-generator
code .
# Click "Reopen in Container" when prompted# Clone the repository
git clone https://github.com/leejsinclair/badge-cli-generator.git
cd badge-cli-generator
# Install dependencies
npm install
# Build the project
npm run build
# Generate your first badge
npm start generate$ npm start generate
✔ Enter the badge text: Example
✔ Choose an SVG icon: zap.svg
✔ Choose a color: secondary
✔ Enter the output filename (without extension): example-badge
✔ Enter the badge size (optional): 200
Generating badge...
Badge generated successfully: my-badges/example-badge.png
Choose from our carefully selected color palette:
| Color | Hex Code | Preview |
|---|---|---|
| primary | #FF6B6B | 🔴 Red |
| secondary | #4ECDC4 | 🩵 Teal |
| accent | #45B7D1 | 🔵 Blue |
| success | #8AC46B | 🟢 Green |
| warning | #FFD66B | 🟡 Yellow |
| info | #6B88FF | 🟣 Purple |
| error | #FF6B87 | 🔴 Pink |
The generator includes hundreds of icons from the Lucide icon library. Popular choices include:
star.svg- Perfect for achievementsheart.svg- Great for favoriteszap.svg- Ideal for energy/power themesshield.svg- Security and protectiontrophy.svg- Awards and competitionscheck.svg- Completion and success- And hundreds more!
Use the included development container for a consistent environment:
- Node.js 20, all dependencies pre-installed
- VS Code extensions and settings configured
- See .devcontainer/README.md for details
- Node.js 18+ and npm
- Canvas dependencies (automatically handled)
npm install
npm run build
npm testIf you're using the dev container and encounter git authentication issues:
-
Authenticate with GitHub CLI (recommended):
gh auth login --git-protocol https
Choose "Paste an authentication token" and use a Personal Access Token with
reposcope. -
If you see SSH errors, ensure the remote uses HTTPS:
git remote set-url origin https://github.com/leejsinclair/badge-cli-generator.git
The dev container includes all necessary tools (Git, Node.js, GitHub CLI) pre-configured for development.
npm run build- Download icons and compile TypeScriptnpm start generate- Run the badge generatornpm run dev generate- Development mode with ts-nodenpm test- Run test suitenpm run lint- Lint codenpm run format- Format code with Prettier
- Badge Generator: Core class handling canvas rendering
- Components: Modular rendering system (Background, Icon, TextBox)
- CLI Interface: Interactive command-line tool
- Icon Management: Automated SVG icon downloading and processing
- Type Safety: Full TypeScript implementation with comprehensive types
Comprehensive test suite covering:
- Color validation and conversion
- Background rendering logic
- Icon processing and scaling
- Text box rendering and positioning
npm test # Run all tests
npm run test:watch # Run tests in watch modeWe welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Commit using Conventional Commits
- Push to your fork and submit a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Lucide for the beautiful icon library
- Canvas API for high-quality image rendering
- Inquirer for the interactive CLI experience
import { BadgeGenerator } from './badge-generator'
const generator = new BadgeGenerator()
await generator.createBadge({
text: 'Achievement',
color: 'primary',
icon: 'star.svg',
output: 'my-achievement.png',
size: 200, // optional, defaults to 200
})interface BadgeConfig {
text: string // Text to display
color: ColorName // Color from predefined palette
icon?: string // SVG icon filename (optional)
output: string // Output filename
size?: number // Badge size in pixels (optional)
}⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature
Made with ❤️ by the Badge Generator team