How Shorebird Works: Breaking Down Flutter’s Over-the-Air Update Engine

#mobile #tooling #flutter #architecture

When you build a Flutter app today, every single update even small bug fixes requires resubmission to the Play Store or App Store. That process takes time and slows iteration.

Shorebird, built by former Flutter team members, solves that through over-the-air (OTA) updates letting you push new Dart code directly to users’ devices without resubmitting to app stores.

Let’s break down how this magic actually works under the hood.

1. Why OTA Updates Matter

In native Flutter builds, your Dart code is compiled into a native snapshot bundled inside the .apk or .ipa. Once shipped, that code is frozen.
If you fix a bug, users must download a new version through the store.

That’s where OTA updates come in. Instead of replacing the whole binary, Shorebird:
• Delivers incremental patches
• Applies them at runtime
• Executes the updated Dart code dynamically

This unlocks continuous deployment for Flutter just like web apps.

2. The Problem Shorebird Solves

Without Shorebird:
• You wait for app store reviews.
• You can’t easily A/B test features.
• You can’t quickly fix production bugs.

With Shorebird:
• You build once.
• You patch Dart code (not native binaries).
• Your app downloads the patch in the background and runs it instantly.

3. High-Level Architecture

Here’s a conceptual diagram:

4. Technical Breakdown

a. The Patch Process

When you run:

shorebird patch android

The CLI:
1. Rebuilds your Dart code into a new AOT snapshot (compiled Dart → native code).
2. Computes a delta between the old snapshot and the new one.
3. Uploads that delta to the Shorebird Cloud.

This means users don’t redownload your whole app — just the modified code section.

b. The Cloud / Function Layer

Shorebird uses a backend (likely powered by Cloud Functions or a serverless system) to:
• Store patch metadata (app ID, version, patch ID).
• Handle auth & access (only registered apps fetch patches).
• Manage rollouts (e.g., gradual rollout 10%, 50%, 100%).

Example pseudocode for such a Cloud Function:

exports.checkForUpdate = async (req, res) => {
  const { appId, currentVersion } = req.query;

  const patch = await db.getLatestPatch(appId, currentVersion);
  if (!patch) return res.status(204).send(); // No update

  res.status(200).json({
    patchUrl: patch.url,
    version: patch.version,
    checksum: patch.hash,
  });
};

This endpoint is what the app calls to check for updates.

c. The Flutter App (Client) Layer

Inside your Flutter app, a small runtime module (Shorebird SDK) handles:
• Checking for updates (calling the API).
• Downloading and verifying the patch.
• Replacing the local Dart snapshot with the new one.

The SDK handles this safely — if a patch fails validation, it reverts to the previous version.

You could build something similar using:

final response = await http.get(Uri.parse('$baseUrl/checkForUpdate?version=$currentVersion'));

if (response.statusCode == 200) {
  final patch = jsonDecode(response.body);
  await downloadAndApplyPatch(patch['patchUrl']);
}

d. The Update Delivery Mechanism

Once a patch is applied:
1. The new snapshot replaces the old one in the local storage directory.
2. On next app launch, Flutter VM loads the new snapshot instead of the bundled one.
3. The user runs the updated code instantly.

That’s how Shorebird achieves live patching without changing your native code or re-deploying to stores.

Security, Versioning, and Rollbacks

To prevent tampering:
• Each patch is digitally signed.
• Checksums are validated before applying.
• Rollbacks are automatic if a patch crashes, the SDK reverts to the last stable snapshot.

You can imagine a versioning model like:

app_version: 1.0.0
patches:
  - id: 001 (stable)
  - id: 002 (rollback)
  - id: 003 (active)

6. Building Your Own Simplified OTA System

If you want to replicate this concept, here’s what you need:

Frontend
• Store current app version in local storage.
• Add logic to check for patches on launch.

Backend
• Cloud Function endpoint to serve patches.
• Storage bucket (Firebase Storage / S3) for patch files.
• Database for patch metadata.

Patch Delivery
• Generate patch files manually (could even be JSON scripts or Dart updates for testing).
• Securely download and apply them.

7. Limitations & Caveats
• You cannot modify native code (e.g., new plugins, platform channels).
• App Store policies limit what you can update — Shorebird ensures compliance by patching only Dart logic.
• Patches must be backward-compatible with the bundled version.

8. The Future of Flutter Delivery

Shorebird is more than just a tool — it’s a shift in how Flutter apps evolve.
We’re moving toward a world where mobile apps update as fast as web apps.

Soon, tools like Shorebird could integrate:
• Real-time rollback analytics
• Multi-environment staging
• A/B testing with AI-based rollout predictions

And Flutter developers will build with continuous iteration in mind.

Final Thoughts

Shorebird brings the web development agility to mobile.
It’s a huge step for teams that want faster releases, live experimentation, and zero downtime.

Whether you use it directly or try to build something similar, understanding how it works under the hood teaches you one thing: