Integrating Flutter into Large Native Projects: A Practical Refactoring Strategy

Background In early 2018, Xianyu's technical team introduced Flutter to unify client development. They successfully migrated a complex product‑detail feature but faced the challenge of integrating Flutter into already large iOS and Android codebases without hurting development efficiency.

Problem A Flutter project contains native ios and android sub‑directories that depend on Flutter libraries and assets. This creates two main issues: (1) native modules can no longer be built independently, requiring a full Flutter environment; (2) mixed compilation slows down pure native development.

Goal Minimize native projects' reliance on Flutter files so that (a) native code can compile, build, and debug independently, and (b) when native projects reside inside a Flutter directory they still correctly reference Flutter libraries, support Dart builds, hot‑reload, etc.

Solution Formulation Two modes are defined: Standalone (native projects live in independent directories) and Flutter (native projects are sub‑folders of a Flutter project). The core is to extract Flutter dependencies—App.framework, Flutter.framework, plugins, and flutter_assets—into third‑party libraries or remote repositories.

Two dependency strategies were evaluated:

1) Local dependency : copy Flutter binaries and resources into the native project. This keeps sync easy but tightly couples the code. 2) Remote dependency : host all Flutter artifacts in a remote repository and let the Standalone mode reference them. This reduces coupling at the cost of a more complex sync process. Xianyu chose the remote approach.

Implementation The directory layout places iOS and Android native projects as sub‑modules under the Flutter parent. In Standalone mode, dependencies point to the remote repo; in Flutter mode they remain unchanged. Automated scripts extract built Flutter artifacts, push them to the remote repo, tag the release, generate podspecs (iOS), and update the Standalone project to the new version. Synchronization is recommended for each test/gray‑release build, with at least a daily sync during active development.

Summary By externalizing Flutter dependencies, Xianyu achieved independent native builds while preserving full Flutter functionality. The approach has been applied to several production versions and can serve as a reference for other teams transitioning to Flutter‑based hybrid architectures.