shorebird_sdk Pro

OTA code-push SDK wrapping shorebird_code_push. Generates shorebird_updater_api (contract + sealed result models) and shorebird_updater_impl (ShorebirdUpdater wrapper with injectable DI). Optionally generates CI patch docs.

Version: 1.0.0

Variables

Variable	Type	Default	Description
shorebirdAppId	string	""	Your Shorebird app_id from shorebird init or the dashboard. Leave blank to fill in shorebird.yaml manually.
includeCiPatches	boolean	true	Generate docs/shorebird-ci-patches.md with sample diffs for CI integration.

Usage

Interactive

archipelago generate shorebird_sdk

Non-interactive (CI)

archipelago generate shorebird_sdk --config my_config.json

Generated Structure

apps/
└── template_app/
    └── shorebird.yaml              # Shorebird app config
features/
└── shorebird/
    ├── shorebird_updater_api/      # Contract + sealed result models (no plugin deps)
    │   └── lib/src/
    │       └── models/
    └── shorebird_updater_impl/     # shorebird_code_push wrapper + injectable DI
        └── lib/src/
            └── di/
docs/
└── shorebird-ci-patches.md         # (if includeCiPatches=true)

Setup

1. Install the Shorebird CLI:

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

2. Log in: shorebird login
3. Generate this brick from your workspace root.
4. Initialise Shorebird for your app:

   cd apps/template_app && shorebird init

5. Commit shorebird.yaml to version control.

Build-Prepare Ordering

Always run build-prepare before shorebird release or shorebird patch:

melos run build-prepare:release
shorebird release android --flavor production
melos run build-prepare:debug   # restore for development

Shorebird captures the dependency graph at build time. Running build-prepare first ensures the graph matches what ships to users (noop implementations, stripped debug tools).

Releasing

# Initial release (creates the base release in Shorebird):
shorebird release android --flavor production -- -t lib/main.dart
shorebird release ios --flavor production -- -t lib/main.dart

# Subsequent patches (Dart-only changes):
shorebird patch android --flavor production
shorebird patch ios --flavor production

For non-Dart changes (native code, assets, plugins) you must create a new release — patches only cover Dart code changes.

Runtime API

final updater = getIt<ShorebirdUpdaterSDK>();

// Silent background update (recommended for most apps):
await updater.updateNow(UpdateStrategy.silent);

// Check then prompt:
final result = await updater.checkForUpdate();
if (result is UpdateAvailable) {
  final confirmed = await showMyUpdateDialog(context, result.patchNumber);
  if (confirmed) await updater.downloadUpdate();
}

Configuration

Override ShorebirdConfig in a custom @module class:

@module
abstract class MyAppShorebirdModule {
  @lazySingleton
  ShorebirdConfig get shorebirdConfig => const ShorebirdConfig(
    defaultStrategy: UpdateStrategy.prompt,
    checkOnLaunch: true,
    promptCopy: PromptCopy(
      title: 'New version available',
      body: 'Update now for the latest features.',
      updateButton: 'Update now',
      laterButton: 'Maybe later',
    ),
  );
}

CI Integration

See the generated docs/shorebird-ci-patches.md for ready-to-apply diffs for GitHub Actions and Fastfile. Required CI secret: SHOREBIRD_TOKEN (generate with shorebird token create).

Known Limitations

• Shorebird requires a paid account for production usage (patches to real users). A free tier is available for evaluation with limited monthly active users.
• Web and desktop targets are not supported by Shorebird — isAvailable returns false on those platforms.