Favicon and Apple Touch Icon Generation
Relevant source files
The following files were used as context for generating this wiki page:
The Favicon and Apple Touch Icon generation system automates the creation of web-standard branding assets from SVG masters. It processes source artwork to produce optimized SVGs, multi-resolution ICO files, and specific PNG formats required for modern web browsers and mobile devices.
This system ensures visual consistency across different platforms by supporting multiple background variants (e.g., light and dark). It automates technical requirements such as square aspect ratio enforcement, SVG optimization, and downsampling from high-density vector renders to ensure crisp raster assets.
Sources: README.md:65-72, scripts/generate-assets.ts:1-10
Asset Generation Architecture
The generation process follows a linear pipeline that begins with configuration loading and ends with the distribution of assets and a metadata manifest. The system uses sharp for rasterization and svgo for vector optimization.
Generation Pipeline Flow
The following diagram illustrates the sequence of operations performed during asset generation.
Core Components and Logic
SVG Optimization and Transformation
The system enforces strict requirements for source SVGs. It rejects files containing live text, requiring all lettering to be converted to paths to ensure font-independent rendering.
- SVGO Optimization: Uses a conservative allowlist to remove editor metadata without altering coordinates or viewBox data.
- Square Viewport Adjustment: The
squareSvgfunction calculates a new square viewBox by taking the maximum of the original width or height and centering the existing artwork.
Sources: scripts/generate-assets.ts:32-47, scripts/svgo.config.ts:5-18
Rasterization and ICO Packaging
The system renders PNGs from vectors at a minimum of 2x target resolution before downsampling to ensure high quality.
- Density Calculation: The script calculates the required rendering density (DPI) based on the target width relative to the original SVG dimensions.
- ICO Structure: The
icofunction manually constructs the ICO binary format. It includes three specific frames (16px, 32px, and 48px) as independently rendered RGBA PNGs.
Configuration and Output
The generation behavior is controlled via export.config.json. This file defines the source paths, target variants, and specific sizes for icons and logos.
Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
assetsOutput | string | Directory for optimized SVG assets. |
output | string | Directory for generated PNG, ICO, and manifest files. |
iconSizes | number[] | Array of widths for standalone PNG icons. |
logoWidths | number[] | Array of widths for PNG logos. |
variants | object | Key-value map of variant names to source SVG paths. |
Sources: export.config.json:1-20, scripts/generate-assets.ts:85-102
Output Structure
The system generates a specific directory structure within the configured output folder:
[variant]/favicon/favicon.svg: Optimized square SVG for modern browsers.[variant]/favicon/favicon.ico: Legacy support file containing 16px, 32px, and 48px frames.[variant]/favicon/apple-touch-icon.png: A 180x180 PNG specifically for iOS/macOS.manifest.json: A catalog of all files, including their types, formats, and dimensions.
Sources: scripts/generate-assets.ts:149-160, test/generate-assets.test.ts:46-75
Asset Manifest
The manifest.json file serves as the single source of truth for the generated bundle. It includes a exportedAt timestamp in UTC format and an array of Asset objects.
export interface Asset {
path: string;
variant: string | null;
type: 'icon' | 'logo' | 'favicon' | 'apple-touch-icon' | 'preview';
format: string;
width?: number;
height?: number;
sizes?: number[]; // Used for ICO frames
}
Sources: scripts/types.ts:9-18, test/generate-assets.test.ts:48-52
Summary
The generation system transforms master branding SVGs into a comprehensive set of web assets. By validating source files for outlined text, enforcing square aspect ratios for icons, and automating multi-frame ICO creation, it removes the manual effort required to maintain web-standard favicons and touch icons. The process concludes with the generation of a manifest, providing a structured index for consuming applications.