Flutter plugin development

Abstract contract)

• my_plugin_example/ (Integration test harness)

Step 2: Define the Platform Interface

The interface must be platform-agnostic and explicitly declare async contracts. Avoid leaking platform types into Dart.

// my_plugin_platform_interface/lib/my_plugin_platform_interface.dart
abstract class MyPluginPlatform extends PlatformInterface {
  static late MyPluginPlatform _instance;
  static MyPluginPlatform get instance => _instance;
  static set instance(MyPluginPlatform instance) {
    PlatformInterface.verifyToken(instance, _token);
    _instance = instance;
  }

  Future<String> fetchDeviceId();
  Stream<double> get sensorStream;
}

Step 3: Generate Bindings with Pigeon

Pigeon replaces manual MethodChannel serialization with compile-time type safety. Define the schema:

// pigeon/schema.dart
import 'package:pigeon/pigeon.dart';

@HostApi()
abstract class DeviceApi {
  String getDeviceId();
  @async
  Future<double> readSensorValue();
}

@FlutterApi()
abstract class SensorStreamApi {
  void onSensorUpdate(double value);
}

Run generation:

flutter pub run pigeon --input pigeon/schema.dart

Pigeon outputs Dart, Kotlin, and Swift bindings with automatic codec handling, null safety enforcement, and async wrapper generation.

Step 4: Implement Platform Logic (Android)

Thread confinement is non-negotiable. Android platform channels must not block the main thread. Use Kotlin coroutines scoped to the plugin lifecycle.

// my_plugin_android/android/src/main/kotlin/com/yourcompany/my_plugin/MyPlugin.kt
class MyPlugin(private val messenger: BinaryMessenger) : DeviceApi {
  private val channel = MethodChannel(messenger, "com.yourcompany.my_plugin")
  private var sensorStreamHandler: EventChannel.StreamHandler? = null
  private var eventSink: EventChannel.EventSink? = null
  private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())

  init {
    DeviceApi.setUp(messenger, this)
    setupSensorStream()
  }

  override fun getDeviceId(): String {
    return Settings.Secure.getString(
      ApplicationProvider.getApplicationContext<Context>().contentResolver,
      Settings.Secure.ANDROID_ID
    )
  }

  override fun readSensorValue(callback: (Result<Double>) -> Unit) {
    scope.launch {
      try {
        val value = readNativeSensor()
        withContext(Dispatchers.Main) {
          callback(AsyncResult.success(value))
        }
      } catch (e: Exception) {
        withContext(Dispatchers.Main) {
          callback(AsyncResult.error("SENSOR_ERROR", e.message, null))
        }
      }
    }
  }

  private fun setupSensorStream() {
    val eventChannel = EventChannel(messenger, "com.yourcompany.my_plugin/sensor")
    sensorStreamHandler = object : EventChannel.StreamHandler {
      override fun onListen(arguments: Any?, events: EventChannel.EventSink?) {
        eventSink = events
        startSensorUpdates()
      }
      override fun onCancel(arguments: Any?) {
        eventSink = null
        stopSensorUpdates()
      }
    }
    eventChannel.setStreamHandler(sensorStreamHandler)
  }

  private fun startSensorUpdates() {
    // Native sensor registration logic
    // Dispatch to eventSink on main thread
  }

  fun detachFromEngine() {
    scope.cancel()
    eventSink?.endOfStream()
  }
}

Step 5: Implement Platform Logic (iOS)

iOS requires explicit main-thread dispatch for UI-bound callbacks and careful lifecycle management.

// my_plugin_ios/ios/Classes/MyPlugin.swift
public class MyPlugin: NSObject, DeviceApi {
  private var sensorSink: FlutterEventSink?
  private let sensorQueue = DispatchQueue(label: "com.yourcompany.my_plugin.sensor")
  
  public static func register(with registrar: FlutterPluginRegistrar) {
    let instance = MyPlugin()
    DeviceApiSetup.setUp(binaryMessenger: registrar.messenger(), api: instance)
    let eventChannel = FlutterEventChannel(name: "com.yourcompany.my_plugin/sensor", binaryMessenger: registrar.messenger())
    eventChannel.setStreamHandler(instance)
  }
  
