This article focuses on hybrid development with HarmonyOS NEXT and Flutter Module. The core goal is to embed cross-platform UI seamlessly into a HarmonyOS native project so you can achieve code reuse, consistent rendering, and incremental migration. It is ideal for teams that already have Flutter features and want to bring them into HarmonyOS. Keywords: HarmonyOS NEXT, Flutter Module, hybrid development.
Technical Specifications at a Glance
| Parameter | Description |
|---|---|
| Primary Languages | Dart, ArkTS/ETS, JSON5 |
| Runtime Platform | HarmonyOS NEXT |
| Integration Method | Source-level integration of a Flutter Module into a native project |
| License | Original article states CC 4.0 BY-SA |
| GitHub Stars | Not provided in the source |
| Core Dependencies | Flutter SDK 3.24.0+, DevEco Studio 5.0.0 Beta2+, JDK 17, Node.js 14+, @ohos/flutter_module, @ohos/flutter_ohos |
This approach solves the problem of rebuilding cross-platform UI repeatedly
Integrating a Flutter Module into a HarmonyOS project essentially means treating Flutter as an embeddable UI runtime. The value is straightforward: existing Flutter pages, complex animations, and chart components can continue to be reused, so you do not need to rebuild the same interface specifically for HarmonyOS NEXT.
For enterprise projects, this approach is especially well suited to incremental refactoring. HarmonyOS continues to provide native capabilities, while Flutter handles the cross-platform business layer and complex interactions. This helps avoid the risks and costs of a full one-time migration.
Environment setup must satisfy both toolchains
Hybrid development is not about a single SDK. It requires the HarmonyOS toolchain and the Flutter toolchain to work side by side. The most common pitfall is not the code itself, but whether the Flutter SDK actually includes OpenHarmony support.
| Component | Recommended Version | Purpose |
|---|---|---|
| DevEco Studio | 5.0.0 Beta2+ | Create and debug HarmonyOS native projects |
| Flutter SDK | 3.24.0+ | Compile Dart code and build the Flutter Module |
| JDK | 17 | Base build environment |
| Node.js | 14.x+ | Script and dependency support |
# Check whether the Flutter toolchain includes HarmonyOS support
flutter doctor
# Key check: the output should recognize HarmonyOS support
# If it does not, the current SDK cannot be used directly for HarmonyOS integrationThis command verifies whether your Flutter environment is ready to build for HarmonyOS.
Creating a Flutter Module is the starting point of the hybrid architecture
A Flutter Module is not a standalone app. It is a business module designed to be embedded into a native project. That role means the project structure should prioritize reusability rather than a complete app startup flow.
# Create an embeddable Flutter module
flutter create --template=module my_flutter_moduleThis command generates a Flutter Module that can be referenced by a HarmonyOS native project.
After creation, build the smallest possible validation page first so you can quickly confirm whether the integration works.
import 'package:flutter/material.dart';
void main() => runApp(MyFlutterApp());
class MyFlutterApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(title: const Text('Flutter Hybrid Page')), // Verify that the title renders correctly
body: const Center(
child: Text(
'This content comes from Flutter!', // Verify that the Flutter page has taken over rendering
style: TextStyle(fontSize: 24),
),
),
),
);
}
}This code builds a minimal Flutter page so you can verify that the embedded rendering path is working.
You declare the local module dependency in the HarmonyOS native project
The key to source integration is not copying files, but declaring dependencies correctly. The HarmonyOS project treats the Flutter Module as a local package through oh-package.json5, which allows the IDE and build system to recognize its source code and artifacts.
{
"name": "harmonyfluttermix",
"version": "1.0.0",
"dependencies": {
"@ohos/flutter_module": "file:../../my_flutter_module" // Reference the Flutter Module locally
},
"devDependencies": {
"@ohos/hypium": "1.0.18"
}
}This configuration adds the Flutter Module to the HarmonyOS project as a local dependency.
After saving the file, run Sync Now in the IDE. If synchronization fails, check the path first, then verify SDK compatibility and package naming.
The entry Ability must be switched to FlutterAbility
The action that actually makes a Flutter page run is replacing the default UIAbility with FlutterAbility. This step determines whether the app initializes the Flutter Engine automatically at launch.
import { FlutterAbility } from '@ohos/flutter_ohos';
export default class EntryAbility extends FlutterAbility {
onCreate(want, launchParam) {
super.onCreate(want, launchParam); // Initialize the Flutter engine lifecycle
console.info('FlutterAbility onCreate');
}
onDestroy() {
super.onDestroy(); // Release engine-related resources
console.info('FlutterAbility onDestroy');
}
}This code gives the entry Ability the ability to host and manage the Flutter Engine.
The module.json5 file must align with the Flutter-driven page takeover model
When Flutter takes over page rendering, module.json5 should no longer follow a traditional pages-based routing model. Flutter manages most page transitions through its own engine, while the native side only handles Ability startup and lifecycle hosting.
{
"module": {
"name": "entry",
"type": "entry",
"mainElement": "EntryAbility",
"deviceTypes": ["default", "tablet"],
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"exported": true,
"launchType": "standard" // Keep the standard launch mode
}
]
}
}This configuration ensures that the HarmonyOS module starts with FlutterAbility as the application entry point.
The runtime result should reflect native hosting plus Flutter rendering
After connecting a HarmonyOS device or emulator and running the project, the app will typically show the native startup window first and then switch into the Flutter-rendered page. If everything works, you will see the title and text defined in main.dart.
That confirms the full integration path is working: the native Ability serves as the host and lifecycle container, while the Flutter Engine handles UI rendering. The two cooperate through an embedded architecture.
The real advantage of this hybrid model is incremental evolution
From an architectural perspective, Flutter provides a unified rendering layer, while HarmonyOS provides access to system-level capabilities. Flutter solves cross-platform UI consistency. HarmonyOS handles device features, distributed capabilities, and deep platform integration.
This is not a question of one replacing the other. It is a clean separation of responsibilities: UI and interaction logic are reused across platforms, while system capabilities remain native. For existing apps, this is a safer upgrade path than a full rewrite.
The most common risks center on plugins and memory management
If your Flutter page depends on third-party plugins, you must confirm that those plugins support OpenHarmony. Otherwise, you need to bridge HarmonyOS native capabilities yourself through Platform Channels, which is one of the most common extension points in real projects.
In addition, the Flutter Engine adds memory overhead. On lower-end devices, avoid creating engine instances without limits. If necessary, destroy the engine promptly after leaving a page to prevent long-lived residency from causing memory pressure.
FAQ
Q1: Why not use pure HarmonyOS native development directly?
A: If your team already has mature Flutter pages or needs to support Android, iOS, and HarmonyOS at the same time, reusing a Flutter Module usually provides a better return on investment, especially for complex UI and animation scenarios.
Q2: After integration, the page does not render. What should I check first?
A: Start with these three items: whether the Flutter SDK supports HarmonyOS, whether the local path in oh-package.json5 is correct, and whether the entry class actually extends FlutterAbility.
Q3: What if a third-party Flutter plugin does not support HarmonyOS?
A: There are usually two options: replace it with a compatible plugin, or implement the capability natively on the HarmonyOS side and expose it to Flutter through Platform Channels.
AI Readability Summary: This article walks through the full process of integrating a Flutter Module into HarmonyOS NEXT, including environment preparation, module creation, dependency declaration in oh-package.json5, migration to FlutterAbility, module.json5 configuration, and runtime validation. It also summarizes the architectural benefits of hybrid development, along with practical guidance on plugin compatibility and memory management.
AI Visual Insight: In this integration model, HarmonyOS acts as the native host that owns application startup and lifecycle management, while Flutter acts as the embedded rendering engine for cross-platform UI. Together they form a layered architecture that enables reuse without sacrificing native capability access.