Getting started

Inlay turns annotated Dart schema classes into type-safe navigation and shared-state APIs for Dart, Swift, and Kotlin. Before you can navigate between screens or share state, three things need to be in place: the right packages, the generated code, and a one-time native initialization. In this page, we will walk through that setup. The Navigation and State management pages cover the features themselves.

Requirements

These are the framework's own floors. The Flutter SDK you build with may require more - Flutter 3.47 raised its iOS minimum to 15, for example - so the effective minimum is whichever is higher.

Pin the Flutter version your module and hosts build with - see Versioning for why and how.

Packages

Inlay is split across a few packages:

Add inlay to your Flutter module's pubspec.yaml. Put inlay_gen (and build_runner) under dev_dependencies, since code generation only runs at build time. Add inlay_compose only if your Android host uses Jetpack Compose:

# pubspec.yaml of your Flutter module
dependencies:
  inlay: ^0.1.1
  inlay_compose: ^0.1.1 # optional - Jetpack Compose only

dev_dependencies:
  inlay_gen: ^0.1.1
  build_runner: ^2.11.0

Code generation

Inlay's type safety comes from code generation. You describe your routes and stores once, as plain annotated Dart classes, and inlay_gen emits matching type-safe classes for Dart, Kotlin, and Swift. There are no hand-written route paths or string keys that could drift out of sync - when a schema changes, the mismatch shows up as a compile error on every platform that uses it.

Schema files work similarly to Pigeon definitions - they are specs only. App code never imports them; it imports the generated output. The annotated classes only describe the shape of your routes and stores to the generator.

import 'package:inlay/inlay.dart';

// A Flutter screen. `:userId` in the path maps to the `userId` field. Keep path
// fields required - the generator doesn't enforce it, and a null path parameter
// would encode as an empty path segment.
// Simple fields (primitives, enums) become optional query parameters; complex
// fields like `badges` travel only in the typed params envelope.
@InlayFlutterRoute('/profile/:userId')
class ProfilePage {
  const ProfilePage({required this.userId, this.badges});

  final String userId;
  final List<UserBadge>? badges; // nested types and enums are supported
}

// A native screen reachable from Flutter, type-safely.
@InlayNativeRoute()
class NativeSettingsPage {
  const NativeSettingsPage({this.source});

  final String? source;
}

class UserBadge {
  const UserBadge({required this.label, required this.level});
  final String label;
  final BadgeLevel level;
}

enum BadgeLevel { bronze, silver, gold }

import 'package:inlay/inlay.dart';

@InlayStore(key: 'user_preferences')
class UserPreferencesStore {
  const UserPreferencesStore({
    @InlayStoreKey() required this.userId, // marks the identifying key
    this.displayName = 'User',
    this.darkMode = false,
    this.tags = const [],
  });

  final String userId;
  final String displayName;
  final bool darkMode;
  final List<String> tags;
}

# Schema inputs (specs only - not imported by app code)
routes: lib/inlay/routes.dart
stores: lib/inlay/stores.dart

# Output target per language. Omit kotlin or swift to skip that language.
# Dart is always generated; under build_runner it defaults to lib/src/generated/.
dart:
  output: lib/src/generated/

kotlin:
  output: android/src/main/kotlin/com/example/app/generated/
  package: com.example.app.generated # required for Kotlin

swift:
  output: ios/Classes/Generated/

dart run build_runner build
# or, while iterating on schemas:
dart run build_runner watch

dart run inlay_gen:inlay_gen --config inlay.yaml

What gets generated

From the schema above, the generator emits one file per language pair, each with the same types so the boundary stays in sync:

App code imports the Dart output (import 'package:my_module/src/generated/routes.g.dart';), and your native host uses the generated Kotlin/Swift types directly. Remember to treat all *.g.* files as generated code - don't edit them by hand, re-run the generator instead.

Native initialization

Call the framework's init once at app startup. It creates the shared FlutterEngineGroup and registers your handler for Flutter → native routes. Both entry points accept an optional prewarm parameter (default true).

// AppDelegate
import FlutterPluginRegistrant

// Register plugins on every engine Inlay creates - set before start()
// so the prewarmed engine is covered too.
InlayNavigator.shared.setOnEngineCreated { engine in
    GeneratedPluginRegistrant.register(with: engine)
}
InlayNavigator.shared.start() // prewarm: true by default
InlayNavigator.shared.setNativeRouteHandler(MyNativeRouteHandler())

Dart entrypoint

Every Flutter engine the framework spins up runs the same Dart entrypoint - inlayMain by default. At a minimum it has to initialize the Flutter binding and the shared storage layer before runApp:

@pragma('vm:entry-point')
void inlayMain() async {
  WidgetsFlutterBinding.ensureInitialized();
  await KeyValueStorage.instance.init();

  // ... resolve the initial route and runApp(...)
  // (see the Navigation page for router wiring)
}

To use a different top-level function (for example, to keep several add-to-app entrypoints in one module), point the framework at it at startup. If the hidden prewarmed engine already exists, it is recreated with the new entrypoint, while engines that are already running keep theirs.

InlayNavigator.shared.setDartEntrypoint("myOtherMain")

How you turn the initial route into a widget depends on whether you use a declarative router (go_router, auto_route) or imperative pattern matching - both are covered in Flutter router integration.

Engine prewarming

By default the framework keeps one hidden prewarmed engine, so the first Flutter navigation doesn't have to pay the engine startup cost. You can disable it or tear it down explicitly:

InlayNavigator.shared.setPrewarmEnabled(false)
InlayNavigator.shared.destroyPrewarmedEngine()