ProGuard and R8

Release builds that enable code shrinking (R8 or ProGuard) need extra care for Nitro modules. react-native-alternate-app-icon ships consumer keep rules in its AAR so you usually do not add library-specific rules in your app.

Enable shrinking in your app

In android/app/build.gradle, turn on minification for release and use the optimize defaults:

def enableProguardInReleaseBuilds = true

android {
    buildTypes {
        release {
            minifyEnabled enableProguardInReleaseBuilds
            shrinkResources enableProguardInReleaseBuilds
            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
        }
    }
}

Use proguard-android-optimize.txt

Prefer proguard-android-optimize.txt over the older proguard-android.txt. The optimize file includes standard keeps for Android components and enables R8 optimizations.

What the library provides

The module’s android/consumer-rules.pro is merged automatically when your app depends on this package (it is included in the published files list). It keeps:

• com.alternateappicon.** — Kotlin implementation (HybridAlternateAppIcon, package entry)
• com.margelo.nitro.alternateappicon.** — Nitrogen-generated Nitro specs and loaders
• Subclasses of com.margelo.nitro.core.HybridObject — required because hybrids are created from C++ via JNI

You do not need to copy those rules into android/app/proguard-rules.pro unless you fork or patch the library.

Activity aliases

Your activity-alias entries live in AndroidManifest.xml, not as Java classes. AAPT2 and R8 already keep manifest-declared components (activities, services, aliases).

Avoid redundant keeps

Do not add broad rules such as -keep public class * extends android.app.Activity. They are unnecessary for alternate icons and can block useful optimizations. See Android’s guidance on redundant R8 rules.

App-specific rules

Add rules to android/app/proguard-rules.pro only for your code (other SDKs, reflection, serialization). This library does not require extra keeps for MainActivity or alias names beyond correct Android setup.

Troubleshooting release builds

Symptom	Likely cause
setIcon / getActiveIcon work in debug but fail in release	Nitro hybrid stripped — this package ships android/consumer-rules.pro; upgrade and clean rebuild
Crash mentioning HybridAlternateAppIcon or AlternateAppIconOnLoad	Same as above; confirm minifyEnabled true still merges consumer rules from all dependencies
Icon names wrong only in release	Usually a naming mismatch in manifest, not ProGuard — alias suffix must match setIcon() argument
getAllAlternativeIcons() returns fewer icons than expected	Missing or misnamed activity-alias entries, not R8 removing aliases

Rebuild after native changes

Metro reload is not enough. After changing ProGuard settings or updating this library, run a full release build (./gradlew assembleRelease or your CI equivalent).

Debugging R8

To inspect the merged configuration for a release build:

# android/gradle.properties (temporary)
android.enableR8.fullMode=true

Or add to proguard-rules.pro:

-printconfiguration build/outputs/mapping/release/configuration.txt

Compare the effective rules with consumer-rules.pro in this repo.