TypeScript Types and Interfaces

Relevant source files

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

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

TypeScript types and interfaces in this project define the structural contract for FOSSBilling branding assets, configuration, and the resulting manifest. They ensure type safety across the asset generation pipeline, from initial SVG processing to the final distribution of PNGs, favicons, and metadata.

These definitions facilitate the transformation of source SVG files into multiple formats and sizes while maintaining consistency between the logic in scripts/generate-assets.ts and the validation in test/generate-assets.test.ts.

Core Data Structures

The project relies on three primary interfaces to manage the lifecycle of a branding asset.

Variant Interface

The Variant interface represents a specific visual theme (e.g., light-background or dark-background) and holds the raw SVG content during the optimization process.

The Variant interface stores the optimized SVG string data for the icon and logo, along with a "square" version used for favicon generation.
Sources: scripts/types.ts:1-6, scripts/generate-assets.ts:77-94

Asset Interface

The Asset interface describes an individual file exported by the system. It tracks metadata required for the web manifest and automated testing.

Field	Type	Description
path	string	Relative path to the file in the distribution bundle.
variant	string | null	The theme variant the asset belongs to, or null for global assets.
type	string	The category of asset (icon, logo, favicon, etc.).
format	string	File extension (e.g., svg, png, ico).
width	number	Optional width for raster images.
height	number	Optional height for raster images.
sizes	number[]	Optional array of sizes for multi-frame formats like ICO.
variants	string[]	Optional list of variants included in a preview asset.

Sources: scripts/types.ts:8-16, scripts/generate-assets.ts:121-127

AssetManifest Interface

The AssetManifest interface defines the structure of the manifest.json file, which serves as the inventory for all generated assets.

Configuration and Integration

The asset generation script uses these types to validate the input from export.config.json and external libraries like svgo and sharp.

Generation Logic Flow

The following diagram illustrates how the Variant and Asset types are utilized during the execution of the generation script.

SVGO Configuration

The svgo.config.ts file utilizes the Config type from the svgo library to enforce a strict allowlist of optimization plugins. This ensures that SVG coordinate rounding or path rewriting does not occur, preserving the integrity of the original artwork.
Sources: scripts/svgo.config.ts:1-20

Usage in Preview Generation

The createPreview function uses the Variant type to arrange assets onto a reference sheet. It calculates layout positions and renders labels using the Manrope font based on the variant names provided in the configuration.

• Background Mapping: The function maps variant names to specific hex colors (e.g., #171C24 for dark backgrounds).
• Layer Composition: It builds an array of OverlayOptions for the sharp library, where each layer corresponds to an asset described by the interfaces.
  Sources: scripts/create-preview.ts:13-35

Validation and Testing

The test suite in test/generate-assets.test.ts imports the AssetManifest type to verify that the generation script produces accurate output.

1. Dimension Verification: For PNG assets, the test compares the width and height properties in the manifest against the actual binary headers of the generated files.
2. Timestamp Validation: It ensures the exportedAt string follows the ISO UTC format.
3. Variant Integrity: It confirms that every asset in the manifest is correctly associated with a valid variant name defined in the config.
   Sources: test/generate-assets.test.ts:43-70

The use of shared TypeScript interfaces across the build scripts and test suite ensures that any change to the asset structure is caught during type checking or testing, maintaining the reliability of the branding distribution.