Local Setup Guide

Relevant source files

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

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

The Local Setup Guide describes the requirements and procedures for managing FOSSBilling branding assets on a local development machine. This project provides tools to optimize SVG masters and generate various distribution formats including PNGs, favicons, and a preview sheet.

Sources: README.md:47-49, scripts/generate-assets.ts:10-12

Prerequisites

You must install Node.js version 24 or newer to run the automation scripts. The project uses TypeScript, but scripts execute directly in Node.js without a separate build step.

Sources: README.md:47-48, package.json:11-13

Installation Steps

1. Clone the repository to your local machine.
2. Open a terminal in the project root.
3. Install dependencies using the command: npm ci.

Sources: README.md:51-52, package.json:6-10

Asset Generation Flow

The asset generation system processes SVG masters from the source/ directory and outputs optimized files to assets/ and distribution files to dist/.

This diagram shows the transformation of source artwork into production-ready assets.
Sources: scripts/generate-assets.ts:133-162, README.md:54-61

Configuration

The export.config.json file controls the generation process. You define source paths, output directories, and specific dimensions for exported assets here.

Option	Type	Description
assetsOutput	string	Directory for optimized SVGs (e.g., "assets/")
output	string	Directory for PNGs, favicons, and manifest (e.g., "dist/")
iconSizes	number[]	Array of integer sizes (1-4096) for PNG icon exports
logoWidths	number[]	Array of integer widths for PNG logo exports
variants	object	Mapping of variant names to their SVG source files

Sources: export.config.json:1-21, scripts/generate-assets.ts:24-26, scripts/generate-assets.ts:77-83

Execution and Maintenance

Core Commands

Run the following commands via npm to manage the branding assets:

• npm run generate: Optimizes SVG masters and generates all distribution files.
• npm run typecheck: Validates script integrity using the TypeScript compiler.
• npm test: Runs the test suite to verify export accuracy and dimensions.

Sources: package.json:5-9, README.md:53-67

Script Logic

The generate-assets.ts script performs several safety checks before writing files:

1. Validation: Rejects SVGs containing "live text" (requires outlined paths).
2. Square Conversion: Automatically calculates a square viewBox for icon files to ensure correct rendering in favicons.
3. Cleanup: Removes obsolete files from the output directories if they are no longer defined in the configuration.
4. Safety: Prevents overwriting source files if output paths overlap with input paths.

Sources: scripts/generate-assets.ts:31-48, scripts/generate-assets.ts:101-104, scripts/generate-assets.ts:175-185

This sequence illustrates the interaction between the generation script and external libraries to produce assets.
Sources: scripts/generate-assets.ts:120-170, package.json:14-16

Environment Constraints

The project configuration is strictly typed to ensure consistency across the branding pipeline.

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "NodeNext",
    "strict": true,
    "allowImportingTsExtensions": true
  }
}

Sources: tsconfig.json:2-10

Summary: Local setup involves installing Node.js 24+, configuring paths in export.config.json, and using npm run generate to maintain the branding assets. The system ensures high-quality output by requiring outlined SVG text and performing automated cleanup of obsolete files.