How Taro Enables React Code to Run on HarmonyOS ArkUI: Runtime Principles and Implementation

With the rapid development of the HarmonyOS platform, developers aim to migrate existing cross‑platform applications, and Taro—a popular cross‑platform framework—has attracted attention for its potential to support HarmonyOS.

HarmonyOS uses the new ArkUI framework for native UI, which differs significantly from the platforms Taro originally supports, making the integration of React‑based Taro code with ArkUI a technical challenge.

This article explores how Taro achieves this integration by introducing its runtime principles, the custom Taro Renderer, and the conversion process that maps React components to ArkUI structures.

Taro Runtime Principles

Taro converts React code into a platform‑agnostic intermediate representation. The article details how Taro transforms React components into a virtual node tree that can be adapted for HarmonyOS.

From React to Taro

React’s Renderer maps virtual nodes to platform‑specific implementations (e.g., react‑dom for browsers, react‑native for iOS/Android). Taro implements a similar renderer, creating a bridge between React operations and Taro’s virtual node tree.

HostConfig Interface Implementation

// Partial HostConfig interface implementation
const hostConfig: HostConfig {
  // Create Taro virtual node
  createInstance (type, props: Props, _rootContainerInstance, _hostContext, internalInstanceHandle: Fiber) {
    const element: TaroElement = TaroNativeModule.createTaroNode(type)
    precacheFiberNode(internalInstanceHandle, element)
    updateFiberProps(element, props)
    return element
  },
  // Update properties
  commitUpdate (dom, updatePayload, _, oldProps, newProps) {
    updatePropsByPayload(dom, oldProps, updatePayload)
    updateFiberProps(dom, newProps)
  },
  // Insert node
  insertBefore (parent: TaroElement, child: TaroElement, refChild: TaroElement) {
    parent.insertBefore(child, refChild)
  },
  // Remove node
  removeChild (parent: TaroElement, child TaroElement) {
    parent.removeChild(child)
  },
  // ...
}

By implementing these methods, Taro’s Renderer translates React operations into actions on the Taro virtual node tree, which serves as the core of its cross‑platform capability.

From Taro to ArkUI

The conversion from Taro virtual nodes to ArkUI involves three key steps: creating corresponding ArkUI components, handling structural differences (such as composite components and layer adjustments), and maintaining a render tree that bridges Taro and ArkUI.

Creating Taro Elements by Component Type

// Create Taro element based on component type
std::shared_ptr
TaroDocument::CreateElement(napi_value &node) {
    // Get component type
    TAG_NAME tag_name_ = TaroDOM::TaroElement::GetTagName(node);
    std::shared_ptr
item;
    switch (tag_name_) {
        case TAG_NAME::SCROLL_VIEW: {
            item = std::make_shared
(node);
            break;
        }
        case TAG_NAME::IMAGE:
            item = std::make_shared
(node);
            break;
        case TAG_NAME::SPAN:
        case TAG_NAME::TEXT: {
            item = std::make_shared
(node);
            break;
        }
        case TAG_NAME::SWIPER: {
            item = std::make_shared
(node);
            break;
        }
        // ...
    }
    return item;
}

After creating Taro Elements, they are transformed into Taro RenderNodes, which are closer to the ArkUI hierarchy.

Creating Taro RenderNode

void TaroSwiper::Build() {
    if (!is_init_) {
        // create render node
        TaroElementRef element = std::static_pointer_cast
(shared_from_this());
        auto render_swiper = std::make_shared
(element);
        render_swiper->Build();
    }
}

Creating ArkUI Node

// Create ArkUI Node
void TaroSwiperNode::Build() {
    NativeNodeApi *nativeNodeApi = NativeNodeApi::getInstance();
    // Create a Swiper ArkUI node
    SetArkUINodeHandle(nativeNodeApi->createNode(ARKUI_NODE_SWIPER));
}

These three steps—creating Taro Elements, converting them to RenderNodes, and finally generating ArkUI Nodes—enable React components to be rendered accurately on HarmonyOS.

Conclusion

The article summarizes that Taro’s custom renderer and the three‑stage conversion pipeline allow React code to run on HarmonyOS ArkUI, providing a robust solution for cross‑platform development.