Setting Up the Shorebird SDK

What you'll learn

• Generating the Shorebird SDK feature with API/Impl split
• Running build_prepare before releasing to ensure correct dependency swapping
• Creating releases and pushing Dart-only patches without a full store submission
• Configuring update strategies and custom prompt copy at runtime

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Monorepo Toolkit already generated (see Monorepo Toolkit Setup)
• A paid Shorebird account for production releases

Pro Feature

shorebird_sdk is available on the Pro tier and above.

Step 1: Install the Shorebird CLI

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

Restart your terminal, then authenticate:

shorebird login

Step 2: Generate the Shorebird SDK

archipelago generate shorebird_sdk

You will be prompted for:

• shorebirdAppId — leave blank to fill in manually after shorebird init (default: "")
• includeCiPatches — true generates docs/shorebird-ci-patches.md with CI patch instructions

Or use a config file:

{
  "shorebirdAppId": "",
  "includeCiPatches": true
}

archipelago generate shorebird_sdk --config shorebird_config.json

Step 3: Understand the Generated Structure

features/shorebird/
├── shorebird_updater_api/
│   └── lib/src/
│       └── shorebird_updater_sdk.dart   # FeatureSDK contract
└── shorebird_updater_impl/
    └── lib/src/
        ├── shorebird_updater_impl.dart  # Implementation
        ├── di/                          # DI registration
        └── config/
            └── shorebird_config.dart    # Update strategy config

apps/template_app/
└── shorebird.yaml                       # Created by shorebird init (step 4)

Step 4: Initialise Shorebird in the App

cd apps/template_app && shorebird init

This creates shorebird.yaml with your app ID. Commit it:

git add apps/template_app/shorebird.yaml
git commit -m "chore: add shorebird.yaml"

If you left shorebirdAppId blank during generation, open shorebird.yaml and copy the generated app_id value back into your brick config or directly into the DI module.

Step 5: Register the Shorebird Feature

In your shell app's bootstrap.dart:

import 'package:shorebird_updater_impl/shorebird_updater_impl.dart';

FeatureRegistry.register(ShorebirdUpdaterImpl());

Step 6: Create a Release

Always run build_prepare before releasing

Archipelago uses build_prepare to swap impl/noop dependencies per flavor. Releasing without it means Shorebird may sign the wrong binary.

# Switch to release dependencies
melos run build-prepare:release

# Create the release (Android)
shorebird release android --flavor production -- -t lib/main.dart

# Create the release (iOS)
shorebird release ios --flavor production -- -t lib/main.dart

# Restore debug dependencies
melos run build-prepare:debug

Step 7: Push a Dart-Only Patch

When you fix a bug with no native code or asset changes, push a patch instead of a full release:

shorebird patch android --flavor production
shorebird patch ios --flavor production

Patches only cover Dart changes

Native code changes (Kotlin/Swift), new Flutter plugins, or modified assets require a new full release, not a patch.

Step 8: Use the Runtime API

Resolve the updater via GetIt and apply updates:

final updater = getIt<ShorebirdUpdaterSDK>();

// Silent background update (recommended — no user interruption)
await updater.updateNow(UpdateStrategy.silent);

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

Step 9: Configure the Update Strategy

Override defaults by providing a custom ShorebirdConfig in your app module:

@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',
    ),
  );
}

Step 10: CI Integration

Add SHOREBIRD_TOKEN to your repository secrets (generate with shorebird token create), then patch on every merge to main:

- name: Patch Android
  env:
    SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
  run: |
    melos run build-prepare:release
    shorebird patch android --flavor production
    melos run build-prepare:debug

Common Customizations

Customization	Where to Change
Change default update strategy	ShorebirdConfig.defaultStrategy in your app module
Disable launch-time check	Set checkOnLaunch: false in ShorebirdConfig
Custom update dialog	Call updater.checkForUpdate() and handle UpdateAvailable yourself
Multiple flavors	Pass --flavor <name> to both shorebird release and shorebird patch

Next Steps

• Set up Monitoring to track patch adoption rates
• Configure CI/CD to automate patch delivery on merge