Flutter for Web: Architecture, Platform Issues, and Disaster‑Recovery Solutions at Beike

Background

Flutter added Web support in version 1.5 (2019) and entered the stable channel with Flutter 2. Beike has integrated Flutter into more than 24 of its apps, covering over 70% of its UI, and now seeks a way to downgrade problematic pages without a full app release.

Flutter for Web Exploration and Main Issues

The team first compiled a Flutter project to Web and observed a runtime error when Platform._operatingSystem was called, because the generated main.dart.js contains a stub that throws an exception. The underlying cause is that dart:io and related libraries are marked as unsupported in the Web SDK.

Flutter for Web Front‑End Compilation

When flutter build web is executed, the tool runs dart2js with a set of command‑line options (shown below) to produce a dill kernel file and then JavaScript output.

final List
sharedCommandOptions = <String>[ globals.artifacts.getArtifactPath(Artifact.engineDartBinary), '--disable-dart-dev', globals.artifacts.getArtifactPath(Artifact.dart2jsSnapshot), '--libraries-spec=
/libraries.json', ... ];
final ProcessResult kernelResult = await globals.processManager.run<String>([...sharedCommandOptions, '-o', environment.buildDir.childFile('app.dill').path, '--packages=.packages', '--cfe-only', environment.buildDir.childFile('main.dart').path]);
if (kernelResult.exitCode != 0) { throw Exception(kernelResult.stdout + kernelResult.stderr); }

The Web SDK’s libraries.json marks dart:io and isolate as supported: false , explaining the exception.

Operating‑System Detection Solution

Instead of using kIsWeb checks throughout the code, the team calls JavaScript directly via js_util.callMethod to query window.isAndroid or window.isIOS . They then replace existing platform checks with Aspect‑Oriented Programming (AOP) using their internal library Beike AspectD, so the original business code remains untouched.

js_util.callMethod(html.window, 'isAndroid', []);
js_util.callMethod(html.window, 'isIOS', []);

Platform Channel Issue

MethodChannel communication, which relies on the native engine, is unavailable on Web. The team designed a three‑layer bridge: a Native Channel on the iOS/Android side, a Flutter Web Channel on the Web side, and a JavaScript bridge connecting them. Calls are hooked, serialized with a unique ID, transferred via JS, executed on the opposite side, and the result is routed back.

dart:io File‑System API Issue

Because dart:io is unsupported, the team overrides file‑system calls using the IOOverrides class. An example override redirects readAsBytes() to a custom plugin that invokes native file‑reading code.

@pragma('vm:entry-point')
class FileOverride extends FileSystemEntity implements File {
  @override
  @pragma('vm:entry-point')
  Future
readAsBytes() async {
    return await FlutterFileOverridePlugin.overrideReadAsBytes(path);
  }
}

Disaster‑Recovery and Degradation Design

The solution is split into six modules: CI platform for building and packaging, package‑management service, configuration service for routing rules, native client that hosts a local server and loads the Web container, a JS layer shipped with the client, and the Flutter Web bundle that includes the custom channels. This architecture enables on‑the‑fly replacement of a failing native Flutter page with a pre‑compiled Web fallback without a new app release.

Conclusion

Beike’s Flutter team successfully leveraged Flutter’s cross‑platform nature to create a robust, Web‑based fallback mechanism, addressed platform‑specific limitations with AOP and IO overrides, and built a comprehensive degradation pipeline that improves release velocity and reliability across iOS, Android, and Web.