Export Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Export Configuration system defines the parameters for processing FOSSBilling branding SVG masters into optimized web assets. It controls the generation of optimized SVGs, PNG icons, logos, favicons, and an asset manifest by specifying source paths, target dimensions, and visual variants.
The system uses export.config.json as the primary configuration file to drive the scripts/generate-assets.ts execution. This process ensures that branding assets remain consistent across different background treatments (light and dark) and provides a structured manifest for downstream consumption.
Sources: export.config.json, scripts/generate-assets.ts:1-20, README.md:65-75
Configuration Structure
The configuration resides in a JSON file, typically named export.config.json. It maps source SVG files to specific variants and defines the output scales for rasterized assets.
Key Configuration Properties
| Property | Type | Description |
|---|---|---|
assetsOutput | string | Directory for optimized SVG assets (e.g., assets/). |
output | string | Directory for generated PNGs, favicons, and the manifest (e.g., dist/). |
iconSizes | number[] | Array of pixel sizes for square icon PNG exports. |
logoWidths | number[] | Array of pixel widths for logo PNG exports. |
variants | object | Mapping of variant names to their respective icon and logo source paths. |
Sources: export.config.json:2-22, scripts/generate-assets.ts:65-85
Variant Definition
Each entry in the variants object represents a specific branding treatment. A variant must include paths to an icon and a logo SVG file. The generator validates that these names use only lowercase alphanumeric characters and hyphens.
"variants": {
"light-background": {
"icon": "source/light-background/fossbilling-icon.svg",
"logo": "source/light-background/fossbilling-logo.svg"
}
}
Sources: export.config.json:13-21, scripts/generate-assets.ts:89-91
Data Flow and Processing Logic
The generation script parses the configuration and executes a pipeline to validate, optimize, and export assets.
Asset Generation Pipeline
The following diagram illustrates how the configuration drives the asset processing flow:
The generator reads the variants from the config, ensures source SVGs do not contain "live text" (requiring outlined paths), and uses the iconSizes and logoWidths to trigger multi-resolution rasterization.
Sources: scripts/generate-assets.ts:87-130, scripts/svgo.config.ts:6-21
Validation Rules
The system enforces strict validation on configuration values and source files to prevent broken exports:
- Size Constraints:
iconSizesandlogoWidthsmust be integers between 1 and 4096. - SVG Requirements: Source SVGs must have a valid
viewBox. They must not contain<text>elements; lettering must be converted to paths. - Path Safety: The script prevents overwriting source files and detects dangling symlinks.
- Optimisation Integrity: SVGO optimization must not change the original dimensions (width/height) of the SVG.
Sources: scripts/generate-assets.ts:28-33, scripts/generate-assets.ts:40-45, scripts/generate-assets.ts:95-105, test/generate-assets.test.ts:98-105
Output Management
The configuration defines two distinct output paths: assetsOutput and output.
Manifest Schema
Every execution generates a manifest.json in the output directory. This file catalogs all generated files with their metadata, allowing external systems to discover available branding assets.
The Asset type includes fields for path, variant (e.g., "light-background"), type (icon, logo, favicon, etc.), and dimensions for raster formats.
Sources: scripts/types.ts:7-22, scripts/generate-assets.ts:162-165
Cleanup Behavior
The generator tracks all files it creates. If a variant or a size is removed from export.config.json, the script identifies and deletes the corresponding files in the output directories during the next run. It specifically targets files matching the project's naming patterns to avoid deleting unrelated user files.
Sources: scripts/generate-assets.ts:175-195, test/generate-assets.test.ts:71-85
Summary
Export Configuration provides a centralized, schema-validated method for managing FOSSBilling brand assets. By separating editable masters from optimized distribution files, it allows developers to regenerate a full suite of icons and logos simply by updating export.config.json and running the generation script. This ensures that all published assets adhere to the defined sizes and optimization standards required for high-performance web use.