or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-favicons-webpack-plugin

Let webpack generate all your favicons and icons for you

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/favicons-webpack-plugin@6.0.x

To install, run

npx @tessl/cli install tessl/npm-favicons-webpack-plugin@6.0.0

Favicons Webpack Plugin

Favicons Webpack Plugin is a webpack plugin that automatically generates comprehensive favicon and icon collections for web applications. It creates 44 different icon formats suitable for iOS devices, Android devices, Windows Phone, and various desktop browsers from a single source logo image (PNG or SVG), along with webapp manifest files and appropriate meta tags.

Package Information

Package Name: favicons-webpack-plugin
Package Type: npm
Language: JavaScript
Installation: npm install --save-dev favicons favicons-webpack-plugin

Core Imports

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

For ES modules:

import FaviconsWebpackPlugin from 'favicons-webpack-plugin';

Basic Usage

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

// Zero-config usage (looks for logo.png in webpack context)
module.exports = {
  plugins: [
    new FaviconsWebpackPlugin()
  ]
};

// Basic usage with logo path
module.exports = {
  plugins: [
    new FaviconsWebpackPlugin('/path/to/logo.png') // SVG works too!
  ]
};

// Advanced usage with configuration options
module.exports = {
  plugins: [
    new FaviconsWebpackPlugin({
      logo: './src/logo.png',
      cache: true,
      inject: true,
      favicons: {
        appName: 'My App',
        appDescription: 'My awesome application',
        developerName: 'Developer Name',
        background: '#fff',
        theme_color: '#333'
      }
    })
  ]
};

Architecture

The plugin integrates with webpack's compilation process through several key components:

Main Plugin Class: FaviconsWebpackPlugin provides the webpack plugin interface
Caching System: Built-in caching for performance optimization using webpack's cache or filesystem cache
Generation Modes: Light mode (development) for fast builds vs webapp mode (production) for comprehensive favicon generation
HTML Integration: Automatic HTML injection when used with html-webpack-plugin
Asset Management: Handles webpack asset generation and public path resolution

Capabilities

Plugin Constructor

Creates a new instance of the favicons webpack plugin.

/**
 * Creates a new favicons webpack plugin instance
 * @param {FaviconWebpackPlugionOptions | string} [args] - Configuration options or logo path (optional for zero-config)
 * @returns {FaviconsWebpackPlugin} New plugin instance
 */
constructor(args?: FaviconWebpackPlugionOptions | string): FaviconsWebpackPlugin;

Usage Examples:

// String parameter (logo path only)
new FaviconsWebpackPlugin('/path/to/logo.png');

// Configuration object
new FaviconsWebpackPlugin({
  logo: './src/logo.svg',
  cache: true,
  inject: true,
  favicons: {
    appName: 'My App',
    background: '#ffffff'
  }
});

// Zero-config (looks for logo.png in webpack context)
new FaviconsWebpackPlugin();

Webpack Plugin Interface

Standard webpack plugin apply method that hooks into the webpack compilation process.

/**
 * Webpack plugin apply method
 * @param {import('webpack').Compiler} compiler - Webpack compiler instance
 */
apply(compiler: import('webpack').Compiler): void;

Configuration Options

Complete configuration interface for customizing favicon generation behavior.

interface FaviconWebpackPlugionOptions {
  /** Source logo path(s) - can be PNG or SVG (optional for zero-config, automatically looks for logo.png in webpack context) */
  logo?: string | string[];
  
  /** Maskable source logo path(s) - can be PNG or SVG (optional) */
  logoMaskable?: string | string[];
  
  /** 
   * Enable caching (default: true)
   * Note: disabling caching may increase build times considerably
   */
  cache?: boolean;
  
  /**
   * Inject HTML links/metadata (default: true)
   * Requires html-webpack-plugin for injection
   * - boolean: true/false to enable/disable injection
   * - function: predicate that takes html-webpack-plugin instance and returns boolean
   */
  inject?: boolean | ((htmlWebpackPlugin: any) => boolean);
  
  /** Favicons library configuration options */
  favicons?: Partial<import('favicons').FaviconOptions>;
  
