Complete Guide to Changing Package Name for Android in React Native

Necessity and Challenges of Package Name Modification

In React Native development, the application package name serves as a unique identifier on the Android platform, determining not only the app's publishing identity on Google Play Store but also affecting permissions for various system service calls. Projects initialized with the react-native init command typically generate basic package name structures like com.myapp, but in actual commercial deployments, developers often need to adjust them to more organizational formats such as com.mycompany.myapp.

Many developers initially attempt to modify only the package name declaration in the AndroidManifest.xml file, but this partial approach causes inconsistencies between the Gradle build system and Java source code paths, leading to compilation errors or runtime exceptions. Proper package name modification requires comprehensive adjustments from file system structure to code references.

File System Structure Adjustment

The Android application package name directly maps to the project directory structure. First, create the new package path in the file system:

// Original path
android/app/src/main/java/com/myapp/

// Target path  
android/app/src/main/java/com/mycompany/myapp/

After moving the original MainActivity.java and MainApplication.java files to the new directory, ensure file permissions and ownership remain unchanged. This step forms the foundation for all subsequent modifications—if the directory structure doesn't match, the class loader cannot locate the corresponding class files even with correct package declarations in the code.

Java Source Code Package Declaration Updates

After moving files, update the package declaration statements at the top of each Java source file. Taking MainActivity.java as an example:

package com.mycompany.myapp;

import android.os.Bundle;
import com.facebook.react.ReactActivity;

public class MainActivity extends ReactActivity {
    @Override
    protected String getMainComponentName() {
        return "MyApp";
    }
}

Similarly, the MainApplication.java file requires the same package name modification:

package com.mycompany.myapp;

import android.app.Application;
import com.facebook.react.ReactApplication;
// ... other import statements

These modifications ensure the Java Virtual Machine correctly resolves fully qualified class names at runtime, avoiding runtime errors like ClassNotFoundException.

Android Configuration File Updates

The package name declaration in the AndroidManifest.xml file must match the Java source code:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.mycompany.myapp">
    
    <application
        android:name=".MainApplication"
        android:label="@string/app_name"
        android:icon="@mipmap/ic_launcher">
        <activity
            android:name=".MainActivity"
            android:configChanges="keyboard|keyboardHidden|orientation|screenSize">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

The package name here not only defines the application's unique identifier but also determines the generation location of the resource file R class, affecting the entire application's resource reference system.

Gradle Build Configuration Adjustments

In the android/app/build.gradle file, the applicationId property must be updated synchronously:

android {
    compileSdkVersion rootProject.ext.compileSdkVersion
    
    defaultConfig {
        applicationId "com.mycompany.myapp"
        minSdkVersion rootProject.ext.minSdkVersion
        targetSdkVersion rootProject.ext.targetSdkVersion
        versionCode 1
        versionName "1.0"
    }
    // ... other configurations
}

The relationship between applicationId and package name requires special attention: in most cases they should be identical, but applicationId is primarily used by the build system to generate the final APK filename and internal identifier, while the Java package name is mainly for code organization. This separation design allows developers to use the same codebase with different application identifiers across various build variants.

Buck Build System Configuration (If Applicable)

If the project uses Facebook's Buck build system, also update relevant configurations in the android/app/BUCK file:

android_build_config(
    name = "build_config",
    package = "com.mycompany.myapp",
)

android_resource(
    name = "res",
    package = "com.mycompany.myapp",
    res = "src/main/res",
)

These configurations ensure the Buck build system correctly generates the BuildConfig class and resource index files, maintaining the integrity of the build process.

Build Cleanup and Verification

After completing all file modifications, execute Gradle cleanup to clear previous build caches:

cd android
./gradlew clean

After cleanup, rebuild the project:

cd ..
npx react-native run-android

This step is crucial because Gradle caches previous package name information and class path relationships. Without cleanup, various difficult-to-diagnose compilation errors or runtime issues may occur.

Common Issues and Solutions

During package name modification, developers often encounter the following problems:

Resource Not Found Errors: If R.java file generation errors or resource reference failures occur, check if the package name in AndroidManifest.xml completely matches the Java package declaration. The Android build system generates the R class based on the package name in the manifest file—any mismatch will cause the resource system to crash.

Class Not Found Exceptions: If the application throws ClassNotFoundException at runtime, confirm all Java files have been moved to the correct package path and package declarations at file tops have been updated. Pay special attention to checking if any hard-coded class references need updating.

Build Configuration Conflicts: Some third-party libraries may depend on specific package name structures. If dependency conflicts occur after modifying the package name, check the relevant library documentation to see if custom package names are supported or special configuration is required.

Best Practice Recommendations

To ensure a smooth package name modification process, follow these best practices:

Version Control Preparation: Commit the current working state to version control before starting modifications for quick rollback if problems arise.

Comprehensive Testing: After modifications, test not only basic functionality but also features related to package names, such as deep linking, notification handling, and interactions with other applications.

Documentation Updates: Update all package name references in project documentation, including CI/CD configurations, release scripts, and team development guidelines.

By systematically executing the above steps, developers can safely and efficiently complete package name modifications for React Native Android applications, laying a solid foundation for correct deployment and long-term maintenance.