Build System Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• export.config.json
• scripts/generate-assets.ts
• scripts/create-preview.ts
• scripts/svgo.config.ts
• scripts/types.ts
• test/generate-assets.test.ts

The FOSSBilling Branding build system automates the optimization of SVG master files and the generation of various asset formats, including PNGs, favicons, and preview sheets. It transforms source artwork into production-ready assets used across the FOSSBilling ecosystem.

The system relies on Node.js and TypeScript, utilizing the sharp library for image processing and svgo for vector optimization. It supports multiple branding variants, such as light and dark backgrounds, and outputs a comprehensive manifest of all generated files.
Sources: README.md:52-57, scripts/generate-assets.ts:1-10

Core Build Process

The primary build logic resides in scripts/generate-assets.ts. This script validates source files, optimizes vectors, renders raster images at multiple scales, and manages the output directories.

Asset Generation Workflow

The workflow follows a strict order of operations to ensure data integrity and prevent the overwriting of source files.

Validation and Optimization

Before any files are written, the script performs the following checks:

• Outlined Text: It rejects SVGs containing <text> elements to ensure consistent rendering without installed fonts.
• Dimensions: It verifies that optimization does not change the original SVG dimensions.
• Path Safety: It prevents output paths from overlapping with source file paths.

Optimization uses a specific svgo configuration that removes metadata, comments, and editor data while preserving coordinates and viewBox integrity.
Sources: scripts/generate-assets.ts:98-112, scripts/svgo.config.ts:5-20

Build Configuration

The system is controlled by export.config.json, which defines the input sources and the desired output specifications.

Key	Type	Description
assetsOutput	string	Directory for optimized SVG assets.
output	string	Directory for PNGs, favicons, and manifest.
iconSizes	number[]	Array of pixel widths for icon PNG exports.
logoWidths	number[]	Array of pixel widths for logo PNG exports.
variants	object	Mapping of variant names to source file paths.

Sources: export.config.json:1-21, scripts/generate-assets.ts:80-95

Asset Types and Metadata

The build system tracks every generated file through an internal Asset interface. This metadata is exported to manifest.json.

Output Categories

• Optimized SVGs: Found in the assets/ directory; these serve as vector masters for web use.
• Raster PNGs: Generated for both logos and icons at widths specified in the configuration.
• Favicons: Includes favicon.svg, a multi-resolution favicon.ico (16px, 32px, 48px), and an apple-touch-icon.png.
• Preview: A composite sheet (preview.png) showing all variants on various background colors.
  Sources: scripts/generate-assets.ts:145-163, README.md:14-25

Preview Generation

The scripts/create-preview.ts module generates a 1200px wide reference sheet. It uses the Manrope variable font to label different branding treatments and background contrasts.

Execution and Quality Control

The project provides several npm scripts to manage the lifecycle of the assets.

Command	Action
npm run generate	Executes the full build pipeline.
npm test	Runs the test suite to verify export accuracy and cleanup.
npm run typecheck	Validates TypeScript code for internal scripts.

Sources: package.json:5-9, README.md:52-57

Cleanup Mechanism

To maintain a clean distribution, the build script identifies "obsolete" files. If a size or variant is removed from export.config.json, the script deletes the corresponding files from the output directories during the next run. It specifically avoids traversing symlinked directories to prevent accidental deletion of external files.
Sources: scripts/generate-assets.ts:182-205, test/generate-assets.test.ts:96-103

Summary

The FOSSBilling Branding build system provides a robust, configuration-driven pipeline for asset production. By enforcing vector optimization standards and automating multi-format exports, it ensures that all brand assets remain consistent, high-quality, and easy to distribute via the generated manifest and preview sheet.