Why I Built an Open-Source Alternative to Shorebird for Flutter Android

#flutter #android #opensource #mobile

Shorebird is a great product. If it fits your team's needs, you should probably just use it.

This post is for the cases where it doesn't.

The Problem

Flutter doesn't officially support hot updates. When a bug ships to production on Android, the only path is to rebuild, re-sign, re-submit, and wait for store review. For teams shipping to multiple Android stores — especially in markets where store review can take days — this is a real operational cost.

Shorebird is currently the most mature solution to this problem. But it makes a few choices that aren't universal:

The backend is closed-source. Patch metadata, user telemetry, and rollout state all go through Shorebird's infrastructure.
It's a paid service, priced per patch install on the team tier and above.
The CDN's primary edges are in the US and EU. For users in Asia, patch fetch latency varies.
Your production runtime depends on a third-party service staying available long-term.

For some teams these are fine tradeoffs. For others — anyone with data-residency requirements, anyone with a long-lived product, anyone whose users are concentrated outside the US/EU, anyone who just wants to own their own infrastructure — they're not.

I wanted an open-source, self-hosted option. There wasn't one I was happy with. So I built flutter_patcher.

How Flutter Android Hot Updates Actually Work

In release mode, Flutter compiles all your Dart code ahead-of-time into libapp.so. This shared object contains the VM snapshot and isolate snapshot. At runtime, Flutter Engine loads it and starts the Dart VM.

This shapes what's possible:

You can't ship Dart source or bytecode the way React Native ships JS bundles. There's no interpreter to feed.
You can only replace libapp.so wholesale. A one-line Dart change requires a full recompile.
The replacement has to happen before Engine loads the lib. Once mmap has run, you're too late.
Snapshot format compatibility is strict. The patched libapp.so must be built with the exact same Flutter SDK version as the installed app.

The actual mechanic is straightforward: intercept the native library load path before Application.onCreate, redirect to a patched libapp.so on disk, let Flutter Engine load that instead.

What makes it production-grade is everything around that:

versionCode binding so a patch can't be applied to the wrong app version
Signature verification (MD5 + optional Ed25519) so a compromised CDN can't push malicious code
Crash rollback so a bad patch doesn't brick your app on the next launch
A bad-patch blacklist so a known-broken patch can't be re-applied even if the server still serves it

These aren't optional features. They're what separates "a hot update plugin" from "a hot update plugin you'd ship to production."

What flutter_patcher Is

An open-source Flutter plugin that does the above. Specifically:

Android-only. iOS App Store policy forbids dynamic code delivery for executable code. This isn't a roadmap item; it's an architectural decision.
Dart-layer only. Native code, assets, and AndroidManifest changes are out of scope. If you need to change those, you ship a new build.
Self-hosted. The plugin talks to your server. Your patch CDN. Your rollout logic. The plugin ships a reference protocol; the backend is yours.

Minimal usage:

dependencies:
  flutter_patcher: ^0.1.2

await FlutterPatcher.checkUpdate(serverUrl: 'https://your-api/check');
await FlutterPatcher.applyPatch();

To make evaluation easy, 0.1.2 ships a local mock server:

dart run flutter_patcher:mock_server

This runs through the full check → download → apply → verify → rollback-on-crash flow without any backend setup. Takes about 5 minutes end to end.

What It Isn't

Honest scope:

Not for iOS. Won't be.
Not for native, asset, or manifest changes. By design.
Not a managed service. You run the server.
Not battle-tested at scale yet. Status is beta. I've validated on a handful of devices; production device-matrix coverage is something the community will have to help build.

If you're a small team that wants someone else to handle the infrastructure, Shorebird is still probably the right answer.

If you have backend capacity and want infrastructure ownership, this might be worth 30 minutes of evaluation.