Skip to content

kgluszczyk/iconer

BranchesTags

Repository files navigation

Iconer 🎨

A powerful Node.js CLI tool that leverages OpenRouter's API to generate PNG and SVG icons using AI models. Supports multiple models, configuration via JSON, and keeps intermediate representations.

Features

  • 🤖 Multi-Model Support: Choose from various text and image generation models
  • 🎨 Theme-Based Design: Generate icons based on themes like "modern", "retro", "minimal"
  • 📦 Batch Processing: Generate multiple icon classes at once
  • 🖼️ Dual Format Output: Generate both PNG and SVG formats
  • 🔄 PNG to SVG Conversion: Automatic conversion using Potrace for scalable vector graphics
  • 📏 Multiple Sizes: Generate icons in various sizes (16px to 512px)
  • ⚙️ JSON Configuration: Customize defaults via config.json
  • 💻 CLI Interface: Easy-to-use command line interface
  • ⚡ Fast & Efficient: Optimized for batch operations

Installation

# Clone the repository
git clone <repository-url>
cd iconer

# Install dependencies
npm install

# Make CLI globally available (optional)
npm link

Setup

  1. Get your OpenRouter API key from openrouter.ai
  2. Set up your API key:
# Using the setup command
npx iconer setup

# Or manually create .env file
cp .env.example .env
# Edit .env and add your API key

Configuration

Iconer uses a config.json file for default settings. You can:

  • View current config: iconer config
  • Edit config: iconer config --edit
  • Reset to defaults: iconer config --reset
  • List available models: iconer list-models

Configuration Structure

{
  "models": {
    "text": {
      "default": "openai/gpt-4o-mini",
      "options": [
        "openai/gpt-4o-mini",
        "openai/gpt-4o",
        "anthropic/claude-3.5-sonnet",
        "anthropic/claude-3-haiku",
        "google/gemini-pro",
        "meta-llama/llama-3.1-70b-instruct"
      ]
    },
    "image": {
      "default": "openai/dall-e-3",
      "options": [
        "openai/dall-e-3",
        "openai/dall-e-2",
        "midjourney/v6",
        "stability-ai/sdxl",
        "black-forest-labs/flux-1-schnell"
      ]
    }
  },
  "generation": {
    "theme": "modern",
    "size": 512,
    "outputDir": "./output",
    "keepPng": true,
    "generateSvg": true,
    "multiSize": false,
    "sizes": [16, 32, 64, 128, 256, 512]
  },
  "api": {
    "baseURL": "https://openrouter.ai/api/v1",
    "timeout": 30000,
    "maxRetries": 3
  },
  "prompts": {
    "temperature": 0.7,
    "maxTokens": 1000
  }
}

Usage

Generate Icons

# Basic usage with required classes
npx iconer generate -c "home,user,settings"

# With custom theme and size
npx iconer generate -c "home,user" -t retro -s 256

# Using specific models
npx iconer generate -c "home" --text-model "openai/gpt-4o" --image-model "openai/dall-e-3"

# Using OpenAI provider with custom model (creates timestamped output folder)
npx iconer generate -c "piano,guitar" -t icon-custom --image-model "gpt-image-1" --provider openai

# Keep PNG files alongside SVG
npx iconer generate -c "home" --keep-png

# Generate multiple sizes
npx iconer generate -c "download,upload" --multi-size

# Skip SVG generation
npx iconer generate -c "chart,graph" --no-svg

# Use custom config file
npx iconer generate -c "home" --config ./custom-config.json

# Generate with Android naming convention (ic_ prefix)
npx iconer generate -c "home,settings" --target android

# Use predefined icon classes from icon-classes.json
npx iconer icon-c ui-essentials -t modern

# Combine predefined class with Android naming
npx iconer icon-c communication --target android -t minimal

# Generate with context for cohesive icon sets
npx iconer generate -c "play,pause,stop,forward,rewind" --context-name "Media Controls" --context-desc "Media playback control icons"

Convert Existing PNGs

# Convert single file
npx iconer convert -i ./icon.png -o ./svg-output

# Convert directory of PNGs
npx iconer convert -i ./png-icons/ -o ./svg-icons/

Rename to Android Format

Rename existing icon files to Android naming convention (ic_<name>):

# Rename files in a directory to Android format
npx iconer rename-android ./output/2024-01-15

# Dry run to see what would be renamed
npx iconer rename-android ./output --dry-run

# Process subdirectories recursively
npx iconer rename-android ./output --recursive

# Create backups before renaming
npx iconer rename-android ./output --backup

