Documentation for adding icons to a backstage app

Feature Suggestion

I’d like some documentation on adding icons to a Backstage app! Happy to help with this 😃.

The current links documentation reads:

NOTE: The icon field value is meant to be a semantic key that will map to a specific icon that may be provided by an icon library (e.g. material-ui icons). These keys should be a sequence of [a-z0-9A-Z], possibly separated by one of [-_.]. Backstage may support some basic icons out of the box, but the Backstage integrator will ultimately be left to provide the appropriate icon component mappings. A generic fallback icon would be provided if a mapping cannot be resolved.

As far as I can tell, however, how to set this up is not documented:

This has been asked several times in the Backstage discord. (examples: 1, 2)

Possible Implementation

• Add documentation somewhere about the icons field in createApp
• Link to that documentation from the links note (or just place those docs inline)
• bonus 1 provide some docs on creating custom icons! rather than just mapping in material-ui
• bonus 2 provide an example or helper function to ingest all material ui icons into the icon mapping. currently i can’t figure out a better way to do it than manually mapping in every material-ui icon (as in, importing every single icon and then adding it to the object with a key being its name - maybe in lower, camel, or snake case.) given this library is included by default in a backstage app i think it makes sense to allow for easy inclusion of all of its icons

Context

One thing to note here is that in the example entity there is a link with the icon dashboard. Given “Backstage may support some basic icons out of the box, but the Backstage integrator…” it’s easy to assume that dashboard is a “basic icon out of the box”, even though it’s not included and falls back to the fallback icon.

[zhammer]

yep i think so!

[awanlin]

I’ve submitted PR #12696 to work towards filling this gap in the documentation