  /**
   * Favicon generation mode (default: 'auto')
   * - 'light': Fast compilation, limited features (single favicon)
   * - 'webapp': Full generation, wide browser support (44 formats)
   * - 'auto': Light for development, webapp for production
   */
  mode?: 'light' | 'webapp' | 'auto';
  
  /**
   * Development mode override
   * - 'light': Fast compilation for development
   * - 'webapp': Full generation even in development
   */
  devMode?: 'light' | 'webapp';
  
  /**
   * Web app manifest configuration
   * Can be a file path to base manifest or manifest object
   */
  manifest?: string | { [key: string]: any };
  
  /** Prefix path for generated assets (default: 'assets/') */
  prefix?: string;
  
  /** 
   * Output directory relative to webpack output dir
   * If not set, prefix is used
   */
  outputPath?: string;
  
  /** Override webpack's publicPath for favicon assets */
  publicPath?: string;
}

Favicons Library Options

Complete configuration options for the underlying favicons library (v7.0.1+):

interface FaviconOptions {
  /** Application name (defaults to package.json name) */
  appName?: string;
  
  /** Application description (defaults to package.json description) */
  appDescription?: string;
  
  /** Application short name for mobile devices */
  appShortName?: string;
  
  /** Application version (defaults to package.json version) */
  version?: string;
  
  /** Developer name (defaults to package.json author.name) */
  developerName?: string;
  
  /** Developer URL (defaults to package.json author.url) */
  developerURL?: string;
  
  /** Language code for the application */
  lang?: string;
  
  /** Background color for icons and splash screens */
  background?: string;
  
  /** Theme color for browser UI */
  theme_color?: string;
  
  /** Apple mobile web app status bar style */
  appleStatusBarStyle?: 'default' | 'black' | 'black-translucent';
  
  /** Display mode for PWA */
  display?: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
  
  /** Orientation constraint for PWA */
  orientation?: 'portrait' | 'landscape' | 'any' | 'natural' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';
  
  /** Scope of the PWA */
  scope?: string;
  
  /** Start URL for the PWA */
  start_url?: string;
  
  /** Preferred related applications */
  preferRelatedApplications?: boolean;
  
  /** Related applications list */
  relatedApplications?: Array<{
    platform: string;
    url?: string;
    id?: string;
  }>;
  
  /** Path prefix for generated assets (not needed when using webpack plugin) */
  path?: string;
  
  /** Logging configuration */
  logging?: boolean;
  
  /** Pixel art scaling method */
  pixel_art?: boolean;
  
  /** Load manifest from file */
  loadManifestWithCredentials?: boolean;
  
  /** Icon generation options - control which icon types to generate */
  icons?: {
    /** Android homescreen icon */
    android?: boolean | AndroidIconOptions;
    /** Apple touch icon */
    appleIcon?: boolean | AppleIconOptions;
    /** Apple startup images */
    appleStartup?: boolean | AppleStartupOptions;
    /** Opera Coast icon */
    coast?: boolean | CoastIconOptions;
    /** Standard favicons */
    favicons?: boolean | FaviconsOptions;
    /** Firefox OS icons */
    firefox?: boolean | FirefoxIconOptions;
    /** Windows tile icons */
    windows?: boolean | WindowsIconOptions;
    /** Yandex browser icon */
    yandex?: boolean | YandexIconOptions;
  };
}

interface AndroidIconOptions {
  /** Generate Android adaptive icons */
  adaptive?: boolean;
  /** Offset for adaptive icons */
  offset?: number;
  /** Background color for adaptive icons */
  background?: boolean | string;
  /** Mask for adaptive icons */
  mask?: boolean;
  /** Shadow for icons */
  shadow?: boolean;
}

interface AppleIconOptions {
  /** Generate different sized icons */
  sizes?: number[];
  /** Offset for icons */
  offset?: number;
  /** Background color */
  background?: boolean | string;
}

interface AppleStartupOptions {
  /** Generate startup images */
  background?: boolean | string;
  /** Offset for startup images */
  offset?: number;
}

interface CoastIconOptions {
  /** Offset for Coast icon */
  offset?: number;
  /** Background color */
  background?: boolean | string;
}

interface FaviconsOptions {
  /** Standard favicon sizes to generate */
  sizes?: number[];
}

