Complete Guide to Developing HarmonyOS Native Apps with Taro (v4.0.0‑beta.x)

This article is the third in the series "Using Taro to Develop HarmonyOS Native Apps" and provides a complete step‑by‑step guide for developers to set up the environment, create a HarmonyOS project, and build the first app with Taro v4.0.0‑beta.x.

1. Environment configuration – Install and configure Huawei DevEco Studio, obtain a whitelist, download IDE 4.0.3.700, and set up the SDK path.

2. Create the Harmony main project – Create a new project in Stage mode, explore the generated directory structure (entry/src/main/ets/pages/Index.ets, build-profile.json5, etc.), and add the Harmony plugin.

3. Preview & debugging – Use a Huawei test device for preview and debugging; the emulator is not yet supported.

4. Taro development workflow

Step 1: Install Taro CLI

npm i -g @tarojs/cli@beta

Step 2: Install project dependencies (Vite, terser, @tarojs/vite‑runner)

$ npm i vite@^4.2.0

$ npm i terser@^5.4.0

$ npm i @tarojs/vite-runner@beta

Step 3: Install the Harmony plugin

$ npm i @tarojs/plugin-platform-harmony-ets@beta

Step 4: Modify Taro’s config/index.ts to enable the Harmony plugin and set the projectPath, hapName, and compiler to Vite.

Step 5: Add required permissions in entry/src/main/module.json5 (e.g., VIBRATE, INTERNET, LOCATION, etc.).

Step 6: Add build scripts in package.json :

"scripts": { "build:harmony": "taro build --type harmony", "dev:harmony": "npm run build:harmony -- --watch" }

Step 7: Run the scripts to compile and preview the app on a test device.

5. Important notes – Layout uses Flex/Column instead of the CSS box model; only px, vw, vh units are supported; some Mini‑Program APIs and components (e.g., login, live‑player) are not available; SDK version compatibility issues may arise.

Conclusion – Following this guide enables developers to quickly set up the HarmonyOS development environment and efficiently create their first HarmonyOS app with Taro.