Loader plugins

The Flitz loader is native code you embed in your own Flutter app. Your app plus the loader is the host: it carries the compiled Dart runtime, the Flutter engine, and every native plugin you use. A bundle (.flitz) is a complete build of your application code, compiled to bytecode by flitz publish. The loader receives a bundle, checks that it fits the host, and runs it in a second Flutter engine inside your process — your app's own UI keeps running underneath.

The loader ships as compiled binaries with no Dart-side surface: a Maven AAR plus a Gradle plugin for Android, and a FlitzLoader.xcframework for iOS (CocoaPods or Swift Package Manager). You add the dependency, write a few lines of platform glue, and your host can open bundles.

What the loader does

Every bundle goes through the same sequence on both platforms:

1. Acquire. A flitz:// link arrives (a QR code a teammate scans on a real device, a link tapped in a browser, or adb), or the loader's built-in QR scanner is opened. See the URL scheme.
2. Validate. The loader unpacks the archive and checks the bundle's platform_dill_hash against the SDK your host was built with, its required_plugins against the plugins your pubspec.yaml declares, and its required_native_assets against the native libraries your host ships. See Compatibility.
3. Run. A second FlutterEngine starts in bytecode mode and runs the bundle in its own Activity (Android) or a full-screen view controller (iOS).
4. Clean up. When the bundle is dismissed, its extracted files are removed.

The loader takes over only when a flitz:// URL is dispatched or you open the scanner programmatically. A normal home-screen launch still runs your own lib/main.dart. Two integration modes are supported:

• Deeplink-only (default): your app is unchanged on launch; flitz:// links open bundles.
• Scanner as the first screen: the QR scanner replaces your own UI as the entry point — useful for a build whose only job is to preview bundles.

There is no Dart API for the loader and no supported way to embed its UI inside your own FlutterActivity / FlutterViewController.

Supported platforms

A debug host rejects every bundle: bytecode runs only on an AOT (profile/release) engine, and the debug engine's AOT guard refuses it before any compatibility check runs. Build the host in profile or release mode.

There is no loader plugin for Linux, macOS, Windows, or web.

Requirements

• The host is built against the Flitz SDK, not stock Flutter. Stock Flutter does not ship the Dynamic-Modules engine the loader needs; the build fails when the SDK marker is missing. Pin the SDK with flitz sdk use — see Getting started.
• Host and bundles share one SDK tag. The bundle's platform_dill_hash must match the SDK the host was built with. A mismatch is reported as platform_dill_hash mismatch when the bundle loads. flitz status reports drift between your pin and your toolchain.
• pubspec.yaml declares every native plugin your bundles call. The host defines the envelope: a bundle can only use plugins and native libraries the host already ships. The available list is derived from .flutter-plugins-dependencies at build time — you never maintain it by hand.
• A physical device. Both loaders are device-only.

Credentials and versions

The plugin binaries live in private package repositories (Maven, CocoaPods, and Swift views of the same repository). Access is handled by the flitz plugins command group — see the CLI reference:

• flitz plugins credentials --write fetches your organization's repository token and stores it in your developer-local credential stores: ~/.gradle/gradle.properties (as the flitzMavenToken property, next to the repository URL) for Gradle, and a machine entry in ~/.netrc for CocoaPods and SwiftPM. These files are machine-local and are never committed; the token is redacted from console output.
• flitz plugins configure prints the recommended loader-plugin version for your pinned SDK, the SDK tag it resolved against, and the repository coordinates. flitz plugins configure --version-only prints just the version string for scripts. It never prints the token and never edits project files.
• flitz plugins skill prints a ready-to-paste prompt for a coding agent with the concrete coordinates and version already substituted into the build-file additions shown in the quickstarts.

The plugin is versioned independently of the SDK. Wherever this section shows <plugin-version> or <maven-repo-url>, substitute the values flitz plugins configure prints — the quickstarts never carry a hard-coded version. Re-run configure after changing your SDK pin.

Platform quickstarts

Reference