In-depth Analysis and Solutions for Duplicate Resource Errors in React Native Android Builds

Problem Background and Error Analysis

In React Native development, developers frequently encounter Duplicate resources errors when attempting to build Android release APKs. The error typically manifests as:

[drawable-mdpi-v4/assets_mario] /path/to/res/drawable-mdpi/assets_mario.png
[drawable-mdpi-v4/assets_mario] /path/to/build/generated/res/react/release/drawable-mdpi-v4/assets_mario.png
Error: Duplicate resources
:app:mergeReleaseResources FAILED

The core issue lies in the duplication of resource files. During React Native's build process, when using the react-native bundle command to package resources, the system copies image resources from the project to the Android project's res directory. However, in subsequent Gradle build processes, the system discovers that these resources already exist in the build/generated/res/react/release directory, leading to resource conflicts.

Error Generation Mechanism

To understand the essence of this problem, it's essential to analyze React Native's build workflow. When executing the react-native bundle command:

1. React Native's bundler scans resource files in the project
2. Copies these resources to the specified target directory (typically android/app/src/main/res/)
3. Simultaneously, React Native's Gradle plugin generates identical resources to the build/generated/res/react/release directory during the build process
4. When Gradle attempts to merge these resources, it finds identical resource files in both directories, throwing a duplicate resource error

This duplication occurs due to design inconsistencies in React Native's build system. The problem is particularly prominent in newer React Native versions, as the resource handling approach has evolved in the build system.

Solution 1: Modifying the react.gradle File

This is the most fundamental solution, avoiding resource duplication by modifying React Native's build script. Edit the node_modules/react-native/react.gradle file and add resource movement logic in the doLast block:

doLast {
    def moveFunc = { resSuffix ->
        File originalDir = file("$buildDir/generated/res/react/release/drawable-${resSuffix}");
        if (originalDir.exists()) {
            File destDir = file("$buildDir/../src/main/res/drawable-${resSuffix}");
            ant.move(file: originalDir, tofile: destDir);
        }
    }
    moveFunc.curry("ldpi").call()
    moveFunc.curry("mdpi").call()
    moveFunc.curry("hdpi").call()
    moveFunc.curry("xhdpi").call()
    moveFunc.curry("xxhdpi").call()
    moveFunc.curry("xxxhdpi").call()
}

This code moves resource files generated during the build process to the correct location, overwriting resources previously copied via the react-native bundle command, thereby eliminating duplication. Note that this method requires manual modification of files in node_modules, which may be lost when reinstalling or upgrading React Native.

Solution 2: Cleaning Resource Directories

Manually clean potentially duplicate resource directories before building release APKs:

rm -rf ./android/app/src/main/res/drawable-*
rm -rf ./android/app/src/main/res/raw

Or use Gradle's clean command:

cd android
./gradlew clean

This approach is straightforward but requires executing cleanup before each build, making it unsuitable for automated build workflows.

Solution 3: Optimizing Build Scripts

For projects using React Native 0.61.2 or later, resource duplication can be avoided by modifying build scripts in package.json:

"release-build": "react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/build/intermediates/res/merged/release/ && rm -rf android/app/src/main/res/drawable-* && rm -rf android/app/src/main/res/raw/* && cd android && ./gradlew assembleRelease && cd .."

Key improvements in this script include:

1. Changing the resource output directory to android/app/build/intermediates/res/merged/release/
2. Cleaning potentially conflicting resource directories before building
3. Ensuring resources exist in only one location to prevent duplication

Best Practice Recommendations

Based on the above analysis, developers are advised to adopt the following best practices:

1. Prioritize modifying react.gradle: Although it requires modifying node_modules, this is the most comprehensive solution
2. Establish automated build workflows: Integrate cleanup and build steps into CI/CD processes
3. Regularly update React Native versions: Monitor official fixes, as this issue may have been improved in newer versions
4. Use version control to ignore generated files: Add android/app/src/main/res/drawable-* to .gitignore

Technical Principles Deep Dive

From a technical perspective, the root cause of this problem lies in the incompatibility between React Native's resource management mechanism and Android's Gradle build system. React Native uses JavaScript-driven resource packaging, while Android uses Gradle for resource merging. When both systems handle the same resources simultaneously, conflicts arise.

This issue is particularly evident in React Native 0.57.x versions, which introduced new resource handling logic. While React Native continues to optimize this mechanism with updates, the problem may still occur under specific configurations.

Conclusion

The duplicate resource error in React Native Android builds is a common but solvable issue. By understanding the mechanisms behind error generation, developers can choose the most suitable solution for their projects. Whether modifying build scripts, cleaning resource directories, or optimizing build workflows, the core objective is to ensure resource files exist in only one location during the build process. As the React Native ecosystem evolves, we anticipate more comprehensive official solutions to fundamentally eliminate such build issues.