@profullstack/favicon-generator

@profullstack/favicon-generator

Generate PNG icons from SVG for iOS and PWA compatibility. A modern, flexible Node.js tool that converts your SVG favicon into all the icon sizes you need for mobile devices and progressive web apps.

Features

• 🎨 Convert SVG to multiple PNG icon sizes
• 📱 iOS Apple Touch Icon support
• 🌐 PWA icon generation
• 🖼️ Automatic favicon size generation (16x16, 32x32)
• ⚙️ Configurable quality and compression
• 🎯 CLI with interactive mode
• 📦 ESM module for programmatic use
• ✅ Comprehensive test coverage
• 🚀 Built with modern Node.js (v20+)

Installation

# Using pnpm (recommended)
pnpm add @profullstack/favicon-generator

# Using npm
npm install @profullstack/favicon-generator

# Using yarn
yarn add @profullstack/favicon-generator

Global Installation (for CLI)

# Using pnpm
pnpm add -g @profullstack/favicon-generator

# Using npm
npm install -g @profullstack/favicon-generator

Usage

CLI Usage

Interactive Mode

Simply run the command without arguments to enter interactive mode:

fav

You'll be prompted for:

• SVG file path
• Output directory
• PNG quality (1-100)
• Compression level (0-9)
• Whether to generate additional favicon sizes

Command Line Arguments

# Basic usage
fav -i favicon.svg -o ./icons

# With custom quality and compression
fav -i logo.svg -o ./public/icons -q 90 -c 7

# Silent mode (no output)
fav -i favicon.svg -o ./icons --silent

# Skip favicon generation
fav -i favicon.svg -o ./icons --no-favicon

# Show help
fav --help

# Show version
fav --version

CLI Options

Option	Alias	Description	Default
--input	-i	Path to SVG file	./favicon.svg
--output	-o	Output directory	./icons
--quality	-q	PNG quality (1-100)	95
--compression	-c	Compression level (0-9)	9
--no-favicon		Skip additional favicon sizes	false
--silent		Suppress output messages	false
--help	-h	Show help message
--version	-v	Show version number

Programmatic Usage (ESM)

Basic Example

import { generateIcons } from '@profullstack/favicon-generator';

const results = await generateIcons({
  svgPath: './favicon.svg',
  outputDir: './icons',
});

console.log(`Generated ${results.icons.length} icons`);

Custom Configuration

import { generateIcons } from '@profullstack/favicon-generator';

const results = await generateIcons({
  svgPath: './logo.svg',
  outputDir: './public/icons',
  quality: 90,
  compressionLevel: 7,
  generateFavicon: true,
  faviconSizes: [16, 32, 48],
  verbose: true,
});

// Access generated files
results.icons.forEach((icon) => {
  console.log(`${icon.name}: ${icon.path}`);
});

Custom Icon Sizes

import { generateCustomIcons } from '@profullstack/favicon-generator';

const customSizes = [
  { size: 48, name: 'icon-48.png' },
  { size: 96, name: 'icon-96.png' },
  { size: 144, name: 'icon-144.png' },
];

const results = await generateCustomIcons('./favicon.svg', './icons', customSizes, { quality: 95 });

Using Constants

import { generateIcons, DEFAULT_ICON_SIZES, BACKGROUNDS } from '@profullstack/favicon-generator';

// Use default icon sizes
const results = await generateIcons({
  svgPath: './favicon.svg',
  outputDir: './icons',
  iconSizes: DEFAULT_ICON_SIZES,
});

// Available background colors
console.log(BACKGROUNDS.transparent); // { r: 255, g: 255, b: 255, alpha: 0 }
console.log(BACKGROUNDS.white); // { r: 255, g: 255, b: 255, alpha: 1 }
console.log(BACKGROUNDS.black); // { r: 0, g: 0, b: 0, alpha: 1 }

API Reference

generateIcons(options)

Generate PNG icons from an SVG file.

Parameters:

