Skip to content

Configuration File

shorebird.yaml configures Shorebird for your app. shorebird init creates it in the root of your Flutter project and adds it to the assets in your pubspec.yaml. It holds no secrets, so check it into version control.

app_id: 8c846e87-1461-4b09-8708-170d78331aca
flavors:
  development: 8c846e87-1461-4b09-8708-170d78331aca
  production: 6b6e6631-4fbe-4645-8d9d-d5247656d975
auto_update: false
KeyRequiredDefaultSet it to
app_idYesYour app’s ID. shorebird init writes it.
flavorsNoA flavor name to app ID map, one per flavor.
base_urlNohttps://api.shorebird.devA server that forwards to Shorebird’s API.
auto_updateNotruefalse to check for patches from your code.
patch_verificationNoDepends on Flutter buildstrict or install_only, see below.

Identifies your app to Shorebird. The CLI uses it for every app command run in the project, and your app sends it when it checks for patches. It isn’t a secret.

One app ID per flavor. shorebird init writes this map when your project has flavors, and app_id is the app ID used when you build without --flavor. When you pass --flavor, the build puts that flavor’s app ID in your app, and the CLI uses it for that command. A flavor that isn’t in the map fails with:

This project does not have a flavor named "<flavor>". Pass one of: ... (from "flavors" in shorebird.yaml).

See Flavors for setup.

Where your app sends patch checks and patch events. Set it only to route that traffic through your own domain; see Using a reverse proxy. Leave out the trailing slash.

The CLI also sends its own API requests in this project to base_url, unless the SHOREBIRD_HOSTED_URL environment variable is set.

With true (the default), your app checks for a patch on the stable track in the background at every launch and installs it. With false, it checks only when your code calls checkForUpdate() or update() from package:shorebird_code_push. See Update strategies, including what turning it off means for rollback.

When a signed patch’s signature is checked:

  • install_only: once, when the patch downloads (before the download on recent Flutter builds). Some builds skip it; see install_only skips the check on some builds before you use it.
  • strict: every time your app launches the patch, and on recent Flutter builds also before it downloads.

The default depends on the Flutter build the release is made with: install_only from Shorebird’s Flutter 3.47.9 at revision e2c965f (the default in Shorebird 1.6.138 and newer), strict before it. Read the trade-offs for the exact builds and what each mode costs, and Fallback behavior for how each mode behaves on older Flutter versions. Desktop apps that want protection against changes on disk can set strict; the trade-offs say what it costs at launch.

The CLI accepts only the keys above. Any other key makes the CLI commands that read shorebird.yaml, such as shorebird release, fail with an error like this:

Unrecognized keys: [channel]; supported keys: [app_id, flavors, base_url, auto_update, patch_verification]

Two keys people add that don’t belong here:

  • channel. Which track a device checks is set in your code: pass track: to checkForUpdate() or update() from package:shorebird_code_push. See Subscribing a device to a track.
  • patch_public_key. The build adds the public key for patch signing to the copy of the file in your app. Don’t add it yourself.

shorebird release and shorebird patch bundle a trimmed copy of shorebird.yaml into your app. It holds the app ID for the flavor you built, your base_url, auto_update and patch_verification if you set them, and, for a signed release, the patch signing public key. flavors isn’t in it. Your project’s shorebird.yaml doesn’t change.

Your app reads this copy when it starts, so a change to shorebird.yaml reaches devices only in a new release. A patch can’t change it.