BadgeForge

Modern badge generator powered by shields.io with AI-assisted design

Create beautiful shields.io badges with live customization, extensive icon library, and optional AI-powered design generation.

Features

Feature	Description
Live Customization	Modify labels, messages, and colors with instant visual feedback
Icon Library	Search and browse 3000+ icons from Simple Icons
Style Selection	Choose from multiple badge styles including flat, plastic, and more
Color Picker	Intuitive color selection with hex input support
Easy Export	Copy generated badge URLs or Markdown snippets instantly
AI Generation	Describe your badge concept and generate multiple variations
Design Persistence	Save and manage your favorite badge configurations

Quick Start

Local Development

1. Clone the repository

git clone https://github.com/48hour-solutions/badge-forge.git

cd badge-forge

2. Install dependencies

npm install

3. Set up environment (optional - for AI features)

echo "GEMINI_API_KEY=your_api_key_here" > .env

4. Start development server

npm run dev

Application available at http://localhost:9002

Docker Deployment

1. Build and run with Docker Compose

docker-compose up -d

2. Set your Gemini API key (optional)

export GEMINI_API_KEY="your_api_key_here"

docker-compose up -d

Application available at http://localhost:3102

Docker Configuration

Customize deployment by modifying docker-compose.yml:

Setting	Configuration	Description
Port Mapping	"3102:3000"	Change left port for different host binding
Environment	GEMINI_API_KEY	API key for AI features
Volume	./data:/app/data	Persists saved badge configurations

AI Integration (Optional)

BadgeForge includes optional AI-powered badge generation using Google Gemini.

Setup

1. Obtain an API key from Google AI Studio

2. Configure your environment:

Option 1: Environment file

echo "GEMINI_API_KEY=your_api_key_here" > .env

Option 2: Docker environment variable

export GEMINI_API_KEY="your_api_key_here"

Usage

Navigate to the AI generation tab in the application

Describe your desired badge in natural language

Receive multiple design variations tailored to your specifications

Select and customize your favorite generated design

Technology Stack

Component	Technology
Framework	Next.js 15.3.3
UI Library	React 18.3.1
Language	TypeScript 5
Styling	Tailwind CSS 3.4.1
Components	Radix UI
AI	Google Gemini (Genkit 1.13.0)
Icons	Simple Icons 13.1.0
Deployment	Docker

Development

Command	Description
npm run dev	Run development server with Turbopack
npm run build	Build for production
npm start	Start production server
npm run typecheck	Type checking
npm run lint	Linting

Showcase

Acknowledgments

Built with shields.io for badge generation and Simple Icons for icon assets.