Updating Version Numbers in React Native Android Apps: From AndroidManifest.xml to build.gradle

The Importance of Version Management and Common Misconceptions

In React Native Android application development, version number management is fundamental to app publishing and updates. Version numbers not only identify versions in app stores but also directly impact user update experiences. However, many developers new to React Native fall into a common trap: directly modifying version information in the AndroidManifest.xml file.

Root Cause of AndroidManifest.xml Auto-Revert Issues

As described by developers, when attempting to modify the android:versionCode and android:versionName attributes in AndroidManifest.xml, these changes are automatically reverted upon rebuilding the application. This phenomenon stems from the design of React Native's build system.

In standard Android projects, AndroidManifest.xml is indeed the primary location for version information. However, in React Native projects, the Gradle build system employs a different configuration strategy. During the build process, Gradle reads version configurations from the build.gradle file and dynamically generates the final AndroidManifest.xml file. This means direct modifications to the generated AndroidManifest.xml are ineffective, as each build regenerates this file based on configurations in build.gradle.

Correct Version Number Configuration Method

According to best practices, React Native Android app version numbers should be configured in the android/app/build.gradle file. Here's the specific configuration method:

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 21
        targetSdkVersion 33
        versionCode 2
        versionName "1.1"
        
        // Other configuration items
        ndk {
            abiFilters "armeabi-v7a", "x86", "arm64-v8a", "x86_64"
        }
    }
    
    // Other build configurations
}

In this configuration, two key attributes need to be understood:

• versionCode: This is an integer value used for internal version comparison in app stores. This value must increment with each new release. For example, increasing from 1 to 2, then to 3. This value is not displayed directly to users but determines how app stores identify which version is newer.
• versionName: This is a string value in a user-friendly format (such as semantic versioning). This value is displayed to users, typically following the "major.minor.patch" format, such as "1.1.0" or "2.0.0".

Best Practices for Version Number Configuration

To ensure accuracy and consistency in version management, follow these principles:

1. versionCode must increase monotonically: Each new version released to app stores must have a versionCode greater than all previous versions. This is a hard requirement of the Android system.
2. Semantic Versioning: For versionName, semantic versioning (SemVer) is recommended. This format is "MAJOR.MINOR.PATCH", where:
   • MAJOR version: Incremented when making incompatible API changes
   • MINOR version: Incremented when adding functionality in a backward-compatible manner
   • PATCH version: Incremented when making backward-compatible bug fixes
3. Separate development and production environments: During development, specific version naming conventions can distinguish app versions across different environments.

Advanced Techniques for Automated Version Management

For larger projects requiring more sophisticated version management, consider implementing automated version control. A common approach synchronizes version information with other parts of the project, such as package.json and Git commit history.

Here's an example of automated version configuration that retrieves versionName from package.json and generates versionCode from Git commit history:

import groovy.json.JsonSlurper

def getNpmVersion() {
    def inputFile = new File("../package.json")
    def packageJson = new JsonSlurper().parseText(inputFile.text)
    return packageJson["version"]
}

def getGitVersion() {
    def process = "git rev-list HEAD --first-parent --count".execute()
    return process.text.trim().toInteger()
}

def userVer = getNpmVersion()
def googleVer = getGitVersion()

android {
    defaultConfig {
        versionCode googleVer
        versionName userVer
        
        // Other configurations
    }
}

The advantages of this approach include:

• Version consistency: Ensures the React Native JavaScript version (version in package.json) aligns with the Android native version
• Automatic incrementation: versionCode automatically increments based on Git commit count, avoiding errors from manual updates
• Traceability: Each version number correlates with specific code states, facilitating issue tracking and version management

Building and Verification

After configuration, verify that version numbers are correctly applied through these steps:

1. Execute cd android && ./gradlew clean to clear previous build caches
2. Execute ./gradlew assembleRelease to build the release version
3. Use APK analysis tools or inspect the generated APK file's version information through code

Display current version information in the app for debugging and verification using this code:

import { Platform, NativeModules } from 'react-native';

const getAppVersion = () => {
  if (Platform.OS === 'android') {
    // For Android, version information can be obtained through native modules
    // or using third-party libraries like react-native-device-info
    return NativeModules.AppInfo?.versionName || 'Unknown';
  }
  return 'Not Android';
};

// Usage in the app
console.log('App version:', getAppVersion());

Common Issues and Solutions

During version number management, you may encounter these common issues:

1. Version number not updating: Ensure you're modifying android/app/build.gradle not android/build.gradle, and perform a complete clean and rebuild
2. Version conflicts: When multiple build variants exist, ensure each has correct version configurations
3. App store rejection: Ensure the new version's versionCode is strictly greater than all previously published versions

Conclusion

React Native Android app version number management requires following specific configuration patterns. Unlike traditional Android development, React Native apps should manage version information through the android/app/build.gradle file rather than directly modifying AndroidManifest.xml. Proper version number configuration includes not only basic versionCode and versionName settings but can also implement synchronization with other project parts through automation scripts. Mastering these technical details helps developers manage app versions more efficiently, ensuring smooth release processes.