Environment Setup and Project Creation for HarmonyOS Flutter Development

Before starting, read the project's README file thoroughly (at least ten times). The flutter_flutter project is the core of this guide, and it must be built from the dev branch: https://gitee.com/openharmony-sig/flutter_flutter/tree/dev/.

The project supports Linux, macOS, and Windows. Follow the README to configure the OpenHarmony SDK, ohpm , and sdkmanager . Ensure the SDK version matches the project; the current official Flutter version is 3.7.

Configure the command‑line signing tool. It requires Gradle 7.1 and Java 11. On macOS you can install Java 11 via Homebrew and then uncomment the Java 11 entry in the environment variables.

export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"

After a successful build, the signing tool produces ./hapsigntool/hap_sign_tool/build/libs/hap-sign-tool.jar .

To run a HarmonyOS Flutter project locally, you need a customized Flutter Engine. Clone and build it from https://gitee.com/openharmony-sig/flutter_engine, or use the pre‑built binaries provided in the documentation: https://docs.qq.com/sheet/DUnljRVBYUWZKZEtF?tab=BB08J2.

It is still recommended to compile the engine yourself to enjoy the custom‑engine experience.

Verify the environment with flutter doctor -v . A successful output looks like:

flutter doctor
[✓] OpenHarmony toolchain - develop for OpenHarmony devices
• OpenHarmony Sdk location: /Users/xxx/Downloads/harmony_flutter/M1SDK/openharmony, available api versions has [10]
• hdc version 1.3.0
• ohpm version 1.4.0
• signTool location:/Users/xxx/Downloads/harmony_flutter/developtools_hapsigner/autosign

Create a Project

Run the following command to create the first HarmonyOS Flutter project:

flutter create --platforms ohos flutter_test_project

Enter the project directory and build the app with the custom engine:

flutter build hap --target-platform ohos-arm64 --debug --local-engine=~/flutter_engine/src/out/ohos_debug_unopt_arm64 -v

The local-engine points to the engine you built earlier. After a successful build, the tool automatically signs the app and produces a signed .hap package. Install it with:

flutter install ohos/entry/build/default/outputs/default/entry-default-signed.hap

Note: HarmonyOS 4.0 does not support emulators, so a real device with HarmonyOS 4.0+ is required.

Project structure is similar to a standard Flutter project, with Android/iOS replaced by ohos . The native HarmonyOS code resides in entry‑src‑main‑ets , where you can find GeneratedPluginRegistrant.ets . The overall layout remains familiar, making it easy to start native development.

Three‑Platform Unification

There are two development modes for HarmonyOS Flutter:

Pure Flutter project where HarmonyOS native code lives inside the Flutter project.

Dependency mode using a compiled .har artifact, similar to Android/iOS library integration.

The first mode is simpler because HarmonyOS native code is declarative (Compose‑like), allowing you to embed a FlutterPage() directly as a view. The second mode aligns better with the goal of three‑platform unification and facilitates team collaboration, but third‑party Flutter plugins that require native support must be adapted for HarmonyOS.

Currently, the flutter_flutter build har command has a bug that causes compilation failures; the community is working on a fix.

The HarmonyOS Flutter community maintains a compatibility plan for third‑party libraries (see https://docs.qq.com/sheet/DVVJDWWt1V09zUFN2?tab=BB08J2). Most pure‑Dart plugins work out‑of‑the‑box, while plugins with native components need adaptation.

This article provides the initial steps for a HarmonyOS Flutter project. Future posts will cover mixed‑code solutions and bridge methods.