What happened
Our plugin declared bb.branding.icon: "Database" in package.json and an icon: "Inbox" hint on a nav panel registration. Both rendered as the generic fallback icon. Nothing errored, nothing warned, and nothing in the SDK indicated the names were wrong.
The cause is that neither name exists in the host's icon set. Database and Inbox appear zero times in the renderer bundle's icon registry, while GitBranch, Settings and Mail are present. Changing to valid names fixed it immediately.
The gap
The SDK types document the fallback behaviour accurately:
Icon hint (BB icon name); unknown names fall back to a generic icon.
But they do not say which names are valid, and the installed @bb/plugin-sdk package contains no list, enum, or union type for them — the field is plainly icon: string.
So a plugin author has three options: guess from a plausible-sounding vocabulary, read the host's compiled application bundle, or ship an icon and see what happens. We ended up doing the second, searching bb-app/app/dist/assets/*.js for the registry, which is not a reasonable thing to require and will break whenever that bundle is reorganised.
Why the silence makes it worse
A wrong icon name is indistinguishable from a plugin that never set one. The observable symptom — a generic icon — is identical in both cases, so the natural debugging move is to add another declaration rather than to suspect the value. We nearly did exactly that: the plugin already had two icon declarations, and "add a distinct icon" would have added a third and reported success while the operator still saw the generic one.
What would fix it
Any one of these, in rough order of usefulness:
- A union type or exported const in
@bb/plugin-sdk — icon: BbIconName — so an invalid name is a compile error rather than a silent runtime fallback.
- An exported list of valid names that plugin authors can read at build time.
- Documentation listing the set, with a note on how it is versioned.
- A dev-mode warning when a name misses the registry, so the failure is at least observable.
Option 1 is the one that would have prevented this entirely, and it costs plugin authors nothing at runtime.
Not urgent
This is cosmetic — a wrong icon, not broken behaviour. We are filing it because the silent-fallback-plus-undiscoverable-vocabulary combination is a trap that will catch other plugin authors the same way, and because the fix is small on your side and impossible on ours.
What happened
Our plugin declared
bb.branding.icon: "Database"inpackage.jsonand anicon: "Inbox"hint on a nav panel registration. Both rendered as the generic fallback icon. Nothing errored, nothing warned, and nothing in the SDK indicated the names were wrong.The cause is that neither name exists in the host's icon set.
DatabaseandInboxappear zero times in the renderer bundle's icon registry, whileGitBranch,SettingsandMailare present. Changing to valid names fixed it immediately.The gap
The SDK types document the fallback behaviour accurately:
But they do not say which names are valid, and the installed
@bb/plugin-sdkpackage contains no list, enum, or union type for them — the field is plainlyicon: string.So a plugin author has three options: guess from a plausible-sounding vocabulary, read the host's compiled application bundle, or ship an icon and see what happens. We ended up doing the second, searching
bb-app/app/dist/assets/*.jsfor the registry, which is not a reasonable thing to require and will break whenever that bundle is reorganised.Why the silence makes it worse
A wrong icon name is indistinguishable from a plugin that never set one. The observable symptom — a generic icon — is identical in both cases, so the natural debugging move is to add another declaration rather than to suspect the value. We nearly did exactly that: the plugin already had two icon declarations, and "add a distinct icon" would have added a third and reported success while the operator still saw the generic one.
What would fix it
Any one of these, in rough order of usefulness:
@bb/plugin-sdk—icon: BbIconName— so an invalid name is a compile error rather than a silent runtime fallback.Option 1 is the one that would have prevented this entirely, and it costs plugin authors nothing at runtime.
Not urgent
This is cosmetic — a wrong icon, not broken behaviour. We are filing it because the silent-fallback-plus-undiscoverable-vocabulary combination is a trap that will catch other plugin authors the same way, and because the fix is small on your side and impossible on ours.