Patch App #

A lightweight helper to patch your Flutter app at runtime using shorebird_code_push and terminate_restart.

It automatically checks for Shorebird updates, applies patches, and restarts your app safely when accepted.

Features #

• Check and apply Shorebird patches dynamically
• Show a customizable restart confirmation dialog
• Restart the app safely with one line of code
• Built-in minInterval to limit check frequency and prevent redundant checks
• Optional error handling via callback or PatchResult
• Only report PatchResult.restartRequired when the restart dialog is accepted (or cannot be shown), while rejected prompts return PatchResult.cancelled

Setup #

iOS #

Add the following to your Info.plist to enable restarts with terminate_restart:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    </array>
  </dict>
</array>

Android #

No configuration required.

Usage #

class App extends StatefulWidget {
  const App({super.key});

  @override
  State<App> createState() => _AppState();
}

class _AppState extends State<App> {
  final patchApp = PatchApp(
    confirmDialog: (context) => patchAppConfirmationDialog(context),
    onError: (error, stack) => debugPrint('Update failed: $error'),
  );

  @override
  void initState() {
    super.initState();
    patchApp.register(context); // Auto-checks on start & resume
  }

  @override
  void dispose() {
    patchApp.unregister(); // Stops lifecycle listener
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return FilledButton(
      onPressed: () => patchApp.checkAndUpdate(context), // Check and update manually
      child: const Text('Check and Update'),
    );
  }
}

register() and unregister() #

• register(context) Automatically checks for updates when the app starts or resumes. Should be called once in initState().

• unregister() Cleans up the lifecycle listener created by register(). Always call this in dispose().

Patch Results #

enum PatchResult {
  noUpdate,        // No updater or no patch available
  upToDate,        // Already on the latest version
  cancelled,       // Restart prompt dismissed or skipped
  restartRequired, // Patch applied; restart needed
  failed,          // Error during the update
}

cancelled is returned when the confirmation dialog is dismissed, while restartRequired is only emitted after the user accepts a restart (or if the dialog cannot be shown because the context was unmounted), signaling that a restart is still needed.

Tips #

• Always provide an onError callback in production to capture unexpected failures.

  • If onError is provided, the method returns PatchResult.failed on error.
  • If omitted, the error is rethrown.