auto_interop

A build_runner-based tool that lets Flutter developers consume any native package (npm, CocoaPods/SPM, Gradle) by auto-generating type-safe Dart bindings.

How It Works

auto_interop.yaml     Parsers (TS/Swift/Kotlin)     Unified Type Schema
   (config)        -->      (parse APIs)          -->     (intermediate)
                                                              |
                           Dart Bindings  <--  Code Generators (Dart/Kotlin/Swift/JS)
                         (what you use)

1. Declare which native packages you need in auto_interop.yaml
2. Run dart run build_runner build (or the CLI)
3. Use the generated type-safe Dart bindings

Quick Start

1. Add dependencies

# pubspec.yaml
dependencies:
  auto_interop: ^0.2.0

dev_dependencies:
  auto_interop_generator: ^0.2.0
  build_runner: ^2.4.0

2. Configure native packages

# auto_interop.yaml
native_packages:
  - source: npm
    package: "date-fns"
    version: "^3.6.0"
    imports:
      - "format"
      - "addDays"

  - source: cocoapods
    package: "Alamofire"
    version: "~> 5.9"

  - source: gradle
    package: "com.squareup.okhttp3:okhttp"
    version: "4.12.0"

3. Generate bindings

dart run build_runner build
# or
dart run auto_interop_generator:generate

4. Use the bindings

import 'package:auto_interop/auto_interop.dart';
import 'generated/date_fns.dart';

void main() async {
  await AutoInteropLifecycle.instance.initialize();

  final formatted = await DateFns.format(DateTime.now(), 'yyyy-MM-dd');
  print(formatted); // 2024-01-15
}

Supported Platforms

Source	Language	Platform	Installer
npm	TypeScript/JS	Web	npm install
CocoaPods	Swift	iOS	Podfile
SPM	Swift	iOS	Package.swift
Gradle	Kotlin	Android	build.gradle

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      auto_interop.yaml                       │
│            (declares which native packages to bind)            │
└─────────────────────────┬────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  NPM Parser  │ │  Pod Parser  │ │ Gradle Parser│
   │  (TS .d.ts)  │ │  (Swift)     │ │ (Kotlin)     │
   └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
          │                │                │
          ▼                ▼                ▼
   ┌──────────────────────────────────────────────┐
   │          Unified Type Schema (UTS)            │
   │  (intermediate representation of all APIs)    │
   └──────────────────────┬───────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
   │ Dart Binding │ │ Kotlin/Swift│ │ JS Interop  │
   │ Generator    │ │ Glue Gen    │ │ Generator   │
   └─────────────┘ └─────────────┘ └─────────────┘

CLI Commands

# Generate bindings from auto_interop.yaml
dart run auto_interop_generator:generate

# Pre-warm AST helper caches (avoids delay on first run)
dart run auto_interop_generator:generate setup

# List available pre-built type definitions
dart run auto_interop_generator:generate list

# Add a package to auto_interop.yaml
dart run auto_interop_generator:generate add npm date-fns ^3.0.0

Packages

Package	Description
auto_interop	Runtime library (platform channels, type conversion, error handling)
auto_interop_generator	Code generator (parsers, generators, CLI, build_runner integration)

AST-Based Parsing (v0.2.0)

Parsers use real compiler APIs by default for near-100% accuracy:

• Swift: SwiftSyntax (backward-compatible: Swift 5.9 to 6.2+)
• Kotlin: Kotlin PSI via kotlinc -script
• TypeScript: TypeScript Compiler API via Node.js

Features: extension function folding, overload deduplication, throws/typed throws propagation, mixed Kotlin/Java handling, export default support. Automatic regex fallback when toolchains are unavailable.

Pre-built Type Definitions

The generator ships with pre-built type definitions for popular packages, enabling instant code generation without parsing:

• npm: date-fns, lodash, uuid
• CocoaPods: Alamofire, SDWebImage
• Gradle: OkHttp

Documentation

Full documentation with examples, architecture details, and API reference: flutterplaza.github.io/auto_interop

License

BSD 3-Clause License. See LICENSE for details.