@dabenga/pwa-icon-generator

🎨 Generate PWA icons (standard, maskable, monochrome) from source files with automated CLI

A powerful CLI tool to generate all necessary PWA icons from your source files. Supports standard icons, maskable icons for adaptive themes (Android/iOS), and monochrome icons for custom themes (Material You, iOS).

✨ Features

• 🎯 Generate 24 icons from 2 source files
• 📱 Maskable icons for adaptive Android/iOS themes
• 🎨 Monochrome icons for custom themes (Material You)
• 🍎 Apple Touch Icon (180×180)
• 🌐 Favicon generation
• ✅ Verification of PWA configuration
• 🚀 Project initialization with templates
• 🎭 Framework support (Next.js, React, Vue, Vanilla)

📦 Installation

Global Installation (Recommended)

npm install -g @dabenga/pwa-icon-generator

Local Installation

npm install --save-dev @dabenga/pwa-icon-generator

🚀 Quick Start

1. Initialize your project

pwa-icons init

This will:

• Create necessary directories (public/, public/icons/)
• Add scripts to your package.json
• Create manifest template
• Create README

2. Add your source files

Place these files in public/:

• maskable.png (1024×1024 recommended)
• monochrome.png (1024×1024 recommended, black & white only)
• favicon.png (optional, 32×32 or larger)

3. Generate icons

pwa-icons generate

This generates:

• 8 standard icons (72, 96, 128, 144, 152, 192, 384, 512)
• 8 maskable icons
• 8 monochrome icons
• 1 Apple Touch Icon (180×180)
• 1 Apple Touch Icon (180×180)
• 2 Favicons (32×32 .ico and .png)

4. Verify configuration

pwa-icons verify

5. View preview

pwa-icons preview
# Then open public/icons/preview.html in your browser

📖 Usage

Commands

pwa-icons init

Initialize PWA icons setup in your project.

Options:

• -f, --framework <framework> - Framework (nextjs, react, vue, vanilla) [default: "nextjs"]

Example:

pwa-icons init --framework nextjs

pwa-icons generate

Generate all PWA icons from source files.

Options:

• -s, --source <dir> - Source directory [default: "public"]
• -o, --output <dir> - Output directory [default: "public/icons"]
• --maskable <file> - Path to maskable source [default: "public/maskable.png"]
• --monochrome <file> - Path to monochrome source [default: "public/monochrome.png"]
• --favicon <file> - Path to favicon source [default: "public/favicon.png"]
• --sizes <sizes> - Comma-separated sizes [default: "72,96,128,144,152,192,384,512"]

Example:

pwa-icons generate --sizes 192,512

pwa-icons verify

Verify PWA icon configuration.

Options:

• -d, --dir <dir> - Project directory [default: "."]

Example:

pwa-icons verify

📁 Project Structure

After running pwa-icons init and pwa-icons generate:

your-project/
├── public/
│   ├── icons/
│   │   ├── icon-72x72.png
│   │   ├── icon-72x72-maskable.png
│   │   ├── icon-72x72-monochrome.png
│   │   ├── ... (24 icons total)
│   │   └── README.md
│   ├── maskable.png (your source)
│   ├── monochrome.png (your source)
│   ├── apple-touch-icon.png
│   ├── favicon.ico
│   └── favicon.png
└── src/app/manifest.ts (or public/manifest.json)

🎨 Icon Types

Standard Icons

Default icons used by most browsers and devices.

Sizes: 72, 96, 128, 144, 152, 192, 384, 512

Maskable Icons

Adaptive icons that allow Android and iOS to apply different shapes (circle, rounded square, etc.) based on the user's theme.

Purpose: maskable
Safe Zone: Keep important elements within 80% of the diameter

Resources:

• Maskable.app Editor - Test your maskable icons

Monochrome Icons

Icons for custom themes on Android 13+ (Material You) and iOS. The system applies its own color.

Purpose: monochrome
Requirements: Black and white only

📱 Framework Integration

Next.js

The tool automatically creates src/app/manifest.ts:

import type { MetadataRoute } from "next";

export default function manifest(): MetadataRoute.Manifest {
    return {
        name: "Your App",
        icons: [
            {
                src: "/icons/icon-192x192-maskable.png",
                sizes: "192x192",
                type: "image/png",
                purpose: "maskable",
            },
            // ... more icons
        ],
    };
}

React / Vue / Vanilla

Creates public/manifest.json:

{
  "name": "Your App",
  "icons": [
    {
      "src": "/icons/icon-192x192-maskable.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

🔧 NPM Scripts

After initialization, these scripts are added to your package.json:

{
  "scripts": {
    "generate:icons": "pwa-icons generate",
    "generate:icons": "pwa-icons generate",
    "verify:icons": "pwa-icons verify",
    "preview:icons": "pwa-icons preview"
  }
}

📐 Source File Requirements

maskable.png

• Size: 1024×1024 pixels minimum
• Format: PNG with transparency
• Safe Zone: Keep important elements within 80% diameter circle
• Content: Full logo with all details

monochrome.png

• Size: 1024×1024 pixels minimum
• Format: PNG with transparency
• Colors: Black and white only (or grayscale)
• Content: Simple, recognizable silhouette

favicon.png (Optional)

• Size: 32×32 pixels or larger
• Format: PNG with transparency
• Content: Small, clear icon for browser tabs

✅ Testing

Visual Test

After generation, test your icons visually in the browser.

Device Testing

iOS (Safari):

1. Open Safari on iPhone/iPad
2. Tap Share → "Add to Home Screen"
3. Check icon appearance

Android (Chrome):

1. Open Chrome on Android
2. Menu → "Install app"
3. Check icon on home screen
4. Test with different launchers

Desktop:

1. Install PWA via browser
2. Check icon in taskbar/dock

Tools

• Maskable.app Editor - Test maskable icons
• PWA Builder - Validate manifest
• Lighthouse (Chrome DevTools) - PWA audit

🤝 Contributing

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

📄 License

MIT © DaBenga

🔗 Links

• GitHub Repository
• NPM Package
• Report Issues

💡 Tips

1. Safe Zone for Maskable Icons: Use Maskable.app Editor to ensure your logo fits within the safe zone.

2. Monochrome Design: Keep it simple! Complex designs don't work well as monochrome icons.

3. Regular Updates: Regenerate icons whenever you update your brand/logo:

   npm run generate:icons

4. Verification: Always verify after generation:

   npm run verify:icons

📊 What Gets Generated

| Type | Count | Purpose | |------|-------|---------| | Standard Icons | 8 | Default browser/device icons | | Maskable Icons | 8 | Adaptive Android/iOS themes | | Monochrome Icons | 8 | Custom themes (Material You) | | Apple Touch Icon | 1 | iOS home screen (180×180) | | Favicon | 2 | Browser tab (32×32 .ico and .png) | | Total | 27 | Complete PWA icon set |

Made with ❤️ by DaBenga