React Native's Platform Build Glue

WHY IT EXISTS: React Native runs JavaScript inside a native app, but the Android build system has no native knowledge of JavaScript packages or native modules shipped inside NPM dependencies. The platform-specific configuration files exist to bridge this gap, teaching Gradle how to find, link, and bundle React Native code alongside existing Java or Kotlin source.

THE MENTAL MODEL: Think of it as installing a foreign engine into a car. The engine itself is portable, but the mounting brackets, fuel lines, and electrical connectors must be fabricated specifically for the chassis. On Android, those connectors are Gradle scripts. They do not ship with your existing app; you must bolt them on so the JavaScript runtime can start and native modules can register themselves.

HOW IT WORKS: Integration requires editing three separate Gradle files. First, settings.gradle points to the React Native Gradle Plugin inside node_modules and enables autolinking via the ReactSettingsExtension. Second, the top-level build.gradle adds the plugin to the buildscript classpath so Gradle can resolve it. Third, the app-level build.gradle applies the com.facebook.react plugin, adds the react-android and hermes-android dependencies, and calls autolinkLibrariesWithApp inside a react block. Each file has a distinct responsibility, and they must be modified in concert.

WHEN TO USE IT: Use this approach when you are adding React Native screens or features to an existing Android application rather than starting fresh with a framework like Expo. It is also the path you follow when brownfielding a legacy native app where rewriting the entire codebase is not an option.

WHEN NOT TO USE IT: Do not use manual Gradle integration if you are building a new greenfield app from scratch. In that case, a framework or the Community Template handles these files automatically. You should also avoid this path if your team lacks Android build expertise, because Gradle errors are opaque and debugging them requires reading native build logs.

ONE CANONICAL EXAMPLE: You have an existing Kotlin banking app and want to add a React Native dashboard. You move the Android project into an android subdirectory, add a package.json, and install dependencies. Then you edit settings.gradle to include the React Native Gradle Plugin from node_modules and enable autolinking. In the top-level build.gradle you add the plugin classpath. In the app build.gradle you apply the com.facebook.react plugin, add implementation lines for react-android and hermes-android, and configure autolinkLibrariesWithApp. If you accidentally edit the top-level build.gradle dependencies block instead of the app-level one, the app compiles but native modules like encryption libraries never link, causing runtime crashes when the dashboard tries to use them.