How Taro Enables React Code to Run on HarmonyOS ArkUI: Architecture and Implementation Details

Based on Taro, JD has released a HarmonyOS app that follows the public test of HarmonyOS Next, and this series of articles deeply analyzes how Taro enables high‑performance HarmonyOS applications using React.

With the rapid growth of HarmonyOS, developers want to migrate existing cross‑platform apps, and Taro’s support for the platform has attracted attention. However, HarmonyOS uses the new ArkUI framework, which differs significantly from the platforms Taro originally supports, creating a technical challenge of bridging React’s model with ArkUI’s declarative UI.

The article first introduces Taro’s runtime principle: Taro cleverly transforms React code into platform‑specific executable forms, including for HarmonyOS, by generating a Taro virtual node tree that serves as a unified intermediate representation.

It then describes the transition from React to Taro, outlining React’s core architecture (Renderer, virtual DOM) and how Taro implements a custom Renderer that maps React operations to Taro virtual nodes, enabling cross‑platform rendering.

The required hostConfig interface methods are listed, such as createElement, createTextInstance, appendChild, removeChild, insertBefore, and commitUpdate, which together allow the Taro Renderer to translate React actions into Taro’s virtual node operations.

// Partial HostConfig implementation
const hostConfig: HostConfig = {
  // Create Taro virtual node
  createInstance(type, props, _rootContainerInstance, _hostContext, internalInstanceHandle) {
    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);
  },
  // ...
};

Next, the conversion from Taro to ArkUI is explained. It requires building a component library that maps Taro components (View, Text, Image, etc.) to corresponding ArkUI components, handling composite component structures, hierarchy adjustments (e.g., fixed‑position elements), and platform‑specific components.

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

After creating a Taro Element, it is turned into a Taro RenderNode, which brings the representation closer to ArkUI’s structure.

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

Finally, the RenderNode is converted into an actual ArkUI node by invoking the native ArkUI API.

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

These three steps—creating Taro Elements, building Taro RenderNodes, and generating ArkUI Nodes—enable React components to be accurately rendered on HarmonyOS, providing a robust solution for cross‑platform development.

END