Upgrading React Native 0.63 and QRN Framework: Compatibility Strategies and Lessons Learned

1 Introduction

React Native 0.63 has been released, bringing exciting new features but also causing upgrade difficulties due to large changes in JavaScript, iOS and Android configuration files, which are often coupled.

QuNar recently completed the upgrade from 0.61.3 to 0.63.2 and shares the process.

2 What is QRN?

QRN‑js is a Qunar‑specific React‑Native framework built on top of React‑Native. It modifies native code, provides cross‑platform components and APIs, supports Redux and webx, and is used across all business lines.

To avoid duplication, Qunar splits the JS environment into multiple business packages and a framework package, each with its own bundling script, allowing independent releases.

QRN‑js is bundled into the client and loaded before business JS, ensuring a single version runs regardless of the version each business package depends on, and it supports hot‑release.

Compatibility becomes critical when the RN version changes, because many RN changes affect all business code.

3 Why Update React Native?

Gain the latest performance improvements.

Increase robustness and stability.

Access new APIs and features.

Stay aligned with major changes.

4 Upgrade Content

Collected changelogs and commits from RN 0.61 to 0.63, identified impact areas, and documented them in a wiki.

Key improvements include:

Improved debugging efficiency : LogBox replaces the old error overlay, providing readable stack traces and clickable links to source lines.

Core package slimming : Some components are moved to community libraries, reducing core bundle size and allowing independent updates.

Runtime speed boost : Removal of PropTypes in favor of Flow eliminates runtime type checks.

New interaction component – Pressable : Replaces Button/Touchable* components with a unified API that reports interaction state and supports hover, focus, etc.

Native Colors : PlatformColor and DynamicColorIOS enable direct use of native colors and dark‑mode aware colors.

Other changes: deprecations, bug fixes, React‑DevTools improvements.

5 Compatibility Solutions

5.1 Adapting core‑package slimming

Components moved out of the core package are re‑exported from react-native-community while QRN‑js redirects imports, so existing code can continue to use import {X} from 'react-native' without changes.

For components like the unified @react-native-community/datetimepicker , the team decided to keep using the old APIs to avoid forcing business lines to adapt.

5.2 Handling implementation changes

Example: Image component switched from ImageViewManager to NativeImageLoaderIOS . The compatibility layer prefers the new module when available, otherwise falls back to the old one.

5.3 Fixing official issues

Pressable’s default press‑delay caused a grey overlay; setting the delay to 0 ms restored expected behavior (fixed in RN 0.64).

iOS LogBox could block interaction when multiple hybrid IDs displayed LogBox simultaneously; a singleton guard was added on the native side to prevent multiple LogBox windows.

5.4 Business‑line upgrade problems

Many warnings appear only in dev mode; enabling dev mode and providing a consolidated document of known issues helped business teams resolve them quickly.

5.5 Red‑screen “module not found”

QRN uses a custom Metro split‑bundle mapping where framework modules start at ID 1 and business modules start at 200001. When a module exists in both maps, the framework ID wins, preventing duplicate code.

After the RN upgrade, module paths changed (e.g., /node_modules/A/index.js became /node_modules/react-native/node_modules/A/index.js ), breaking the mapping. The post‑install script now deletes RN’s internal node_modules so that all modules resolve to the top‑level location, keeping the mapping valid.

5.6 JSBundle size increase

Bundle size grew after the upgrade. By splitting the bundle into per‑module files, the team identified that Babel version upgrades added a few kilobytes per module. Locking Babel to the previous version restored the original bundle size.

6 Conclusion

The upgrade from RN 0.61.3 to 0.63.2 was completed with a comprehensive compatibility plan, allowing business lines to continue development without code changes and reducing regression effort.

Key take‑aways: prioritize compatibility, lock dependency versions that are not required to change, and maintain clear documentation of upgrade impacts.