@roku-sdk/compat
v2.19.1
Published
Shims that stand in for SceneGraph nodes older Roku OS firmware lacks
Keywords
Readme
@roku-sdk/compat
Shims for SceneGraph nodes that the SDK renders but firmware does not report as supported.
The package is a side-effect import. rk build and rk dev inject it ahead of the app entry, so
apps do not import it themselves. Set app.compat: false in roku-config.ts to leave it out.
What it does
Each shim registers a tag alias with registerTagAlias from @roku-sdk/solid. When the tag is
created, the alias asks hasFeature("tween") from @roku-sdk/runtime/has-feature whether the firmware
has the real node. If it does, the real node is created. If not, the shim is created instead.
| Tag | Native node | Firmware feature | Shim |
| --------- | ----------- | -------------------------- | -------------- |
| <tween> | Tween | roku.hasFeature("tween") | RsgTweenShim |
hasFeature returns false when roku or roku.hasFeature is absent, including Jest.
The firmware feature set starts empty;
until firmware adds "tween", devices use the shim regardless of their OS version.
When app.compat: false, the Roku build injects only the native-or-refusal registration, not
the shim XML or BrightScript. Importing @roku-sdk/rsg-ts alone performs no registration; only
the Roku build injects these entries.
In a Roku build without shims, creating a gated tag when its feature is not reported throws an error naming the missing firmware feature and this package. That is deliberate: a SceneGraph node type the firmware does not have fails silently and leaves an empty screen.
Retiring a shim
Removing a shim drops support for every firmware that does not report its native feature, so it is a breaking change:
- Remove shims only in a major SDK release, and state which firmware features that release requires.
- Batch removals into one release rather than shipping one breaking release per shim.
- Remove the shim's directory here and its entry in
refuse-gated-tags.tsonce all supported firmware reports the feature.@roku-sdk/soliddoes not change.
An app that must keep running on older firmware can stay on the last @roku-sdk/compat release
that has the shim it needs.
