FlutterBoost: A Hybrid Integration Framework for Mobile Apps

Large‑scale mobile apps often rely on a mature set of native libraries. Re‑writing the whole app with Flutter incurs high cost and risk, so a progressive, hybrid migration is a more reliable strategy.

Alibaba's Xianyu team has built its own hybrid solution in close collaboration with the Google Flutter team, selecting and implementing a scheme that fits their business requirements.

Basic principle : Flutter consists of a C++ Engine and a Dart Framework. One process hosts a single Dart VM, but can create multiple Engine instances that share this VM. On iOS each FlutterViewController initializes a new engine (and thread); Android activities behave similarly. Different engines run code in separate isolates while sharing the same VM.

Official recommendation : Google suggests deep engine sharing—multiple windows should render using a single engine so that all FlutterViewControllers share the same resources. However, long‑term multi‑engine support is not yet robust.

Problems with a multi‑engine mode :

Redundant resource consumption (each engine maintains its own image cache, increasing memory pressure).

Complicated plugin registration and message routing across multiple FlutterViewController s.

Differences between Flutter Widgets and native pages (VC/Activity) increase integration complexity.

Increased communication complexity when isolates are not shared.

Consequently, Xianyu adopts a shared‑engine approach: a single Flutter view acts as a canvas, and a native container drives which page is rendered inside it. This model cannot display multiple peer pages simultaneously; navigation always occurs from the top of the stack.

FlutterBoost – the next‑generation hybrid solution

Key goals:

Reusable, generic hybrid framework.

Support for complex scenarios such as tabbed home pages.

Non‑intrusive integration without modifying Flutter core.

Unified page lifecycle management.

Clear design concepts.

The architecture mirrors the old scheme but retains a shared engine. Native containers (Activity/ViewController) communicate with Flutter containers via a channel‑based messaging system. Each native container has a corresponding Flutter container (Navigator) identified by a unique ID.

Main concepts :

Container (native): platform controller, Activity, ViewController.

Container Manager: manages containers.

Adaptor: Flutter adaptation layer.

Messaging: channel‑based communication.

On the Dart side:

Container: holds Widgets, implemented as a Navigator subclass.

Container Manager: provides show/remove APIs.

Coordinator: receives messages and drives Container Manager.

Messaging: same channel mechanism.

Page understanding : In FlutterBoost, a “page” is the native container together with its associated Widget. All routing operations act on the native container; Flutter Widgets are merely the visual content.

Differences from the old solution : The old approach used a single Navigator stack in Dart. FlutterBoost replaces the stack with a flat key‑value map of containers, each with a unique ID, enabling direct lookup and switch without stack‑top constraints and without modifying Flutter source.

Multi‑Navigator implementation : Only one Flutter Navigator is visible at a time, linked one‑to‑one with a native container. Lifecycle events of the native container create/destroy the corresponding Flutter container.

Page creation flow :

Create a native container (iOS ViewController, Android Activity/Fragment).

Native container notifies Flutter Coordinator via messaging.

Flutter Container Manager creates the matching Flutter container and loads the Widget.

When the native container becomes visible, it sends a message to display the associated Flutter container.

Flutter Container Manager brings the targeted container to the foreground.

Navigation example (illustrating multi‑engine handling): FlutterPage1 -> FlutterPage2 -> NativePage1 -> FlutterPage3 . Only FlutterPage1 and FlutterPage3 need separate engine instances.

FlutterBoost is now running in production for the Xianyu client, serving hundreds of millions of users and supporting complex hybrid scenarios. The project is open‑source at https://github.com/alibaba/flutter_boost , inviting the community to contribute.