iconwolf - Cross-platform app icon generator for Expo/React Native

A CLI tool that takes an Apple Icon Composer .icon folder (or a plain PNG) and generates all necessary icon variants for cross-platform use. Built for React Native and Expo projects, iconwolf produces Android adaptive icons, web favicons, splash screen icons, and standard app icons -- all from one source.

One icon to rule them all.

Features

• Apple Icon Composer Support - First-class support for .icon folders from Apple's Icon Composer. Renders gradient and solid backgrounds via SVG, composites foreground layers with scale and translation automatically.
• Android Adaptive Icons - Generates adaptive icon foreground by default. Use --android for background and monochrome variants (66/108 safe zone ratio).
• Web Favicon - Produces a 48x48 favicon with Apple-style rounded corners (~22.37% radius). Generated by default.
• Splash Screen Icon - Creates a 1024x1024 splash icon.
• Standard App Icon - Outputs a universal 1024x1024 icon.
• Expo Drop-in Ready - Auto-detects src/ projects and defaults to ./src/assets/images/ or ./assets/images/.
• Auto Background Color - When using .icon input, the background gradient color is automatically extracted for Android adaptive icons.
• Separate Splash Image - Use --splash-input to provide a different source image for the splash screen icon.
• Selective Generation - Use CLI flags to generate only the variants you need.
• Custom Background Color - Override the Android adaptive icon background color via --bg-color.
• Dev/Preview Banners - Add diagonal ribbon banners (DEV, BETA, STAGING, etc.) to distinguish app environments. Auto color-coded with customizable position.
• Update Notifier - Non-blocking version check against GitHub Releases with a 24-hour cached TTL. Zero latency impact on icon generation.

Getting Started

1. Design your icon in Apple Icon Composer (or use any square PNG).
2. Install iconwolf via Homebrew or npm (see below).
3. Run iconwolf AppIcon.icon in your project directory.
4. All icon variants land in ./assets/images/ by default.

Install via Homebrew

brew tap mrdemonwolf/den
brew install iconwolf

Install via npm

npm install -g @mrdemonwolf/iconwolf

Or use it directly with npx:

npx @mrdemonwolf/iconwolf <input-icon>

Usage

iconwolf <input> [options]

Arguments

Argument	Description
input	Path to an Apple Icon Composer .icon folder or PNG

Options

