Shorebird in Flutter (Releases and Patches)

As your Flutter application grows in usage and complexity, the need for efficient update delivery becomes essential. Traditionally, Flutter apps require a full deployment through the App Store or Play Store for any code changes. This poses a delay, especially when addressing critical bugs.

Shorebird provides a solution to this by enabling code patching (hotfixes) without re-submitting to the app stores, reducing turnaround time significantly. This guide covers:

• Shorebird setup and release process

• Publishing hotfix patches

• Enforcing updates using the upgrader package (blocking screen)

• Best practices for production apps

1. What is Shorebird?

Shorebird is a CLI tool and platform that brings CodePush-style hotfixing to Flutter. It allows developers to:

• Release full versions (initial app store build)

• Push patch updates directly to users via OTA (over-the-air) delivery

• Manage versions and rollouts through the Shorebird dashboard

Limitations

• Only Dart code is patchable, no native plugin updates or asset changes

• Not a replacement for full releases in cases involving native dependencies

2. Installing and Configuring Shorebird

Install the Shorebird CLI

Run:

curl https://raw.githubusercontent.com/shorebirdtech/shorebird/main/install.sh -sSf | bash

Add Shorebird to your PATH (permanent via .bashrc or .zshrc):

export PATH="$HOME/.shorebird/bin:$PATH"

Verify installation

shorebird --version

Log in

shorebird login

Initialize in your Flutter project

Inside the Flutter root directory:

shorebird init

This will:

• Add Shorebird SDK to your project

• Modify your pubspec.yaml

• Generate required files

3. Creating a Full Release

Before you can patch, you need a base release:

shorebird release android
# or
shorebird release ios

Shorebird uploads your compiled binary to their servers, marking it as a release version.

4. Creating a Patch (Hotfix)

Make your code changes (only Dart files).

Then run:

shorebird patch android
# or
shorebird patch ios

This uploads a delta patch of just the Dart code changes. Users with the original release will receive this patch on next launch.

5. Shorebird Version Checks in Flutter

Shorebird also provides a way to check the current version and patch state:

import 'package:shorebird_code_push/shorebird_code_push.dart';

final shorebirdCodePush = ShorebirdCodePush();

void checkUpdate() async {
  final isAvailable = await shorebirdCodePush.isNewPatchAvailableForDownload();
  if (isAvailable) {
    await shorebirdCodePush.downloadUpdateIfAvailable();
    await shorebirdCodePush.installUpdateAndRestart();
  }
}

You should run this on app start or from a background isolate, depending on your strategy.

6. Enforcing Updates with the upgrader Package

For critical updates, you might want to force the user to update the app, blocking access to the current version if it's outdated.

Step 1: Add the dependency

dependencies:
  upgrader: ^7.0.0

Step 2: Use it in your main widget

import 'package:upgrader/upgrader.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return UpgradeAlert(
      upgrader: Upgrader(
        showIgnore: false,
        showLater: false,
        canDismissDialog: false,
        dialogStyle: UpgradeDialogStyle.material,
        shouldPopScope: () => false, // blocks back navigation
      ),
      child: MaterialApp(
        title: 'My Flutter App',
        home: HomeScreen(),
      ),
    );
  }
}

Step 3: Configure app version and check sources

The upgrader package can pull version info from:

• Play Store / App Store (default)

• Custom endpoint (for enterprise control)

• Manually via configuration

For Shorebird, combine this with custom logic to check for patch status using shorebirdCodePush.

You can also override version check:

Upgrader().appcastConfig = AppcastConfiguration(
  url: 'https://yourdomain.com/appcast.xml',
  supportedOS: ['android', 'ios'],
);

Or combine Shorebird version + forced upgrade flag in Firestore/Remote Config.

7. Real-World Example: Forced Upgrade After Critical Bug

Suppose version 1.0.0 has a major payment bug.

• You fix the bug in Dart code and push shorebird patch android

• You use Firestore Remote Config or your backend to set a force_update flag

• On app start, check for patch AND flag

if (forceUpdateRequired) {
  showUpgradeScreen();
} else {
  checkUpdate(); // from Shorebird
}

This ensures that users who haven’t received the Shorebird patch yet are blocked and asked to update via the store.

8. Best Practices

9. CI/CD and Automation

You can include Shorebird in your CI workflow:

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: curl https://... | bash # Install Shorebird
      - run: shorebird release android

Or automate patching:

shorebird patch android --release-version=1.0.0+5

Conclusion

Shorebird is a powerful addition to your Flutter toolchain for reducing downtime and increasing development velocity. By combining patch delivery and forced update enforcement (via upgrader), you can respond to production issues in near real-time while maintaining control over the user experience.

It’s highly recommended to establish:

• A version control + release strategy (via Shorebird dashboard)

• A user notification mechanism (Remote Config, upgrader, custom UI)

• Monitoring (Crashlytics, Sentry) to measure patch impact

If you're serious about maintaining production apps with minimal friction, Shorebird + Upgrader is a production-ready stack to consider.

References

1. Shorebird

• Official Website: https://shorebird.dev

• CLI Documentation: https://docs.shorebird.dev/cli

• GitHub Repository: https://github.com/shorebirdtech/shorebird

• Shorebird Code Push SDK: https://pub.dev/packages/shorebird_code_push

2. Upgrader Package

• Pub.dev Page: https://pub.dev/packages/upgrader

• GitHub Repository: https://github.com/larryaasen/upgrader

• Usage Documentation: Available in the package README

3. Firebase Remote Config (Optional Integration)

• Firebase Documentation: https://firebase.google.com/docs/remote-config

• FlutterFire Plugin: https://pub.dev/packages/firebase_remote_config

4. Version Management & CI/CD

• Semantic Versioning: https://semver.org

• GitHub Actions: https://docs.github.com/en/actions

• Flutter CI/CD Documentation: https://docs.flutter.dev/testing/cd

5. Alternative Tools and Resources

If Shorebird does not meet a particular use case, here are some alternatives:

• Native Store Update Prompt: in_app_update

• Asset Downloading and Management: flutter_downloader