Shorebird: Code Push for Flutter Apps

You shipped a bug to production. App Store review takes 1-3 days. Your users are stuck. Shorebird fixes this — it lets you push Dart code updates directly to users' devices, bypassing app store review entirely. Here's how to set it up and use it.

What Shorebird Actually Does

Shorebird replaces the Dart code in your app without going through the App Store or Google Play. It works at the Dart VM level — your app checks for patches on launch, downloads them, and applies them. Users get the fix without downloading a new version from the store.

What it CAN update: All Dart code — business logic, UI, state management, API calls, routing.

What it CANNOT update: Native code (Swift/Kotlin), native plugins, assets, or AndroidManifest.xml/Info.plist changes. If you add a new native dependency, you still need a store release.

Setup

1. Install the Shorebird CLI

# macOS/Linux
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

# Verify installation
shorebird --version

2. Initialize in Your Project

cd your_flutter_app
shorebird init

This creates a shorebird.yaml in your project root:

# shorebird.yaml
app_id: your-unique-app-id

3. Login

shorebird login

That's it. Your project is now Shorebird-enabled.

The Workflow

Step 1: Create a Release

A "release" is your baseline — the version you submit to the app store:

# Build a release for Android
shorebird release android

# Build a release for iOS
shorebird release ios

This produces an AAB (Android) or IPA (iOS) that you submit to the store normally. Shorebird tracks this as a release baseline.

Step 2: Push a Patch

After the release is live and you need to fix something, change your Dart code and push a patch:

# Fix the bug in your Dart code, then:
shorebird patch android

# Or for iOS:
shorebird patch ios

Shorebird diffs your current code against the release baseline and creates a minimal patch. Users get it on next app launch.

Step 3: Verify

Check what's deployed:

# List all releases
shorebird releases list

# List patches for a release
shorebird patches list --release-version 1.0.0

Real-World Example

Let's say your app has a price calculation bug:

// BEFORE (buggy) — shipped in release 1.2.0
double calculateTotal(List<CartItem> items) {
  return items.fold(0, (sum, item) => sum + item.price); // Missing quantity!
}

// AFTER (fixed)
double calculateTotal(List<CartItem> items) {
  return items.fold(0, (sum, item) => sum + item.price * item.quantity);
}

Without Shorebird: fix the code, build, submit to store, wait 1-3 days for review. Users see wrong prices the entire time.

With Shorebird:

# Fix the code, then:
shorebird patch android
shorebird patch ios
# Users get the fix in minutes

How the App Receives Patches

The patching is automatic. On app launch, the Shorebird engine checks for available patches and applies them. No code changes needed in your app — the check happens at the Dart VM level.

The patch download is small (typically 50-200KB) because Shorebird sends only the diff, not the entire app.

Staging & Rollback

Preview Before Deploying

Test a patch before it goes to all users:

# Build a preview patch
shorebird preview

# This gives you a QR code or link to install the patched version
# Test it on your device before deploying to everyone

Rolling Back

Pushed a bad patch? Roll it back:

# List patches
shorebird patches list --release-version 1.2.0

# Delete the bad patch
shorebird patches delete --patch-number 3

Users revert to the previous patch (or the original release if no other patches exist) on next launch.

CI/CD Integration

Add Shorebird to your GitHub Actions workflow:

# .github/workflows/patch.yml
name: Push Patch
on:
  workflow_dispatch:

jobs:
  patch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shorebirdtech/setup-shorebird@v1
        with:
          token: ${{ secrets.SHOREBIRD_TOKEN }}
      - run: shorebird patch android

Now you can push patches from CI with a button click.

Pricing & Limits

Plan	Patch Installs/Month	Price
Free	5,000	$0
Pro	50,000	$20/mo
Team	500,000	$100/mo
Enterprise	Unlimited	Custom

A "patch install" counts when a user downloads and applies a patch. Regular app usage doesn't count.

App Store Compliance

Shorebird is compliant with both Apple and Google's policies. Apple allows "interpreted code" updates as long as you don't change the app's primary purpose. Google's policy is similar. Shorebird is specifically designed to stay within these guidelines.

Key rule: don't use code push to add entirely new features that change your app's category. Use it for bug fixes, performance improvements, and incremental updates.

When to Use Shorebird

Critical bug fixes that can't wait for store review
A/B testing different UI or logic variations
Hotfixes for crashes discovered in production
Iterating fast on user feedback
Compliance updates that need immediate deployment

When NOT to Use Shorebird

Adding new native plugins (requires store release)
Changing app permissions (requires store release)
Major feature additions (better as a proper store release for marketing/visibility)

The Bottom Line

Shorebird adds a safety net to your release process. Ship to the store normally, and when something goes wrong — or you need to iterate fast — push a Dart patch that reaches users in minutes. Setup takes 5 minutes, and the first time you fix a production bug without waiting for store review, you'll wonder how you ever shipped without it.

Shorebird: Revolutionary Code Push for Flutter