Configurator crashes and Icon Wizard icons fail to render when using a kit desktop export

[chadwjames]

Description

When using Font Awesome's Icon Wizard (a Pro feature that lets you combine a core icon with a modifier) and adding those icons to a kit, the desktop kit export includes them in metadata/icons.json with "styles": ["custom"]. There are two bugs that prevent these icons from working:

1. The configurator crashes before generating any files
2. Even after working around the crash, the generated IconDataCustom class doesn't exist in the package, causing compile errors
3. The kit's custom OTF font is not registered in pubspec.yaml, so icons would not render even if the above were fixed

All three issues must be resolved for Icon Wizard icons to work end-to-end.

---

Bug 1: Configurator crashes with null cast

Steps to Reproduce

1. Create icons using the Font Awesome Icon Wizard and add them to a kit
2. Export the kit using the Font Awesome desktop app
3. Copy metadata/icons.json to lib/fonts/icons.json
4. Run ./configurator.sh

Error

Custom icons.json found, generating files
Unhandled exception:
type 'Null' is not a subtype of type 'List<dynamic>' in type cast
#0      readAndPickMetadata (file:///.../util/lib/main.dart:617:35)
#1      main (file:///.../util/lib/main.dart:138:25)

Root Cause

util/lib/main.dart line 617 casts icon['changes'] directly to List, but Icon Wizard icons have no Font Awesome release history so the field is absent:

"solid-bell-circle-plus": {
  "label": "solid-bell-circle-plus",
  "styles": ["custom"],
  "svg": { ... },
  "unicode": "e001",
  "voted": false
}

Fix

// util/lib/main.dart:617
for (var v in (icon['changes'] as List? ?? [])) {
  versions.add(v);
}

Workaround

Manually add "changes": [] to each Icon Wizard icon entry in icons.json before running the configurator.

---

Bug 2: IconDataCustom class is missing

After working around Bug 1, the configurator correctly generates constants using IconDataCustom(0xeXXX) for custom-style icons, but this class does not exist in lib/src/icon_data.dart, causing 12 compile errors:

error • The method 'IconDataCustom' isn't defined for the type 'FontAwesomeIcons'
error • Const variables must be initialized with a constant value

Fix

Add IconDataCustom to lib/src/icon_data.dart pointing to the kit font family:

class IconDataCustom extends IconData {
  const IconDataCustom(super.codePoint)
    : super(
        fontFamily: 'FontAwesomeKit',
        fontPackage: 'font_awesome_flutter',
      );
}

---

Bug 3: Kit custom font not registered in pubspec.yaml

The desktop export includes a kit-specific OTF file (e.g. Font Awesome Kit {kitId}-Regular-400.otf) which contains the Icon Wizard icon glyphs. This file must be copied to lib/fonts/ and registered in pubspec.yaml, otherwise icons render as blank boxes.

Fix

Copy the kit OTF to lib/fonts/ and add to pubspec.yaml:

flutter:
  fonts:
    - family: FontAwesomeKit
      fonts:
        - asset: lib/fonts/Font-Awesome-Kit-{kitId}-Regular-400.otf
          weight: 400

The FontAwesomeKit family name must match what is used in IconDataCustom above.

---

Verification

After all three fixes, Icon Wizard icons are accessible both via direct reference and the name mapping:

// Direct
FaIcon(FontAwesomeIcons.solidBellCirclePlus)

// By name (requires --dynamic flag during configurator run)
FaIcon(faIconNameMapping['custom solid-bell-circle-plus']!)

Both approaches confirmed working with the manual fixes applied.

Notes

• The README makes no mention of Icon Wizard icons or kit custom icons — documentation for this workflow would be valuable for Pro users
• Icon Wizard icons use Font Awesome's fak prefix and the naming format [style]-[core-icon]-[modifier]
• The name mapping key format for custom icons is 'custom {icon-name}'

Environment

• font_awesome_flutter: 10.12.0
• Font Awesome Pro 6.7.2 desktop kit export
• macOS