interface FirefoxIconOptions {
  /** Firefox manifest background */
  background?: boolean | string;
  /** Offset for Firefox icons */
  offset?: number;
}

interface WindowsIconOptions {
  /** Background color for Windows tiles */
  background?: boolean | string;
  /** Offset for Windows tiles */
  offset?: number;
}

interface YandexIconOptions {
  /** Background color for Yandex icon */
  background?: boolean | string;
  /** Offset for Yandex icon */
  offset?: number;
}

Usage Patterns

Zero Configuration

The simplest setup - place a logo.png file in your webpack context directory:

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

module.exports = {
  plugins: [
    new FaviconsWebpackPlugin() // Automatically finds logo.png
  ]
};

Development vs Production

Different modes for optimal development experience:

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

module.exports = {
  plugins: [
    new FaviconsWebpackPlugin({
      logo: './src/logo.png',
      mode: 'auto', // Light mode in dev, webapp mode in prod
      // Or explicitly set development mode:
      devMode: 'light' // Fast builds during development
    })
  ]
};

PWA Configuration

Complete Progressive Web App setup with manifest:

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

module.exports = {
  plugins: [
    new FaviconsWebpackPlugin({
      logo: './src/logo.png',
      favicons: {
        appName: 'My PWA App',
        appDescription: 'A Progressive Web Application',
        developerName: 'My Company',
        developerURL: 'https://mycompany.com',
        background: '#ffffff',
        theme_color: '#000000',
        display: 'standalone',
        orientation: 'portrait'
      },
      manifest: './src/manifest.webmanifest' // Base manifest file
    })
  ]
};

Custom Output Paths

Control where favicon assets are generated:

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

module.exports = {
  plugins: [
    new FaviconsWebpackPlugin({
      logo: './src/logo.png',
      prefix: 'icons/', // Default asset prefix
      outputPath: '../public/icons', // Custom output directory
      publicPath: '/static/icons/' // Custom public path
    })
  ]
};

Conditional HTML Injection

Control when HTML meta tags are injected:

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

module.exports = {
  plugins: [
    new FaviconsWebpackPlugin({
      logo: './src/logo.png',
      inject: (htmlPlugin) => {
        // Only inject for specific HTML files
        return htmlPlugin.options.filename === 'index.html';
      }
    })
  ]
};

Multiple Logo Sources

Use multiple source images for comprehensive icon generation:

const FaviconsWebpackPlugin = require('favicons-webpack-plugin');

module.exports = {
  plugins: [
    new FaviconsWebpackPlugin({
      logo: [
        './src/logo.png',
        './src/logo.svg'
      ],
      logoMaskable: './src/logo-maskable.png' // For Android adaptive icons
    })
  ]
};

Generated Assets

The plugin generates various types of assets depending on the mode:

Light Mode Assets

favicon.png or favicon.svg (single favicon)
manifest.webmanifest (if manifest options provided)

Webapp Mode Assets

Apple Touch Icons: Various sizes from 57x57 to 1024x1024
Android Icons: Different densities and adaptive icons
Windows Tiles: Multiple sizes and formats
Standard Favicons: ICO, PNG formats in multiple sizes
Manifest Files: PWA manifest and browser-specific manifests
Startup Images: Apple touch startup images for different devices

HTML Integration

When used with html-webpack-plugin, the plugin automatically injects appropriate HTML meta tags:

<link rel="apple-touch-icon" sizes="180x180" href="/assets/apple-touch-icon-180x180.png">
<link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon-16x16.png">
<link rel="manifest" href="/assets/manifest.webmanifest">
<meta name="theme-color" content="#ffffff">
<!-- ... and many more -->

Error Handling

The plugin handles several error conditions:

Missing logo: Throws error if logo file cannot be found and no default logo.png exists
html-webpack-plugin compatibility: Shows detailed error for incompatible versions (requires v5+)
favicons peer dependency: Clear error message if favicons library is not installed
Invalid configuration: Type validation and helpful error messages for configuration issues

Performance Considerations

Caching: Enable caching (default: true) for significant build time improvements
Development mode: Use light mode during development for faster builds
Logo optimization: Use optimized source logos to reduce processing time
Selective generation: Configure favicons.icons to generate only needed formats