Embedding Flutter UIs in Native macOS Swift Projects

Introduction

Embedding Flutter UIs in a native macOS Swift project is a practical way to reuse Flutter code and deliver polished, cross-platform UI inside a macOS host. This approach is valuable when migrating features from mobile development to desktop or when incrementally adopting Flutter inside an existing native app. This tutorial covers the essential steps: creating a Flutter module, wiring the Flutter engine into a Swift macOS app, exchanging messages between Dart and Swift, and packaging considerations.

Setup Flutter Module

Start by creating a Flutter module that contains the Dart UI and business logic you want to embed. From your terminal:

flutter create --template module my_flutter

This generates a module with lib/, pubspec.yaml and tooling that supports add-to-app workflows. Develop your UI as usual in lib/main.dart and expose a Widget that you will present from the host app.

A minimal Dart entrypoint looks like this:

// lib/main.dart
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  const channel = MethodChannel('com.example/native');
  channel.setMethodCallHandler((call) async {
    if (call.method == 'getPlatformVersion') return 'Flutter on macOS';
    return null;
  });
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) => const MaterialApp(home: Center(child: Text('Hello from Flutter')));
}

After you develop the module, build the Flutter macOS artifacts that the host app will use. From the module directory, run flutter build macos to produce a macos/ build and necessary engine artifacts. You will copy or reference these artifacts from your host project.

Integrate Flutter Engine In Swift macOS App

On the macOS side, you need to include the Flutter macOS frameworks (FlutterMacOS.framework, App.framework, etc.) and ensure your project links them. The official add-to-app docs describe options: include frameworks manually, use a script to copy Flutter artifacts, or embed them via an Xcode subproject. The core runtime object is FlutterEngine (or FlutterDartProject for custom entrypoints) and the UI object is FlutterViewController.

In Swift, import the Flutter macOS API and create a FlutterEngine. Start the engine with the correct entrypoint (default is main) and attach a FlutterViewController as a child view controller:

import Cocoa import FlutterMacOS

class ViewController: NSViewController { var flutterEngine: FlutterEngine!

override func viewDidLoad() {

super.viewDidLoad()

flutterEngine = FlutterEngine(name: "my_engine")

flutterEngine.run()

let flutterVC = FlutterViewController(engine: flutterEngine, nibName: nil, bundle: nil)
addChild(flutterVC)
flutterVC.view.frame = view.bounds
view.addSubview(flutterVC.view)

} }

This approaches embeds Flutter as a child view. You can present Flutter in a window, panel, or as a reusable view component in your app’s UI. For multiple Flutter screens, reuse a single engine to save memory and warm start time.

Communicate Between Flutter And Swift

MethodChannel and EventChannel are the primary IPC mechanisms between Dart and native macOS Swift. On the Swift side, create a FlutterMethodChannel using the engine’s binary messenger and set a method call handler. Keep naming consistent between Dart and Swift.

Swift example (in viewDidLoad after creating flutterEngine):

let channel = FlutterMethodChannel(name: "com.example/native", binaryMessenger: flutterEngine.binaryMessenger) 
channel.setMethodCallHandler { call, result in
  switch call.method {
  case "getSystemInfo":
    result("macOS " + ProcessInfo.processInfo.operatingSystemVersionString)
  default:
    result(FlutterMethodNotImplemented)
  }
 }

On the Dart side you call MethodChannel('com.example/native').invokeMethod('getSystemInfo') and await the string result. For stream-style updates (like system events), use EventChannel on both sides.

Packaging And Performance

When shipping an app, you must include the Flutter frameworks and your Flutter module’s assets in the final macOS bundle. The build step flutter build macos in the module helps produce the frameworks and App.framework containing compiled Dart AOT code. Copy these into your app target and ensure they are code signed and embedded correctly for distribution.

Performance tips:

• Reuse a single FlutterEngine when possible to avoid Dart VM startup overhead.

• Use platform channels sparingly for high-frequency events; prefer EventChannel or share data via a lightweight shared layer.

• Keep Flutter UI widgets efficient (avoid large build costs) and profile using Flutter’s DevTools even for desktop targets.

Testing and debugging: run the host app in Xcode while keeping your Flutter module in debug mode. Attach DevTools to the Dart VM by enabling observatory ports during development.

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

Embedding Flutter UI in a native macOS Swift project is a powerful strategy to bring modern Flutter interfaces to desktop while preserving existing native code and macOS integrations. Key steps are creating a Flutter module, configuring the macOS project to include Flutter frameworks, instantiating a FlutterEngine and FlutterViewController in Swift, and wiring communication with MethodChannel/EventChannel. With careful packaging and reuse of engines you can achieve smooth startup and a robust integration that benefits both mobile development teams and desktop applications.