React Native 0.81.1 Upgrade Guide

Upgrading your React Native app to 0.81.1 ensures better performance, security, and tooling and prepares you for the full New Architecture migration. This guide is updated to reflect current best practices on both Android (Kotlin) and iOS (Objective-C/Swift) native files.

Why Upgrade?

• Performance: Enhanced Hermes engine, faster builds, better runtime.
• Security: Latest patches and vulnerability fixes.
• New Features: Fabric renderer, TurboModules, and New Architecture are enabled by default.
• Better Tooling: Strict TypeScript API, upgraded debugging.
• Ongoing Support: Legacy architecture frozen; full removal planned later in 2025.

Pre-Migration Checklist

• All changes are committed to version control (Git).
• Created a dedicated upgrade branch.
• Ensure clean Android and iOS builds without errors.

Step-by-Step Upgrade Process

1. Assess Current React Native Version

• Check your current version in package.json (e.g., 0.67.x, 0.71.x, 0.78.x).
• Plan your upgrade path to 0.81.1.

2. Prepare for Migration

a. Use React Native Upgrade Helper

• Visit the Upgrade Helper tool.
• Select your current and target versions.
• Review diffs especially:
  • android/app/src/main/java/<your-package>/MainApplication.kt
  • android/app/src/main/java/<your-package>/MainActivity.kt
  • android/build.gradle, android/app/build.gradle
  • ios/Podfile, ios/AppDelegate.m or .mm (default)
  • Optionally, ios/AppDelegate.swift if your project uses Swift.

b. Read Release Notes and Breaking Changes

• Check React Native 0.80.x official release notes.
• Note deprecated deep imports, frozen legacy architecture, and strict TypeScript API.

3. Upgrade Core Dependencies

npm install react-native@0.81.1
npm install react@19.1.0 react-test-renderer@19.1.0

Also, update peer dependencies such as metro, flipper as needed.

4. Clean Project Before Rebuilding

watchman watch-del-all
rm -rf node_modules ios/Pods ios/Podfile.lock android/.gradle android/build ios/build ~/Library/Developer/Xcode/DerivedData
npm cache clean --force
npm install
cd ios && pod install --repo-update && cd ..

5. Update Native Code

Android (Kotlin):

• Migrate or update MainApplication.java and MainActivity.java to Kotlin .kt files.
• Refer to Upgrade Helper Kotlin templates.

Confirm android/build.gradle includes:

apply plugin: 'org.jetbrains.kotlin.android'

Rewrite any legacy Java code to Kotlin syntax as needed.

iOS (Objective-C or Swift):

• By default, React Native 0.81.1 uses Objective-C-based AppDelegate.m / .mm.
• If your app is fully Swift or you prefer Swift, migrate manually to AppDelegate.swift:
  • Ensure the Xcode project has proper Swift bridging setup.
  • Port lifecycle methods and imports to Swift.
  • Maintain compatibility with Objective-C libraries as needed.
• Use Upgrade Helper diffs for changes in lifecycle and imports.

6. Update Third-Party Libraries

npm outdated
npm install <package>@latest

• Confirm compatibility with RN 0.81.1 and Kotlin-based Android if applicable.
• Patch or replace incompatible libraries.

7. Fix Deprecated Imports

• Replace all deep imports, e.g.,

import { Alert } from 'react-native/Libraries/Alert/Alert';
to with
import { Alert } from 'react-native';

8. Enable New Architecture (Recommended)

• In android/gradle.properties:

newArchEnabled=true

• In Xcode Build Settings:

RCT_NEW_ARCH_ENABLED=1

• Confirm all dependencies support the New Architecture.

9. Rebuild and Test Thoroughly

npx react-native run-android
npx react-native run-ios

• Test full workflows, native modules, and navigation on devices and emulators.
• Fix any build or runtime errors related to Kotlin or Swift migration.

10. Troubleshooting

Problem	Solution
Kotlin compilation errors	Compare .kt files to the latest templates, check plugin versions and Gradle setup.
Module map not found (iOS)	rm -rf ~/Library/Developer/Xcode/DerivedDatacd ios && pod deintegrate && pod install
Invariant Violation / Null errors	Run npx react-native-clean-project and update dependencies
ESLint/TypeScript issues	Fix deprecated imports, update type definitions

Validation Checklist

•  Core React Native dependencies updated.
•  Android native files updated and migrated to Kotlin (.kt).
•  iOS uses updated AppDelegate.m/.mm, or migrated to AppDelegate.swift if preferred.
•  All third-party libraries are compatible and updated.
•  Deep imports removed.
•  (Optional) Adopt a strict TypeScript API.
•  Successful clean build and run on Android and iOS.
•  All critical features fully tested.
•  Documentation updated to reflect Kotlin and iOS native language choices.
•  All changes committed and merged.

Automating Future Upgrades

• Use:

npx react-native upgrade

• Set up Dependabot or similar tools to monitor dependencies.
• Run npm audit regularly for security alerts.

Summary of Key Changes

• Android native app code is now recommended to use Kotlin (MainApplication.kt), migrating away from Java.
• iOS native app code remains by default Objective-C (AppDelegate.m / .mm), but Swift (AppDelegate.swift) is supported via manual migration.
• Legacy React Native architecture is frozen; migrate to the New Architecture using JSI, TurboModules, and Fabric.
• Deep imports deprecated; use only top-level imports.
• Hermes is now the default JavaScript engine; JSC is discontinued.
• Strict TypeScript API is available and encouraged for stronger type safety.