Flag	Description
-o, --output <dir>	Custom output directory (default: auto-detected)
--android	Generate all Android adaptive icons (adds background + monochrome)
--favicon	Generate web favicon only
--splash	Generate splash screen icon only
--icon	Generate standard icon.png only
--splash-input <path>	Use a separate image for the splash screen icon
--bg-color <hex>	Background color for Android adaptive icon (#FFFFFF)
--banner <text>	Diagonal ribbon banner (e.g. DEV, BETA, STAGING)
--banner-color <hex>	Ribbon color (default: auto from text)
--banner-position <pos>	top-left, top-right, bottom-left, bottom-right
-h, --help	Display help
-V, --version	Display version

Examples

# Generate all default variants from an .icon folder
iconwolf AppIcon.icon

# Generate all default variants from a plain PNG
iconwolf app-icon.png

# Generate all Android adaptive icons (foreground + background + monochrome)
iconwolf AppIcon.icon --android

# Use a separate image for the splash screen
iconwolf AppIcon.icon --splash-input splash-logo.png

# Generate only favicon
iconwolf AppIcon.icon --favicon

# Generate favicon and splash to a custom directory
iconwolf AppIcon.icon --favicon --splash --output ./assets/icons

# Generate only the standard icon
iconwolf AppIcon.icon --icon

# Override the Android adaptive icon background color
iconwolf AppIcon.icon --android --bg-color "#1A1A2E"

# Add a DEV ribbon banner to all icons (auto green color)
iconwolf AppIcon.icon --banner DEV

# Add a BETA banner with custom color in the top-right corner
iconwolf AppIcon.icon --banner BETA --banner-color "#FF5722" --banner-position top-right

Output Files

By default (no flags), iconwolf generates 4 files matching the expo-template-default layout exactly.

File	Dimensions	Purpose
icon.png	1024x1024	Universal app icon
adaptive-icon.png	1024x1024	Android adaptive icon foreground
splash-icon.png	1024x1024	Splash screen icon
favicon.png	48x48	Web favicon

With --android flag, also generates:

File	Dimensions	Purpose
android-icon-background.png	1024x1024	Android adaptive icon background
monochrome-icon.png	1024x1024	Android 13+ themed icon (grayscale)

MCP Server (AI Integration)

iconwolf includes an MCP server that lets AI assistants like Claude generate icons directly through conversation.

Quick Setup (Claude Code)

claude mcp add --scope user --transport stdio iconwolf -- npx @mrdemonwolf/iconwolf-mcp

Manual Setup

Add to your MCP client settings (Claude Code, Claude Desktop, etc.):

{
  "mcpServers": {
    "iconwolf": {
      "command": "npx",
      "args": ["@mrdemonwolf/iconwolf-mcp"]
    }
  }
}

Once configured, just ask your AI assistant things like:

• "Generate all app icon variants from ./AppIcon.icon"
• "Create a favicon from ./logo.png"
• "Generate Android adaptive icons with a blue background"

See the @mrdemonwolf/iconwolf-mcp package for full documentation.

Tech Stack

Layer	Technology
Runtime	Node.js
Language	TypeScript
Image Processing	Sharp
CLI Framework	Commander
Console Output	Chalk
Testing	Vitest
Linting	ESLint v9
Formatting	Prettier
Bundling	esbuild
Package Manager	pnpm

Development

Prerequisites

• Node.js v18 or higher
• pnpm

Setup

1. Clone the repository:

git clone https://github.com/MrDemonWolf/iconwolf.git
cd iconwolf

2. Install dependencies:

pnpm install

3. Build the project:

pnpm run build

Development Scripts

• pnpm run build - Compile TypeScript to dist/
• pnpm run build:release - Build release tarball to dist-bin/ (esbuild bundle + sharp native bindings)
• pnpm run dev - Watch mode compilation
• pnpm test - Run all tests with Vitest (87 tests across 11 files)
• pnpm run lint - ESLint across src/ and tests/
• pnpm run format - Format code with Prettier
• pnpm run format:check - Check formatting (used in CI)

Code Quality

• ESLint v9 flat config with TypeScript rules
• Prettier for consistent code formatting
• Vitest for unit, integration, and E2E tests
• Strict TypeScript (ES2022, NodeNext module resolution)
• CI runs lint + tests on Node 18/20/22 across Ubuntu and macOS

Project Structure

iconwolf/
├── packages/
│   ├── iconwolf/              # Core CLI package (@mrdemonwolf/iconwolf)
│   │   ├── src/
│   │   │   ├── index.ts       # CLI entry point (Commander)
│   │   │   ├── generator.ts   # Icon generation orchestrator
│   │   │   ├── lib.ts         # Public API exports
│   │   │   ├── types.ts       # Shared TypeScript interfaces
│   │   │   ├── utils/         # Image processing, paths, logging
│   │   │   └── variants/      # Icon variant generators
│   │   └── tests/             # Vitest test suite
│   └── iconwolf-mcp/          # MCP server (@mrdemonwolf/iconwolf-mcp)
│       ├── src/
│       │   ├── index.ts       # MCP server entry (stdio transport)
│       │   ├── tools/         # Tool handlers (5 tools)
│       │   └── utils/         # I/O helpers, Zod schemas
│       └── tests/             # MCP tool tests
├── Formula/
│   └── iconwolf.rb            # Homebrew formula
├── .github/workflows/         # CI: lint, test, build, publish
├── pnpm-workspace.yaml        # pnpm monorepo config
├── CLAUDE.md                  # AI assistant context
├── CHANGELOG.md               # Release changelog
└── LICENSE                    # MIT License

License

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

Contact

Have questions or feedback?

• Discord: Join my server

---

Made with love by MrDemonWolf, Inc.