Scripts: Asset Generation
Relevant source files
The following files were used as context for generating this wiki page:
Asset Generation transforms SVG source masters into optimized web assets, including vectors, PNG images, favicons, and a visual preview sheet. The system ensures branding consistency by enforcing specific dimensions and optimization rules across multiple background variants.
The generation process relies on Node.js and the sharp and svgo libraries to process imagery. Users initiate the process via npm run generate.
Sources: README.md:88-92, package.json:5-7
Core Workflow
The generation script follows a strict sequence: it validates configuration, optimizes vector masters, renders raster variants, generates special-purpose files like favicons, and cleans up obsolete assets.
Execution Logic
The pipeline operates in a "validate-then-write" mode to prevent partial or corrupted exports.
The diagram shows the sequential stages of the asset generation lifecycle, from configuration loading to file cleanup. Sources: scripts/generate-assets.ts:77-228
Configuration and Input
Asset generation depends on a JSON configuration file, typically export.config.json. This file defines the scope of the export process.
Configuration Properties
| Key | Type | Description |
|---|---|---|
assetsOutput | string | Directory for optimized SVG assets. |
output | string | Directory for PNGs, favicons, and the manifest. |
iconSizes | number[] | Square dimensions for PNG icon exports. |
logoWidths | number[] | Widths for PNG logo exports. |
variants | object | Map of background variants to source SVG paths. |
Sources: export.config.json:1-20, scripts/generate-assets.ts:86-103
Vector Processing
The system processes source SVGs through optimization and viewport adjustment.
Optimization Rules
The script uses svgo with a conservative configuration. It removes editor metadata, comments, and unused namespaces while preserving coordinates, transforms, and IDs to avoid visual regression.
Sources: scripts/svgo.config.ts:6-21
Viewport Squaring
For favicon generation, the squareSvg function modifies the SVG viewport. It calculates the largest dimension (width or height) and re-centers the artwork within a square viewport without distorting the internal paths.
Sources: scripts/generate-assets.ts:39-55
Rasterization and ICO Generation
The script uses sharp to render vectors into raster formats.
High-Density Rendering
To ensure sharpness during downsampling, the script renders SVGs at a minimum of 144 DPI or double the target resolution before resizing.
Sources: scripts/generate-assets.ts:162-167
ICO Format Construction
The script manually assembles .ico files by concatenating a 6-byte header, 16-byte directory entries for each frame, and raw PNG data for 16px, 32px, and 48px sizes.
Sources: scripts/generate-assets.ts:58-75, scripts/generate-assets.ts:182-184
Visual Preview Sheet
The createPreview function generates a composite image (preview.png) that displays branding assets on different background colors.
Layout Logic
- Backgrounds: The preview includes Light (#FFFFFF), Dark (#171C24), and Black (#000000) sections.
- Components: Each section displays a full logo, a 28px header logo, a 120px icon, and various favicon sizes.
- Typography: Labels are rendered using the Manrope font.
Sources: scripts/create-preview.ts:13-56
Manifest and Lifecycle
Every successful run generates a manifest.json file. This file acts as a registry for all exported assets.
Asset Manifest Structure
The manifest includes an exportedAt UTC timestamp and a list 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 multi-size ICO files
variants?: string[]; // Used for the preview sheet
}
Sources: scripts/types.ts:8-22
Cleanup and Safety
- Symlink Protection: The script uses
realpathandlstatto ensure it does not overwrite source masters or delete files outside of recognized naming patterns through symlinks. - Obsolete Removal: It identifies and removes files in the output directory that do not match the current configuration but follow the naming convention of previous exports.
Sources: scripts/generate-assets.ts:133-152, scripts/generate-assets.ts:200-221
Summary
The Asset Generation system provides a predictable, automated pipeline for branding distribution. By combining strict SVG optimization, high-density rasterization, and automated cleanup, it maintains a clean and accurate repository of production-ready assets.