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.
| Key | Required | Default | Set it to |
|---|---|---|---|
app_id | Yes | Your app’s ID. shorebird init writes it. | |
flavors | No | A flavor name to app ID map, one per flavor. | |
base_url | No | https://api.shorebird.dev | A server that forwards to Shorebird’s API. |
auto_update | No | true | false to check for patches from your code. |
patch_verification | No | Depends on Flutter build | strict or install_only, see below. |
app_id
Section titled “app_id”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.
flavors
Section titled “flavors”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:
See Flavors for setup.
base_url
Section titled “base_url”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.
auto_update
Section titled “auto_update”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.
patch_verification
Section titled “patch_verification”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.
Keys you can’t set
Section titled “Keys you can’t set”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:
Two keys people add that don’t belong here:
channel. Which track a device checks is set in your code: passtrack:tocheckForUpdate()orupdate()frompackage: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.
What ends up in your app
Section titled “What ends up in your app”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.