Design and Implementation of Taro 3 Adaptation for React Native

Taro 3 has entered the era of a near‑full runtime architecture, allowing developers to enjoy a complete React/Vue development experience. To bring this capability to React Native, the 58 Frontend team created a dedicated taro-runtime-rn package that adapts standard Taro React code to the React Native environment.

Background : The goal was to keep the solution consistent with the mini‑program design while leveraging the React Native ecosystem, avoiding performance loss and excessive complexity that arise from a pure mini‑program‑style adaptation.

Design Options : Two schemes were considered – (1) simulating browser BOM/DOM APIs in React Native, and (2) compiling and runtime adapting Taro code. The second option was chosen for better alignment with React Native.

Detailed Design : The overall workflow uses Metro to bundle Taro source code into a jsBundle . Metro’s three phases – Resolution, Transformation, and Serialization – are extended with custom transformers ( taro-rn-transformer and taro-rn-style-transformer ) that convert Taro syntax and styles into React Native‑compatible code.

Runtime Modules :

taro-router-rn : wraps React Navigation to provide dynamic routing.

taro-runtime-rn : exposes createReactNativeApp (entry wrapper) and createPageConfig (page wrapper) to handle configuration, lifecycle, and navigation.

taro-rn-transformer : injects entry handling and global styles during compilation.

Entry File Support : The original mini‑program app.config.ts and app.tsx are parsed, pages are converted to camel‑case component names, and a React Native entry is generated that registers the root component via AppRegistry.registerComponent and calls createReactNativeApp with the merged configuration and router list.

import { AppRegistry } from 'react-native';
import { createReactNativeApp } from '@tarojs/runtime-rn';
import App from './src/app';
import pagesIndexIndex from './src/pages/index/index';
import pagesIndexAbout from './src/pages/index/about';

const config = {"appConfig":{"pages":["pages/index/index","pages/index/about"],"window":{"backgroundTextStyle":"light","navigationBarBackgroundColor":"#fff"}}};
const routers = [
  {name: 'pagesIndexIndex', component: pagesIndexIndex},
  {name: 'pagesTabbarHome', component: pagesIndexAbout}
];
AppRegistry.registerComponent('app', createReactNativeApp(App, {config, routers}));

Page Support : Each page is wrapped with createPageConfig , which injects page configuration, lifecycle hooks, and page functions (e.g., onPullDownRefresh , onPageScroll ) by rendering the original component inside a ScrollView when needed.

import { createPageConfig } from '@tarojs/runtime-rn';
import pagesIndexIndex from './src/pages/index/index';
import pageConfig from './src/pages/index/index.config';
export default createPageConfig(pagesIndexIndex, pageConfig);

Lifecycle Handling : componentDidShow and componentDidHide are triggered on navigation focus/blur events and on app foreground/background changes via AppState . Page functions such as onReachBottom and onPullDownRefresh are implemented using ScrollView callbacks.

Current Object : The runtime provides a getCurrentInstance method that returns a Current object containing app , page , and router , mirroring the mini‑program API for seamless code reuse.

Integration with Existing React Native Projects : The solution can be merged with an existing RN codebase by exporting Taro’s Metro configuration, merging it with the project’s config, and using the provided runtime functions to wrap Taro pages without altering existing RN pages or navigation logic.

Summary : Taro 3 React Native adapts Taro’s runtime through Metro bundling, custom transformers, and runtime wrappers, delivering a flexible, performance‑friendly bridge that aligns closely with the React Native ecosystem while supporting all essential Taro page features and lifecycle semantics.