  public func getDeviceId() throws -> String {
    guard let identifier = UIDevice.current.identifierForVendor?.uuidString else {
      throw FlutterError(code: "NO_ID", message: "Vendor ID unavailable", details: nil)
    }
    return identifier
  }
  
  public func readSensorValue(completion: @escaping (Result<Double, Error>) -> Void) {
    sensorQueue.async {
      do {
        let value = try self.readNativeSensor()
        DispatchQueue.main.async {
          completion(.success(value))
        }
      } catch {
        DispatchQueue.main.async {
          completion(.failure(FlutterError(code: "SENSOR_ERROR", message: error.localizedDescription, details: nil)))
        }
      }
    }
  }
  
  private func readNativeSensor() throws -> Double {
    // CoreMotion or hardware API call
    return 0.0
  }
}

extension MyPlugin: FlutterStreamHandler {
  public func onListen(withArguments arguments: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
    sensorSink = events
    startSensorUpdates()
    return nil
  }
  
  public func onCancel(withArguments arguments: Any?) -> FlutterError? {
    sensorSink = nil
    stopSensorUpdates()
    return nil
  }
}

Step 6: Wire the Dart Implementation

The Dart package implements the platform interface using the generated Pigeon bindings.

// my_plugin/lib/my_plugin.dart
class MyPlugin {
  static final _api = DeviceApi();
  static final _streamApi = SensorStreamApiImpl();
  
  static Future<String> fetchDeviceId() async {
    return await _api.getDeviceId();
  }
  
  static Stream<double> get sensorStream {
    return _streamApi.sensorUpdates;
  }
}

class SensorStreamApiImpl extends SensorStreamApi {
  final _controller = StreamController<double>.broadcast();
  Stream<double> get sensorUpdates => _controller.stream;
  
  @override
  void onSensorUpdate(double value) {
    _controller.add(value);
  }
}

Architecture Rationale

• Pigeon over raw MethodChannel: Eliminates runtime codec errors, enforces null safety, generates platform tests automatically, and reduces boilerplate by 70%.
• Federated structure: Isolates platform code, enables independent CI validation, prevents cross-platform build failures, and simplifies migration to platform views or FFI.
• Explicit threading: Android uses Dispatchers.IO for blocking I/O, iOS uses DispatchQueue for hardware access, and all callbacks route to the main thread to satisfy platform UI constraints.
• Lifecycle awareness: detachFromEngine() and onCancel() prevent memory leaks when the Flutter engine is destroyed or the widget tree is rebuilt.

Pitfall Guide

1. Blocking the Main Thread with Synchronous Platform Calls

Platform channels are synchronous by default. Calling blocking native APIs (file I/O, network requests, hardware polling) on the main thread triggers ANRs on Android and watchdog terminations on iOS. Always offload heavy work to background threads and return results via async callbacks or streams.

2. Ignoring Platform Threading Rules

Dart's single-threaded event loop does not map directly to native concurrency models. Android requires main-thread dispatch for EventSink and UI updates. iOS enforces main-thread execution for FlutterEventSink and UIKit calls. Failing to route callbacks correctly causes crashes or dropped events.

3. Misusing MethodChannel Codec Limits

MethodChannel serializes data using Flutter's standard codec, which supports primitives, lists, maps, and Uint8List. Custom objects, large payloads (>1MB), or circular references cause PlatformException or silent truncation. Use Uint8List for binary data, chunk large transfers, and avoid passing complex Dart objects to native code.

4. Skipping Platform-Specific Unit Tests

Plugins without platform tests regress silently. Android requires JUnit/Kotlin tests for coroutine scope, lifecycle detachment, and error mapping. iOS requires XCTest/Swift tests for thread dispatch, sensor registration, and error propagation. Pigeon generates test scaffolding; use it.

5. Not Handling Plugin Detachment

When the Flutter engine is destroyed or the plugin is removed from the widget tree, native resources must be released. Failing to implement detachFromEngine() (Android) or pluginRegistry cleanup (iOS) leaks memory, leaves sensor listeners active, and causes duplicate event streams on re-initialization.

6. Over-Engineering with Pigeon Prematurely

