flutter_patcher 1.0.0+1

Self-hosted code push for Flutter on Android and iOS. Signed Dart code and asset patches that apply on the next cold start and roll back automatically.

flutter_patcher

English | 简体中文

Open-source, self-hosted over-the-air (OTA) hotfix tool for Flutter (Android & iOS). Ship critical bug fixes directly from your own servers or CDN without waiting for app store reviews.

Features

• Open-Source & Self-Hosted: Fully transparent codebase with zero third-party platform dependencies. Host patches on any server or CDN you control.
• Cross-Platform Patching: Supports both Android and iOS. Patches for either platform can be generated from any supported host OS (e.g., build iOS patches directly on a Linux CI runner).
• Code & Asset Updates: Patch application Dart code, pure-Dart dependencies, images, fonts, and other bundled assets.
• Build-Time Safety Checks: Unsupported changes (such as native code or FFI modifications) are caught and blocked with clear error messages during patch generation—before they ever reach production.
• Automatic Rollback: Automatically reverts to the bundled baseline build if a patch fails on startup.
• Cryptographic Verification: Patches are signed with your private key and verified on-device before loading.

Supported Versions & Requirements

Flutter	Android	iOS
3.47.0 – 3.47.9	✅	✅

Target / Stage	Requirements
Android Device	Android 9 (API 28) or higher, arm64-v8a; on Android 7–8 the app runs as built, without patches
iOS Device	iOS 13 or higher
Build Android Release	Linux x64, Windows x64 or Apple Silicon Mac
Build iOS Release	Apple Silicon Mac (Xcode required)
Generate Patches	Any host above can generate both Android and iOS patches

What Can Be Patched

Change Type	Supported	Notes
App Dart code	✅	UI and business logic
Pure-Dart dependencies	✅	Packages without native code (e.g., dio, intl)
Images, fonts & assets	✅	Adding or modifying assets; deleting assets requires a full app release
Native code, plugins & FFI	❌	Kotlin/Swift/C++, platform plugins, and FFI packages (e.g., mmkv, isar)
Flutter SDK version	❌	Patches must be built with the exact same Flutter version as the baseline build

Quick Start

1. Add dependency & initialize

flutter pub add flutter_patcher

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await FlutterPatcher.init();
  runApp(const MyApp());
}

// Check for updates at an appropriate time, at `url` from flutter_patcher.yaml
final check = await FlutterPatcher.checkUpdate();
if (check.hasUpdate) {
  await FlutterPatcher.applyPatch(check.patch!);
}

2. Initialize keys & build the baseline release

dart run flutter_patcher keys init       # Run once: creates the keys
dart run flutter_patcher build android   # Or `build ios` (on an Apple Silicon Mac)

Publish the artifact generated by build to the app store. This command records the baseline snapshot that all subsequent patches for this release will diff against.

3. Fix bugs, generate & publish a patch

dart run flutter_patcher patch android   # Diff against the baseline and generate a patch
dart run flutter_patcher publish         # Sign and upload to your storage

Local debugging tip: Run dart run flutter_patcher serve during development. Your USB-connected device can pull patches directly from http://127.0.0.1:8686 without setting up a remote server.

See the Getting Started Guide for the full walkthrough.

Caveats

• Activation: Downloaded patches take effect on the next cold start.
• Back Up Your Keys & Baselines: Private keys live outside your project; back them up with keys export. Losing them means you can no longer publish patches for live releases; losing a baseline snapshot means you cannot generate patches for that specific release.
• Store Policies: Some app stores restrict downloading executable code. Verify your distribution channel's policies before deploying.

Documentation

Document	Description
Getting Started	End-to-end guide from integration to applying your first patch
How It Works	Host runtime, baselines, patching strategy, and security model
CLI Reference	Commands, flags, and flutter_patcher.yaml configuration
API Reference	Client-side Dart API reference
Production Deployment Guide	From a local setup to a live app: publish, upload, withdraw, and what you can swap
Advanced Operations	Rotating the publisher key and cleaning up old patches
Crash Protection	Auto-rollback, patch blacklisting, and startup diagnostics
Troubleshooting	Error code reference and resolution guide
FAQ	Version alignment, cold starts, and store compliance

Contributing

Issues and Pull Requests are welcome. Please make sure all checks pass before submitting:

flutter pub get
flutter analyze
flutter test

When modifying native code, please also run the on-device acceptance tests in test/acceptance.

License

MIT