How to Build HarmonyOS Apps with Taro: A Step‑by‑Step Guide

Background

HarmonyOS is Huawei's self‑developed operating system for ubiquitous connectivity. Taro is a cross‑platform framework that can be used to develop both HarmonyOS and OpenHarmony applications by reusing its JavaScript‑based UI model.

Implementation Details

Differences Between HarmonyOS and Mini‑Programs

Project structure : Both use an app.js entry file, pages and custom components. Each page/component consists of three files – .hml (layout), .css (styles) and .js (logic, ES6 supported by default).

Configuration : Mini‑programs have separate config files per page/component, while HarmonyOS uses a single JavaScript UI configuration file that also defines routing.

Styles : HarmonyOS inherits many CSS limitations similar to React Native (no box‑model, a restricted set of CSS properties per component).

Components & APIs : HarmonyOS provides native components and APIs whose names and capabilities differ slightly from those of WeChat mini‑programs; the overlap is partial.

Compatibility Details

What Taro can solve : Taro supplies a runtime that maps HarmonyOS components and APIs to mini‑program specifications, handling syntax differences and lifecycle emulation. CSS discrepancies and platform‑specific component capabilities remain unresolved.

HarmonyOS plugin : The core of Taro’s HarmonyOS support is the @tarojs/plugin-platform-harmony plugin. It performs the following adaptations:

a) Template handling – HarmonyOS lacks the <template> tag; Taro uses custom components for recursive rendering.

b) Runtime – Emulates mini‑program lifecycle methods and the setData data‑update mechanism.

c) Component & API mapping – Wraps HarmonyOS native components and APIs to match WeChat mini‑program specifications while preserving Harmony‑specific attributes. Currently 29 components and 16 API groups are supported (see the taro-components-sample repository).

Architecture Overview

(Architecture diagram omitted for brevity.)

Usage Instructions

Upgrade Taro to the Canary version

npm i -g @tarojs/cli@canary

Update package.json to use ~3.5.0-canary.0 for all Taro dependencies and reinstall the packages.

If installation fails, delete node_modules , yarn.lock and package-lock.json before reinstalling.

Install the Harmony plugin

yarn add --dev @tarojs/plugin-platform-harmony

Add the plugin to config/index.js:

config = {
  plugins: ['@tarojs/plugin-platform-harmony'],
  mini: {
    debugReact: true,
    enableSourceMap: false
  },
  harmony: {
    // Absolute path to the Harmony app
    projectPath: path.resolve(process.cwd(), '../MyApplication'),
    // Optional HAP name (default: 'entry')
    hapName: 'entry',
    // Optional JS FA name (default: 'default')
    jsFAName: 'default'
  }
}

Prepare the Harmony development environment

Install Huawei DevEco Studio, register a developer account, download the HarmonyOS SDK, and create a new JavaScript project (e.g., MyApplication). Use the previewer or a real device to test the app.

Build and run the project

taro build --type harmony --watch

The generated HarmonyOS package can be opened in DevEco Studio for inspection.

References

[1] Cross‑Platform UI SIG: https://gitee.com/tangjiao11/community/blob/master/sig/sig-crossplatformui/sig_crossplatformui_cn.md

[2] taro‑components‑sample (Harmony branch): https://github.com/NervJS/taro-components-sample/tree/harmony

[3] "First Look at Harmony": https://juejin.cn/post/6972109475347955749

[4] Huawei DevEco Studio: https://developer.harmonyos.com/cn/develop/deveco-studio

[5] HarmonyOS Documentation: https://developer.harmonyos.com/cn/documentation