Overview
Since Midori-san enjoys programming, she sometimes helps out with app development, right?
And she also has some experience with React.js, the JavaScript and TypeScript framework, right?
This time, I helped with making a React Native app compatible with Android 15 and upgrading React Native itself. It was quite a rare experience, so I decided to write this article for my past self, back when I was like, “Uhh… how do I even start this? What’s the plan…?” to explain what Android 15 adaptation and React Native version upgrading actually mean.
Looking Back: The Shortest Route
- Upgrade React Native to version 0.77 or higher (that’s the minimum version compatible with Android 15)
- Upgrade all dependency packages in
package.jsonto appropriate versions one by one - Replace any packages that have been discontinued with alternative ones
- Follow the official Android 15 adaptation guide to update the Android configuration files in the app
That’s really something I can only say “in hindsight.” At first, my main goal was just “Android 15 adaptation,” so my investigation went in the opposite direction.
I followed the Android 15 adaptation guide → things didn’t work well → apparently the packages were too old → tried upgrading the packages, but it still didn’t work → turns out React Native itself was too old and incompatible with the new versions of those packages → so, I had to upgrade React Native.
Ideally, I should’ve thought: “Hmm, Android 15 adaptation… the platform’s changing a lot, so I’ll probably need to upgrade React Native anyway. Let’s see—looks like Android 15 requires React Native 0.77 or higher… okay, let’s start from there.”
Now let’s go through each step in a bit more detail.
What It Means to Upgrade React Native
-
Decide which version to upgrade to
-
Ideally, you should go up to “the second latest version.” Staying close to the newest is good, but the latest one can be risky.
-
Use the React Native Upgrade Helper to fill in the “from” and “to” fields
-
Update your repository code exactly as described there
-
But well… since your own app contains original code, you probably can’t apply every change exactly as the Helper suggests. You’ll just have to handle that part with your own skills.
At this point, React Native will be new, but other packages will still be old—so your Android build will likely fail.
What It Means to Upgrade All Dependency Packages
-
Check all the packages in
package.jsonand find versions that match your React Native version -
If you could just update everything blindly, life would be easy—but some packages only support specific versions of React Native.
- While doing this, you may find something like, “Wait, there’s no supported version… it’s deprecated and recommends migrating to another package.” In that case, skip it for now and move on.
-
Update the versions
-
When updating, don’t just run
yarn install. Do something like this instead:
# node_modules
rm -rf node_modules
yarn cache clean
yarn install
# iOS side
(cd ios; rm -rf Pods Podfile.lock)
(cd ios; pod cache clean --all)
(cd ios; pod install)
Compared to my beloved Python projects, React Native projects seem to have much weaker backward compatibility between packages.
What It Means to Replace Deprecated Packages
- For the packages you found earlier that are deprecated and recommend alternatives, remove them and install their replacements
- Since the package itself changes, you’ll definitely need to modify your code accordingly
Doing this makes you really want to reduce dependency packages overall, and when using external ones, to keep things as simple as possible.
What It Means to Follow the Official Android 15 Adaptation Guide
-
In short, you’re good if you’ve covered the following three documents:
-
“Set up the Android 15 SDK”: https://developer.android.com/about/versions/15/setup-sdk?hl=ja
- “Behavior changes: All apps”: https://developer.android.com/about/versions/15/behavior-changes-all?hl=ja
- “Behavior changes: Apps targeting Android 15 or higher”: https://developer.android.com/about/versions/15/behavior-changes-15?hl=ja
-
When reading these docs, you’ll probably think “What’s AGP?” or “What’s Gradle?” so let’s sort that out:
-
Gradle: The tool that compiles code. Not specific to Android.
- AGP (Android Gradle Plugin): A plugin that adds Android build functionality to Gradle.
- Android SDK 35: The SDK for Android 15.
- Android Gradle Plugin Upgrade Assistant: A tool built into Android Studio. If you just edit Gradle or AGP versions directly in your code, sometimes the build breaks. The Assistant helps you upgrade safely—it ensures compatible versions between Gradle and AGP.
-
For this app, the “16 KB page size support” section in the “Behavior changes: All apps” document caused particular trouble.
-
https://developer.android.com/guide/practices/page-sizes?hl=ja
- Updating React Native itself pretty much handled everything described here—but that’s hindsight. Since I worked in the opposite order, I had quite a rough time.
-
Also, in the “Behavior changes: Apps targeting Android 15 or higher” document, the “Edge-to-Edge” section was another tricky one. It makes the top status bar and bottom navigation bar transparent, causing the app content to slip underneath them. For example, text at the top or buttons at the bottom can become hidden under the bars. To handle that, use
react-native-safe-area-context. -
https://github.com/AppAndFlow/react-native-safe-area-context
Thoughts
- Between these steps, you’ll face countless build and runtime errors and need to fix them carefully one by one. But thanks to recent AI agents, that wasn’t much of a problem for me.
- One thing I wondered during this process was: “Everyone developing apps must be doing this kind of platform adaptation and React Native upgrading work, so why are there so few authoritative documents describing the overall process…?”
- So, instead of focusing on the small details, I wrote this article to capture “the big picture of what an update process actually looks like.”
- Although I’ve been programming as a hobby for a long time, upgrading an existing project is a whole different skill set—one step deeper. Getting the chance to work on that made this experience really fun.
