How aglasencnik/typedicons works
1. This repository is a .NET solution split into three product-facing subsystems: a command-line tool, a shared core library, and a Roslyn source generator. The overall purpose is to turn Iconify icon selections into strongly typed Blazor-friendly icon references at compile time.
2. src/TypedIcons.Cli is the operational entry point. It exposes commands for project setup and icon lifecycle management: init, add, remove, list, restore, and clean. This is the user-facing boundary that edits project configuration and manages the local icon cache.
3. The CLI is organized around services rather than direct file manipulation. ConfigService handles typedicons.json, IconService and IconifyService handle icon resolution/cache-related work, and InitializationService wires up the initial project state. The command classes in Commands/ are thin wrappers over those services.
4. src/TypedIcons.Core is the shared model layer used by both the CLI and the generator. It contains the configuration and cache abstractions (IconConfig, IconCache, IconReference) plus small utility extensions. This is the main contract boundary for “what icons are selected” and “what cached icon data exists.”
5. The repository’s key data flow starts with typedicons.json in the project root. That file is the source of truth for which icons are enabled in a consumer project. The CLI creates and updates it, and the source generator reads it during build.
6. A second data store exists in the project’s obj folder: the local icon cache. The README and file layout indicate this cache is generated from typedicons.json, is not committed to source control, and is restored from Iconify when needed. This cache decouples build-time generation from network access.
7. src/TypedIcons.Generator is the compile-time generation boundary. Its IconGenerator reads the config and cache and emits strongly typed C# code from CodeTemplates.cs. The generated output provides the Icons.<Set>.<Name> API used by consuming Blazor components.
8. The generator is distributed as a NuGet package and is installed into consumer projects, either manually or via typedicons init. The build-time integration is important architecturally: icon definitions are materialized during compilation, not at runtime, which is why the README emphasizes no dynamic loading and no runtime dependency on Iconify.
9. The sample project under samples/TypedIcons.Sandbox demonstrates the consumption side. It is a Blazor app with an Icon component usage path and test icon wrappers (TestIcon, TestIconBase, TestIconSet, etc.) that illustrate how generated icon types are surfaced in UI code. The sample also includes its own typedicons.json, showing the expected project-local configuration shape.
10. tests/TypedIcons.Tests focuses on generator behavior, especially around additional text inputs and test fixture data for typedicons.json and cache files. That indicates the most critical correctness surface is the transformation from config/cache inputs into generated source.
11. The CI and release workflows in .github/workflows likely validate the package/tooling pipeline rather than app deployment. In this repo, build quality matters across three outputs: the CLI executable/tool, the generator package, and the shared core library.
12. For an architecture diagram, the important boundaries are: consumer project, typedicons.json config, local cache in obj, CLI command layer, shared core models, generator at build time, and the resulting generated icon classes consumed by Blazor UI. The external dependency that materially affects the flow is Iconify, which is only needed to populate or restore the cache.
Main entry points: IconGenerator.cs Icon generator · Commands Commands · IconService.cs Icon service · IconConfig.cs IconConfig
Components 19
CLI
Command-line entrypoint and project maintenance flow
- CLI entry · Operates commands for init, add, remove, list, restore, and clean
src/TypedIcons.Cli/Program.cs - Commands · Thin command wrappers around application services
src/TypedIcons.Cli/Commands - Config service · Reads and writes typedicons.json
src/TypedIcons.Cli/Services/ConfigService.cs - Icon service · Coordinates icon selection and local cache operations
src/TypedIcons.Cli/Services/IconService.cs - Iconify service · Handles fetching or restoring icon data from Iconify
src/TypedIcons.Cli/Services/IconifyService.cs - Init service · Bootstraps a consumer project for TypedIcons
src/TypedIcons.Cli/Services/InitializationService.cs
Core
Shared icon/config contracts
- IconConfig · Selected icon set configuration
src/TypedIcons.Core/Models/IconConfig.cs - IconCache · Cached icon data used during build and restore
src/TypedIcons.Core/Models/IconCache.cs - IconReference · Reference to a specific icon selection
src/TypedIcons.Core/Models/IconReference.cs
Generator
Compile-time code generation
- Icon generator · Reads config and cache to emit typed icon APIs
src/TypedIcons.Generator/IconGenerator.cs - Templates · String templates for generated C# output
src/TypedIcons.Generator/CodeTemplates.cs
Sample app
Blazor consumption example
- Sandbox app · Sample consumer showing generated icon usage
samples/TypedIcons.Sandbox/Program.cs - Sample config · Example typedicons.json for a consumer project
samples/TypedIcons.Sandbox/typedicons.json - Test icons · Sample icon wrapper types used to demonstrate consumption
samples/TypedIcons.Sandbox/Components/Components/TestIcons.cs
Tests
Generator-focused verification
- Generator tests · Checks generator behavior with config and cache inputs
tests/TypedIcons.Tests/IconGeneratorTests.cs - Test config · typedicons.json fixture used by tests
tests/TypedIcons.Tests/TestData/typedicons.json - Test cache · typedicons.cache.json fixture used by tests
tests/TypedIcons.Tests/TestData/typedicons.cache.json
CI/CD
Repository workflows
- Workflows · Build and release validation for CLI, generator, and core
.github/workflows/ci.yml
External
Third-party service
- Iconify · External icon source used to populate or restore cache
Connections 22
- CLI entry → Commands: routes · Starts the command surface
- Commands → Config service: uses · Commands read and update project configuration
- Commands → Icon service: uses · Commands manage icon selection and cache state
- Commands → Init service: uses · Init command bootstraps a project
- Icon service → Iconify service: restores from · Fetches or restores icon data when cache is missing
- Config service → IconConfig: persists · Maps typedicons.json into the shared config model
- Icon service → IconCache: reads/writes · Coordinates the local icon cache lifecycle
- Icon service → IconReference: tracks · Works with selected icon references
- Init service → IconConfig: creates · Initializes default project configuration
- Iconify service → Iconify: calls · External source for icon metadata and content
- Icon generator → IconConfig: reads · Consumes selected icon definitions at build time
- Icon generator → IconCache: reads · Uses cached icon data to avoid runtime fetching
- Icon generator → Templates: emits · Formats generated C# output from templates
- Icon generator → IconReference: expands · Turns references into strongly typed icon members
- Sandbox app → Test icons: uses · Blazor UI consumes generated icon wrappers
- Sandbox app → Sample config: shaped by · Sample project demonstrates the local configuration file
- Generator tests → Test config: loads · Uses typedicons.json fixture inputs
- Generator tests → Test cache: loads · Uses cache fixture inputs
- Generator tests → Icon generator: validates · Verifies generated output from config and cache data
- Workflows → CLI entry: builds · Validates the CLI package in CI
- Workflows → Icon generator: builds · Validates the generator package in CI
- Workflows → IconConfig: builds · Checks shared contracts as part of the solution