Troubleshooting Build Issues

Relevant source files

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

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

Troubleshooting build issues involves identifying and resolving failures in the asset generation pipeline. The project uses a TypeScript-based build system to optimize SVG masters and generate raster assets, favicons, and previews. This page details common failure points, validation requirements, and the recovery process for the branding asset workflow.

Sources: README.md:65-72, scripts/generate-assets.ts:1-25

Build Pipeline Overview

The build process executes through npm run generate, which triggers the scripts/generate-assets.ts script. This script validates configurations, optimizes source SVGs using SVGO, and renders raster images using the Sharp library.

The flow diagram illustrates the sequential stages of the asset generation process and where potential failures occur.
Sources: scripts/generate-assets.ts:114-205, package.json:4-8

Common Configuration Issues

Errors often stem from incorrect settings in export.config.json. The generator enforces strict types for output paths and asset sizes.

Configuration Requirements

Parameter	Requirement	Source
iconSizes	Array of integers between 1 and 4096	scripts/generate-assets.ts:27-32
logoWidths	Array of integers between 1 and 4096	scripts/generate-assets.ts:27-32
output	Non-empty string path	scripts/generate-assets.ts:98-99
assetsOutput	Non-empty string path (separate from source)	scripts/generate-assets.ts:101-103
variants	Object containing at least one valid variant	scripts/generate-assets.ts:105-107

Path Overlap Failures

The build script prevents overwriting source files or overlapping output paths. If a target file path matches a source path, the build aborts before writing any data.
Sources: scripts/generate-assets.ts:182-187, test/generate-assets.test.ts:101-110

SVG Master Validation

The generator requires "outlined" SVG masters. It specifically rejects files containing live text to ensure consistent rendering across environments where fonts might not be installed.

Verification Steps

1. Text Check: The script scans SVGs for <text> or <tspan> tags. If found, the build fails with: use outlined lettering, not live text.
2. ViewBox Check: Every root SVG must have a valid viewBox attribute.
3. Dimension Consistency: Optimization via svgo.config.ts must not change the original dimensions of the SVG.

The sequence diagram shows the internal validation logic applied to each SVG source file.
Sources: scripts/generate-assets.ts:117-128, scripts/svgo.config.ts:6-21

Environment and Dependency Errors

Builds require a specific Node.js environment and external binary dependencies handled by the sharp library.

• Node.js Version: Requires Node.js 24 or newer.
• Dependency Installation: Use npm ci to ensure a clean state of the node_modules directory, including the platform-specific binaries for sharp.
• Memory/Resolution: The script renders vectors at high density (at least 2x target resolution) before downsampling. Extremely large target sizes in export.config.json may cause memory issues during the sharp rendering phase.

Sources: package.json:11-13, README.md:65-72, scripts/generate-assets.ts:167-172

Manifest and Cleanup Failures

The build script maintains an assets/ directory (for optimized SVGs) and a dist/ directory (for generated artifacts).

Manifest Synchronization

The dist/manifest.json file records the exportedAt UTC timestamp and a complete list of all generated files. If a build is interrupted, the manifest may not reflect the actual files on disk. A successful rerun always regenerates the manifest.
Sources: scripts/types.ts:16-24, test/generate-assets.test.ts:40-50

Obsolete File Removal

The script automatically removes files that are no longer defined in the configuration (e.g., a variant was deleted or a size was removed). However, the cleanup process has strict limits:

• It only recognizes specific filename patterns (e.g., fossbilling-icon-*.png).
• It does not traverse or delete files in symlinked directories to prevent accidental data loss.

Sources: scripts/generate-assets.ts:189-204, test/generate-assets.test.ts:112-124

Summary

Build issues in the branding project typically arise from SVG master validation failures (live text), configuration errors (invalid sizes/paths), or environment mismatches (Node.js < 24). Validating that source SVGs have lettering converted to paths and that export.config.json uses unique, valid directories resolves most generation failures.

Sources: README.md:52-63, scripts/generate-assets.ts:212-215