How Taro Transforms React Code to Run on HarmonyOS ArkUI

Background

With the rapid growth of HarmonyOS, developers aim to migrate existing cross‑platform apps to the new platform. Taro, a popular cross‑platform framework, has attracted attention for its potential to support HarmonyOS, but the native UI framework ArkUI differs significantly from the platforms Taro originally targets, creating a technical challenge of linking React‑based Taro code with ArkUI's declarative UI.

Taro Runtime Principles

Taro converts React code into executable forms for each platform, including HarmonyOS. It does this through a custom renderer that translates React operations into a Taro virtual node tree, which serves as a unified intermediate representation.

The renderer implements the hostConfig interface required by ReactReconciler, providing methods such as createElement (creates an ArkUI element), createTextInstance (creates a text node), appendChild, removeChild, insertBefore, and commitUpdate (updates element properties). The following snippet shows a partial implementation:

// 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);
  },
  // ... other methods
};

From Taro to ArkUI

Mapping the Taro virtual node tree to ArkUI involves three key steps:

Create Taro Elements : For each component type (e.g., View, Text, Image), a corresponding Taro element is instantiated. Example code:

// 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;
    // ... other cases
  }
  return item;
}

Create Taro RenderNodes : Each Taro element is transformed into a render node that more closely resembles ArkUI's structure.

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

Create ArkUI Nodes : The render node interacts with ArkUI's native API to instantiate actual UI components.

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

During this conversion, differences such as composite component structures, layer position adjustments, and platform‑specific components are handled, often requiring a dedicated Render Tree to act as an intermediate bridge.

Conclusion

The Taro framework enables React applications to run on HarmonyOS by implementing a custom renderer that converts React operations into a Taro virtual node tree and then maps that tree to ArkUI native components through a three‑step process (Taro Element → Taro RenderNode → ArkUI Node). This approach provides a robust solution for cross‑platform development on HarmonyOS.