Integrating React Native into Taro 3: Zero‑Cost Adaptation and Technical Insights

As the 58 business expands, the internal project 58‑rn was created to avoid duplicate development and improve multi‑platform efficiency, accumulating experience in componentization, workflow optimization, release platform construction, and online monitoring.

Taro, a powerful cross‑platform framework, is used across many 58 product lines. Since Taro 3 does not yet support React‑Native, the team submitted a proposal to the community to share their React‑Native implementation and benefit from community co‑development.

Project Features

Pure React‑Native support with easier community integration.

Improved source‑map support for better debugging.

Enhanced style syntax compatibility.

Runtime standards consistent with Taro 3 React.

Richer API and component set with on‑demand native dependencies.

High stability and performance, TypeScript source with full unit‑test coverage.

Core Focus

Leveraging Taro’s extensible architecture, adapting to React‑Native becomes easier. The article shares new design considerations to inspire further development.

Webpack or Metro?

Taro’s original workflow uses Webpack for web builds. The team switched to Metro to generate bundle files directly, similar to web handling. For mini‑programs, code is first compiled to target‑platform code and then built with the mini‑program IDE. Metro provides better source‑map support, faster caching via hasteFS, and aligns with React‑Native community optimizations.

Better project debugging; source‑map links runtime errors directly to source code.

Metro’s multi‑level cache and hasteFS accelerate bundling.

React‑Native community’s Metro‑based optimizations integrate more smoothly.

Zero‑Cost React‑Native Adaptation

The goal is that upgrading Taro 3 alone should make a project runnable on React‑Native without modifying the Taro template, ensuring low‑cost code reuse across platforms.

Because CSS inheritance does not apply in React‑Native, the team provides platform‑specific style hints and automatic fixes, allowing developers to gradually write multi‑platform compatible styles. Developers can also switch to the classic React‑Native CLI by adjusting the Metro configuration.

Community Integration

Taro focuses on web and mini‑program ecosystems, while React‑Native targets the React ecosystem. The team bridges gaps by improving React‑Native support in Taro components (e.g., tab‑bar, expo‑based shell) and offering a seamless development experience for both communities.

New Components & APIs

TabBar & Navigator – multi‑tab layout via simple app configuration.

Media components – video, audio, camera integration.

ScanCode API – addresses QR‑code scanning needs.

VirtualList – optimized long‑list rendering for React‑Native.

Additional components such as PickerView, MovableView, etc.

Design Approach

The solution is explained through three main scenarios: launching the dev server, accessing the bundle, and executing the bundle.

Launch Dev Server

Run yarn dev:rn to start the Metro bundle server. The CLI uses @tarojs/cli preset presets/platforms/rn.ts to start @tarojs/rn-runner , which merges user Metro config and launches MetroServer.

Access Bundle File

MetroServer acts as an HTTP server; a request to /index.bundle triggers IncrementalBundler to build or update the dependency graph, applying @tarojs/rn-transformer for entry and page handling and @tarojs/rn-style-transformer for style processing.

Bundle Execution

When the native Android (or iOS) app starts, CatalystInstanceImpl::runJSBundle executes the bundle. @tarojs/runtime-rn registers components and APIs via AppRegister.registerComponent , enabling the Taro app to run on React‑Native.

How to Use

To develop a React‑Native app with Taro 3:

# Note: the latest @tarojs/cli is not yet released; use the canary tag
$ yarn global add @tarojs/cli@canary

# Initialize a Taro project
$ npx taro init
# Set environment variable for the canary version
$ export DEVTAG=@canary

# Start the dev server (port can be specified with -p)
$ cd
&& yarn dev:rn

Download the shell app, build and install it (Android example):

# Install dependencies
$ yarn

# Build and launch the app
$ yarn android -- --no-packager

If a native environment is unavailable, download the pre‑built APK.

In the developer menu, set the bundle location to http://localhost:<port> (the port is shown when running yarn dev:rn ) to view the entry page.

Upgrade Guide

3.x – Update @tarojs/cli and all Taro dependencies, then run yarn dev:rn to install React‑Native packages.

2.x – Remove existing React‑Native related packages from package.json and follow the 3.x steps.

For issues, contact the provided channels.

Future Plans

Higher API and component adaptation coverage, with performance optimizations.

Enhanced animation support for smoother interaction.

Further improvement of the development workflow, including release pipelines, hot‑updates, and CI/CD.

Contribution & Feedback

The project uses TypeScript, Jest, and ESLint to maintain code quality and welcomes community contributions via the listed WeChat group.

Team Introduction

The team behind the Taro 3 React‑Native adaptation comes from multiple BU’s of the real‑estate group, with members responsible for architecture, Android, iOS, testing, and overall project management.