@profullstack/favicon-generator

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

Features

🎨 Convert SVG or PNG source art to multiple PNG icon sizes
🖼️ PNG sources for when you only have raster logo art
📱 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:

Source file path (.svg or .png)
Output directory
PNG quality (1-100)
Compression level (0-9)
Whether to generate additional favicon sizes

Command Line Arguments

# Basic usage with an SVG source
fav -i favicon.svg -o ./icons

# Basic usage with a PNG source
fav -i logo.png -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 source `.svg` or `.png`	`./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({
  inputPath: './favicon.svg', // or './logo.png'
  outputDir: './icons',
});

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

PNG Source Example

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

const results = await generateIcons({
  inputPath: './logo.png',
  outputDir: './public/icons',
});

// 'png' for a raster source, 'svg' for a vector one
console.log(results.inputFormat); // 'png'

// A PNG source has no vector equivalent, so no favicon.svg is written
console.log(results.rootFavicons); // { png: ..., ico: ... }

Custom Configuration

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

const results = await generateIcons({
  inputPath: './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({
  inputPath: './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 or PNG source file.

Parameters:

options (Object):
- inputPath (string, required): Path to the source .svg or .png file
- svgPath (string, optional): Deprecated alias for inputPath, still accepted (and it may point at a .png)
- 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',
  inputPath: './favicon.svg',
  inputFormat: 'svg', // 'svg' or 'png'
  rootFavicons: {
    png: './icons/favicon.png',
    svg: './icons/favicon.svg', // omitted for a PNG source
    ico: './icons/favicon.ico'
  }
}

Source Format Notes

	SVG source	PNG source
Scaling	Rasterized losslessly at every size	Resampled; upscaling softens the image
`favicon.svg`	Written (copy of the source)	Not written — no vector equivalent
Primary `<link rel="icon">`	`/favicon.svg` (`image/svg+xml`)	`/favicon.png` (`image/png`)
Recommended input	Any square viewBox	Square, at least 512x512

A PNG source smaller than the largest requested icon, or one that isn't square, logs a warning: icons are still generated (upscaled and padded to fit), but the result will be softer than vector art. Supply the highest resolution you have.

`isSupportedInputFile(filePath)` / `getInputFormat(filePath)`

Helpers for validating a source path before calling generateIcons.

import { isSupportedInputFile, getInputFormat } from '@profullstack/favicon-generator';

isSupportedInputFile('logo.png'); // true
isSupportedInputFile('logo.jpg'); // false
getInputFormat('logo.png'); // 'png'
getInputFormat('logo.svg'); // 'svg'
getInputFormat('logo.jpg'); // null

`generateCustomIcons(inputPath, outputDir, customSizes, additionalOptions)`

Generate icons with custom sizes.

Parameters:

inputPath (string): Path to the source .svg or .png 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 an SVG favicon with PNG fallbacks; with a PNG source, favicon.png plus the sized PNGs cover every browser

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

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.

Name		Name	Last commit message	Last commit date
.github		.github
.socket		.socket
bin		bin
examples		examples
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation