Compatibility
Version matrix
This library’s published native code is built and tested against the versions below. Match them in your app for a reliable install.
| Package | Version | Notes |
|---|---|---|
react-native-alternate-app-icon | next release | Current source — uses Nitro 0.36.x (RN 0.87) |
react-native-alternate-app-icon | 1.0.0–1.1.0 | Uses Nitro 0.35.x |
react-native-alternate-app-icon | 0.8.0 | Legacy release — uses Nitro 0.32.x |
react-native-nitro-modules | 0.36.5 | Required for the current Nitro 0.36.x line |
react-native-nitro-modules | 0.35.9 | Required for 1.0.x |
react-native-nitro-modules | 0.32.0 | Required for 0.9.x |
| React Native | 0.76.0+ | New Architecture (Fabric / TurboModules) |
| React Native | 0.87+ | Requires Nitro 0.36.2+ (installJSIBindingsWithRuntime) |
| Node.js | 18.0.0+ | For CLI, Metro, and local tooling |
The example app in the repo uses React Native 0.84.1 with Nitro Modules 0.36.5.
Nitro toolchain
Native bindings under nitrogen/generated/ are produced with:
| Tool | Version |
|---|---|
| Nitrogen | 0.36.5 (current) / 0.35.9 (1.0.x) / 0.32.0 (v0.9.0) |
react-native-nitro-modules (codegen target) | 0.36.5 (current) / 0.35.9 (1.0.x) / 0.32.0 (v0.9.0) |
Nitrogen and Nitro Modules releases are paired.
- Current source (next release): Uses the 0.36.x line (RN 0.87 compatible).
- For v1.0.x / v1.1.0: Uses the 0.35.x line.
- For v0.9.x: Uses the 0.32.x line.
If you maintain a fork or run bun run codegen locally, ensure you match the version used by the library version you are on.
Architecture support
The library is built with Nitro Modules and supports React Native's New Architecture (Fabric and TurboModules).
Platform minimums
| Platform | Notes |
|---|---|
| iOS | iOS 10.3+ for alternate icons; test on a physical device — some recent simulators do not show the post-change alert reliably |
| Android | Standard launcher icon aliases via activity-alias |
Peer dependencies
Your app package.json should include:
{
"dependencies": {
"react-native-alternate-app-icon": "^1.1.0",
"react-native-nitro-modules": "0.36.5"
}
}
Use your package manager’s install command with an explicit Nitro version:
bun add react-native-alternate-app-icon react-native-nitro-modules@0.36.5
React Native 0.87 / Xcode 26
Nitro 0.36.2+ overloads installJSIBindingsWithRuntime for RN 0.87. The iOS pod matches the NitroSound workaround: library evolution defaults to off (NITRO_LIBLEVOLUTION=NO), Swift compiles as a whole module, and module-interface verification is skipped so Xcode 26 does not fail with 'BorrowingReference.hpp' file not found while verifying AlternateAppIcon.swiftinterface.
After upgrading, clean DerivedData, reinstall pods, and rebuild:
cd ios && pod install --repo-update
Upgrading Nitro later
When this library publishes support for a newer react-native-nitro-modules release, upgrade both packages together, reinstall pods, and rebuild native apps. Do not bump only Nitro Modules while staying on a release that was built for an older Nitro line.