How Taro 3 Brings React Native Support: Design, Implementation, and Migration Guide

Overview

An RFC (https://github.com/NervJS/taro-rfcs/pull/8) proposes a large‑scale refactor to restore and improve React Native support in Taro 3. The changes cover compilation, runtime, API, and component layers to align with Taro 3 standards.

Motivation

After Taro 3 was released, built‑in React Native support disappeared, yet many projects still need to develop React Native apps using Taro.

Design Summary

Unify the compilation and bundling pipeline under Metro, which matches the React Native ecosystem.

Refactor runtime modules to follow Taro 3 specifications and generate entry and page code via a custom taro-rn-transformer.

Expand API and component coverage, prioritising features based on community surveys and using the Expo ecosystem as the primary target.

Provide a flexible app‑integration scheme that does not lock a specific React Native version and allows optional native module dependencies.

Compilation & Bundling Changes

The build system now uses Metro instead of Webpack, delivering faster compilation, smaller bundles, better source‑map support, and easier merging with user‑defined Metro configs.

rn: {
  sass: { options: ..., additionalData: ..., sourceMap: boolean },
  less: {},
  stylus: {},
  postcss: {}
}

Key Babel plugins added: transform-jsx-to-stylesheet – enables className syntax. module-resolver – maps @tarojs/components to @tarojs/components-rn and @tarojs/taro to @tarojs/taro-rn.

Metro configuration from taro-rn-runner is merged with the project's metro.config.js and supports common options such as defineConstants, alias, env, terser, csso, and sass.

Runtime Support

The runtime follows the Taro 3 standard and provides: createReactNativeApp – wraps a Taro app with React Native entry logic. createPageConfig – wraps page components.

Global Current object exposing app, page, and router similar to mini‑programs.

Hooks such as useDidShow, useDidHide, and usePullDownRefresh are provided, mirroring the H5 implementation.

API Refactoring

Missing APIs are now implemented, most built on Expo modules:

TabBar APIs – wrapped with React Navigation.

VideoContext, AudioContext, CameraContext – based on expo-av and expo-camera.

File‑related APIs – built on expo-file-system.

Canvas – using react-native-canvas.

Network requests – using fetch and Expo file system.

Component Refactoring

Component packages are forked from the 2.x versions and extended: VirtualList – wraps FlatList. MovableView / MovableArea – built with Animated and PanResponder. Label – a clickable View. PickerView / PickerViewColumn – based on @ant-design/react-native.

Media components (Audio, Video, Camera) – wrapped with Expo AV modules.

App Integration Changes

The app.config.ts now includes an appName field used for AppRegistry.registerComponent. The solution supports multiple React Native versions (>=0.60) and does not force all native modules; missing modules only emit warnings.

import { appName } from './app.config';
AppRegistry.registerComponent(appName, () => App);

Sub‑package (split‑bundle) support is not yet available; sub‑packages are merged into the pages array.

Known Defects & Adaptation Strategy

Limitations include:

Vue or jQuery code cannot be used to write React Native apps.

Design differences compared with mini‑programs and H5.

Metro‑based bundling differs from Webpack, requiring synchronization with new Taro releases.

Adaptation recommendations:

Write code using Taro React; incompatible components are polyfilled when required dependencies are installed.

Native dependencies must be added to the native project or the shell repository.

React Native styling is a CSS subset; full compatibility is not guaranteed, so a “React Native first” approach is advised for cross‑platform projects.

Conclusion

The RFC delivers a comprehensive React Native support layer for Taro 3, covering build tooling, runtime, API, and component compatibility while keeping the development experience close to existing Taro mini‑program and H5 workflows.