Pigeon adds build complexity and requires schema maintenance. For simple, low-frequency APIs (e.g., single method calls, static configuration), MethodChannel with manual serialization is faster to implement. Reserve Pigeon for multi-method contracts, streaming data, or cross-team plugin distribution.

7. Hardcoding Platform Checks Without Fallbacks

Using Platform.isAndroid or Platform.isIOS in Dart breaks web/desktop compatibility and complicates testing. Always route platform checks through the platform interface. Provide graceful degradation (e.g., mock streams, fallback values) for unsupported platforms.

Production Bundle

Action Checklist

• Scaffold federated plugin: Generate separate packages for Dart interface, Android, iOS, and example app to enforce isolation.
• Define platform contract: Create an abstract Dart interface with explicit async signatures and stream declarations.
• Generate Pigeon bindings: Write a schema file, run code generation, and verify type-safe Kotlin/Swift outputs.
• Implement threading boundaries: Offload blocking work to background dispatchers, route callbacks to main threads, and validate with StrictMode/XCTest.
• Add lifecycle management: Implement detachFromEngine() and stream cancellation to prevent memory leaks and duplicate events.
• Write platform tests: Validate coroutine scope, error mapping, and thread dispatch using generated test scaffolding.
• Publish with versioning: Use semantic versioning, document breaking changes, and provide platform-specific setup guides.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Low-frequency API calls (e.g., config fetch, device ID)	Direct MethodChannel	Minimal serialization overhead, faster initial implementation	Low
High-frequency sensor streams or real-time data	Pigeon + EventChannel	Compile-time type safety, optimized binary codec, stream lifecycle management	Medium
Complex native object exchange (e.g., camera frames, AR data)	FFI or Platform View	Avoids codec serialization limits, enables zero-copy memory sharing	High
Rapid prototyping or internal tooling	Monolithic plugin with MethodChannel	Reduces package overhead, accelerates iteration	Low
Public distribution or cross-team usage	Federated plugin + Pigeon	Enforces contract stability, enables independent platform testing, simplifies maintenance	Medium

Configuration Template

pubspec.yaml

name: my_plugin
description: A production-ready Flutter plugin with federated architecture.
version: 1.0.0
homepage: https://yourcompany.com

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  plugin_platform_interface: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  pigeon: ^9.0.0
  flutter_lints: ^2.0.0

flutter:
  plugin:
    platforms:
      android:
        package: com.yourcompany.my_plugin
        pluginClass: MyPlugin
      ios:
        pluginClass: MyPlugin

pigeon/schema.dart

import 'package:pigeon/pigeon.dart';

@HostApi()
abstract class DeviceApi {
  String getDeviceId();
  @async
  Future<double> readSensorValue();
}

@FlutterApi()
abstract class SensorStreamApi {
  void onSensorUpdate(double value);
}

my_plugin_platform_interface/lib/my_plugin_platform_interface.dart

import 'package:plugin_platform_interface/plugin_platform_interface.dart';
import 'my_plugin_method_channel.dart';

abstract class MyPluginPlatform extends PlatformInterface {
  static final _token = Object();
  static late MyPluginPlatform _instance = MethodChannelMyPlugin();
  static MyPluginPlatform get instance => _instance;
  static set instance(MyPluginPlatform instance) {
    PlatformInterface.verifyToken(instance, _token);
    _instance = instance;
  }

  Future<String> fetchDeviceId();
  Stream<double> get sensorStream;
}

Quick Start Guide

1. Initialize the project: Run flutter create --template=plugin --platforms=android,ios -a kotlin -i swift --org com.yourcompany my_plugin to scaffold the federated structure.
2. Define the contract: Create pigeon/schema.dart with your API signatures, then run flutter pub run pigeon --input pigeon/schema.dart to generate type-safe bindings.
3. Implement platform logic: Add native code to my_plugin_android and my_plugin_ios, ensuring background threading and main-thread callback routing.
4. Wire the Dart API: Create my_plugin/lib/my_plugin.dart to expose the generated bindings through a clean, async-first interface.
5. Validate locally: Run flutter test for Dart, ./gradlew test for Android, and xcodebuild test for iOS to verify threading, error handling, and stream lifecycle before publishing.