Initialize Shorebird

Note

If you are starting a new project, you can use shorebird create to generate a new Flutter app with Shorebird.

Watch the video: Initialize Shorebird in an existing Flutter project

To configure an existing Flutter project to use Shorebird, use shorebird init at the root of a Flutter project:

shorebird init

This does three things:

1. Tells Shorebird to create a unique app_id for your app. This app_id is how Shorebird identifies your app and knows which updates to send to it. It does not need to be kept secret.
2. Creates a shorebird.yaml file in your project’s root directory. shorebird.yaml contains the app_id mentioned above.
3. Adds the shorebird.yaml to the assets section of your pubspec.yaml file, ensuring shorebird.yaml is bundled with your app’s assets and is available to the Shorebird updater at runtime.

You can safely commit these changes; they will have no effect on your app when not using Shorebird.

Example output for an app named shorebird_test:

$ shorebird init
✓ Initializing gradlew (1.2s)
✓ No product flavors detected. (0.6s)
? How should we refer to this app? (shorebird_test) shorebird_test

🐦 Shorebird initialized successfully!

✅ A shorebird app has been created.
✅ A "shorebird.yaml" has been created.
✅ The "pubspec.yaml" has been updated to include "shorebird.yaml" as an asset.

Reference the following commands to get started:

📦 To create a new release use: "shorebird release".
🚀 To push an update use: "shorebird patch".
👀 To preview a release use: "shorebird preview".

For more information about Shorebird, visit https://shorebird.dev
✓ Shorebird is up-to-date (0.6s)
✓ AndroidManifest.xml files contain INTERNET permission (23ms)
✓ android/app/build.gradle(.kts) does not contain a legacy keepDebugSymbols line for libapp.so (2ms)
✓ Xcode project does not override FLUTTER_ build settings (3ms)
✓ shorebird.yaml found in pubspec.yaml assets (1ms)
✓ Lock files are tracked in source control (41ms)

No issues detected!

Note

You can supply a display name directly via the command line by passing the --display-name flag:

shorebird init --display-name "My App"

Note

If your account belongs to multiple organizations, shorebird init will prompt you to choose one interactively. In non-interactive environments (e.g., CI), you can skip the prompt by passing --org-id:

shorebird init --org-id 42

--org-id needs Shorebird 1.6.128 or newer. On an older CLI, use --organization-id instead, or run shorebird upgrade first.

Run shorebird orgs list to list your organization IDs (shorebird account orgs before 1.6.135).

The generated shorebird.yaml should look similar to:

# This file is used to configure the Shorebird updater used by your application.
# Learn more at https://shorebird.dev
# This file should be checked into version control.

# This is the unique identifier assigned to your app.
# It is used by your app to request the correct patches from Shorebird servers.
app_id: 8c846e87-1461-4b09-8708-170d78331aca

If your application contains flavors, shorebird init will create an app per flavor and shorebird.yaml will include all flavors and their corresponding app_ids:

# This file is used to configure the Shorebird updater used by your application.
# Learn more at https://shorebird.dev
# This file should be checked into version control.

# This is the unique identifier assigned to your app.
# It is used by your app to request the correct patches from Shorebird servers.
app_id: 864ab1b0-ba78-4b15-990a-a63cec35a41b
flavors:
  development: 864ab1b0-ba78-4b15-990a-a63cec35a41b
  production: 6b6e6631-4fbe-4645-8d9d-d5247656d975

Note

The app_id is a required field in every shorebird.yaml. In the case of flavors, app_id will default to the first flavor and will be overwritten at build time to the corresponding flavor’s app_id.

Disabling automatic updates

By default, Shorebird checks for and downloads patches automatically in the background at app launch. To disable this and control updates programmatically (e.g., show a prompt before updating), add auto_update: false to shorebird.yaml:

app_id: 8c846e87-1461-4b09-8708-170d78331aca
auto_update: false

You can then use package:shorebird_code_push to check for updates and trigger them at a time of your choosing. See Update Strategies for examples.

Note

Shorebird Code Push requires the internet permission to be added to your AndroidManifest.xml file (located in android/app/src/main/AndroidManifest.xml). This is required for the app to be able to communicate with the Shorebird servers to download patches.

shorebird init will add this permission if it is not already present.

<manifest ...>
<uses-permission android:name="android.permission.INTERNET" />
...
</manifest>

Caution

If your project already has a shorebird.yaml and no new flavors to add, shorebird init stops with:

A "shorebird.yaml" file already exists and seems up-to-date.

Running shorebird init --force instead creates new apps and writes their IDs to app_id (and flavors), even when the old apps already have releases. The old apps stay in the console, but builds already installed on devices keep checking the old app IDs, so patches you make for the new apps never reach them. If you ran it by mistake and haven’t released since, restore the old shorebird.yaml from version control to keep patching those builds. Otherwise, those users get patches again only after they update from the store to a build you released after re-initializing.

Use --force only on a project that has no releases yet. To add flavors to a project you’ve already released, run shorebird init without --force; see Add Shorebird to the flavors.

Whenever shorebird init writes shorebird.yaml, both with --force and when it adds new flavors, it rewrites the file from its template with only app_id and flavors. Your other settings, such as auto_update, base_url or patch_verification, and your comments are dropped, so check the diff and put them back before you commit.

What’s next

Create a ReleaseBuild and submit your app to Shorebird.

Preview LocallyTest your release on a local device before publishing.