• options (Object):
  • svgPath (string, required): Path to the SVG file
  • outputDir (string, required): Output directory for generated icons
  • iconSizes (Array, optional): Array of {size, name} objects. Defaults to DEFAULT_ICON_SIZES
  • quality (number, optional): PNG quality (1-100). Default: 95
  • compressionLevel (number, optional): Compression level (0-9). Default: 9
  • generateFavicon (boolean, optional): Generate additional favicon sizes. Default: true
  • faviconSizes (Array, optional): Array of favicon sizes. Default: [16, 32]
  • verbose (boolean, optional): Enable verbose logging. Default: true

Returns: Promise

{
  icons: [
    { size: 64, name: 'icon-64.png', path: './icons/icon-64.png' },
    // ...
  ],
  faviconSizes: [
    { size: 16, path: './icons/favicon-16.png' },
    // ...
  ],
  outputDir: './icons'
}

generateCustomIcons(svgPath, outputDir, customSizes, additionalOptions)

Generate icons with custom sizes.

Parameters:

• svgPath (string): Path to the SVG file
• outputDir (string): Output directory
• customSizes (Array): Array of {size, name} objects
• additionalOptions (Object, optional): Additional options (quality, compressionLevel, etc.)

Returns: Promise (same as generateIcons)

Default Icon Sizes

The package generates the following icon sizes by default:

Apple Touch Icons

• 57x57, 60x60, 72x72, 76x76
• 114x114, 120x120, 144x144
• 152x152, 180x180

PWA Icons

• 192x192, 256x256, 384x384, 512x512

Favicon Sizes (optional)

• 16x16, 32x32

Using Generated Icons in HTML

After generating your icons, add them to your HTML <head> section. See the complete example in examples/html-head-template.html.

Basic HTML Head Setup

<head>
  <!-- Favicon -->
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  <link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32.png" />
  <link rel="icon" type="image/png" sizes="16x16" href="/icons/favicon-16.png" />

  <!-- Apple Touch Icons (iOS) -->
  <link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon-180x180.png" />
  <link rel="apple-touch-icon" sizes="152x152" href="/icons/apple-touch-icon-152x152.png" />
  <link rel="apple-touch-icon" sizes="144x144" href="/icons/apple-touch-icon-144x144.png" />
  <link rel="apple-touch-icon" sizes="120x120" href="/icons/apple-touch-icon-120x120.png" />
  <link rel="apple-touch-icon" sizes="114x114" href="/icons/apple-touch-icon-114x114.png" />
  <link rel="apple-touch-icon" sizes="76x76" href="/icons/apple-touch-icon-76x76.png" />
  <link rel="apple-touch-icon" sizes="72x72" href="/icons/apple-touch-icon-72x72.png" />
  <link rel="apple-touch-icon" sizes="60x60" href="/icons/apple-touch-icon-60x60.png" />
  <link rel="apple-touch-icon" sizes="57x57" href="/icons/apple-touch-icon-57x57.png" />

  <!-- Web App Manifest (PWA) -->
  <link rel="manifest" href="/manifest.json" />
  <meta name="theme-color" content="#ffffff" />

  <!-- iOS Web App -->
  <meta name="apple-mobile-web-app-capable" content="yes" />
  <meta name="apple-mobile-web-app-status-bar-style" content="default" />
  <meta name="apple-mobile-web-app-title" content="Your App" />
</head>

PWA Manifest File

Create a manifest.json file for Progressive Web App support. See examples/manifest.json for a complete example:

{
  "name": "Your App Name",
  "short_name": "App",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ],
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#ffffff"
}

Platform-Specific Notes

• iOS: Uses Apple Touch Icons (automatically adds rounded corners)
• Android/PWA: Uses icons from manifest.json
• Windows: Uses msapplication meta tags
• Modern Browsers: Prefer SVG favicon with PNG fallbacks

Development

Setup

# Clone the repository
git clone https://github.com/profullstack/favicon-generator.git
cd favicon-generator

# Install dependencies
pnpm install

Running Tests

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

Linting and Formatting

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Format code
pnpm format

# Check formatting
pnpm format:check

Requirements

• Node.js >= 20.0.0
• ESM support

Dependencies

• sharp - High-performance image processing
• inquirer - Interactive CLI prompts

License

MIT © profullstack

Contributing

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

Issues

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Changelog

See CHANGELOG.md for release history.