This command will:

  • Convert filenames like home_modern_openai_2024.png to ic_home.png
  • Replace hyphens with underscores (e.g., user-profile becomes ic_user_profile)
  • Skip files already in Android format
  • Preserve file extensions (.png, .svg)

View Available Models

npx iconer list-models

Manage Configuration

# View current configuration
npx iconer config

# Edit configuration file
npx iconer config --edit

# Reset to default configuration
npx iconer config --reset

Command Options

generate command:

  • -c, --classes <classes>: Comma-separated icon classes (required)
  • -t, --theme <theme>: Icon theme (default from config)
  • -s, --size <size>: Target size in pixels (default from config)
  • -o, --output <dir>: Output directory (default from config)
  • --no-svg: Skip SVG generation
  • --no-png: Skip PNG generation
  • --keep-png: Keep intermediate PNG files
  • --multi-size: Generate multiple sizes
  • --text-model <model>: Override text model
  • --image-model <model>: Override image model
  • --config <path>: Path to config file
  • --api-key <key>: Override API key

convert command:

  • -i, --input <path>: Input PNG file or directory (required)
  • -o, --output <dir>: Output directory (default: ./output/svg)

list-models command:

Lists all available text and image models from configuration

config command:

  • -e, --edit: Open config file for editing
  • -r, --reset: Reset to default configuration

Examples

Theme Examples

  • "modern" - Clean, contemporary design
  • "retro" - Vintage, nostalgic style
  • "minimal" - Simple, clean lines
  • "corporate" - Professional business style
  • "playful" - Fun, colorful design

Icon Class Examples

  • Navigation: "home,back,forward,menu,close"
  • Actions: "download,upload,save,delete,edit"
  • Social: "like,share,comment,follow,message"
  • Media: "play,pause,stop,music,video"
  • UI Elements: "settings,search,filter,sort,refresh"

Predefined Icon Classes (icon-c command)

Use npx iconer icon-c <class> to generate complete icon sets with contextual awareness:

  • ui-essentials - Core UI icons (home, menu, search, settings, etc.)
  • file-operations - File management icons
  • media-controls - Media playback icons
  • communication - Messaging and calling icons
  • e-commerce - Shopping and payment icons
  • social-media - Social engagement icons
  • dev-programming - Development and coding icons
  • And many more! See icon-classes.json for full list.

Note: When using icon-c, the class name and description are automatically passed as context to ensure visual consistency across all icons in the set.

Context-Aware Generation

For cohesive icon sets, use context parameters:

  • --context-name "Set Name" - Name of the icon set
  • --context-desc "Description" - Description for consistent style

When context is provided:

  • Icons are generated with awareness of being part of a cohesive set
  • Visual consistency is emphasized across all icons
  • The AI considers related icons to maintain style coherence

Platform-Specific Naming

Use --target flag for platform conventions:

  • --target android - Clean Android naming with ic_ prefix and underscores
    • Folder: android_modern_openai_2024-...
    • Files: ic_home.png, ic_settings.svg, ic_user_profile.png
    • No theme/model/timestamp in filenames

Output Structure

output/
├── png/                          # PNG files (when keepPng is true)
│   ├── theme-class-512.png
│   └── ...
├── svg/                          # SVG files
│   ├── theme-class-512.svg
│   └── ...
└── sizes/                        # Multiple sizes (if --multi-size used)
    ├── theme-class-16.png
    ├── theme-class-32.png
    └── ...

Supported Models

Text Models (for prompts):

  • OpenAI GPT-4o Mini
  • OpenAI GPT-4o
  • Anthropic Claude 3.5 Sonnet
  • Anthropic Claude 3 Haiku
  • Google Gemini Pro
  • Meta Llama 3.1 70B Instruct

Image Models (for PNG generation):

  • OpenAI DALL-E 3
  • OpenAI DALL-E 2
  • Midjourney v6
  • Stability AI SDXL
  • Black Forest Labs FLUX-1-schnell

API Integration

The tool uses OpenRouter API which provides access to multiple AI models:

  • Text Models: For generating detailed icon descriptions
  • Image Models: For creating PNG images
  • Direct SVG Generation: Fallback when image generation is unavailable

Dependencies

  • axios - HTTP client for API requests
  • commander - CLI framework
  • sharp - Image processing
  • potrace - PNG to SVG conversion
  • chalk - Terminal styling
  • ora - Loading spinners
  • fs-extra - Enhanced file system operations
  • dotenv - Environment variable management
  • inquirer - Interactive prompts

Error Handling

The tool includes comprehensive error handling:

  • API key validation
  • Network error recovery
  • File system error handling
  • Invalid input validation
  • Model fallback mechanisms
  • Graceful failure with detailed error messages

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages