@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

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
Latest commit History 14 Commits
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

License

profullstack/favicon-generator

Folders and files

Latest commit

History

Repository files navigation

@profullstack/favicon-generator

Features

Installation

Global Installation (for CLI)

Usage

CLI Usage

Interactive Mode

Command Line Arguments

CLI Options

Programmatic Usage (ESM)

Basic Example

Custom Configuration

Custom Icon Sizes

Using Constants

API Reference

generateIcons(options)

generateCustomIcons(svgPath, outputDir, customSizes, additionalOptions)

Default Icon Sizes

Apple Touch Icons

PWA Icons

Favicon Sizes (optional)

Using Generated Icons in HTML

Basic HTML Head Setup

PWA Manifest File

Platform-Specific Notes

Development

Setup

Running Tests

Linting and Formatting

Requirements

Dependencies

License

Contributing

Issues

Changelog

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`generateIcons(options)`

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

Packages