Preview Locally

Once you have created a release, you can preview your release on an Android device, Android emulator, or iOS device using the shorebird preview command.

shorebird preview

This will download the release artifacts for the selected app release version, install the app on the selected device, and start the application.

Tip

shorebird preview can be used on any computer that is configured for Flutter development, not just the computer that was used to create the release. This is useful for verifying releases that were created on a CI/CD server.

Options

Option	Abbreviation	Description
--release-version		The release version to preview (e.g., 1.0.0+1). Defaults to an interactive prompt.
--platform		Target platform to preview: android, ios, macos, linux, or windows.
--device-id	-d	The ID of the device or simulator to preview on. Defaults to an interactive prompt.
--track		The deployment track to preview (e.g., stable, staging). Defaults to stable.
--app-id		The Shorebird app ID. Inferred from shorebird.yaml if not specified.

Android keystore options

When previewing an Android release with a production keystore (instead of a debug key):

Option	Description
--ks	Path to the deployment keystore used to sign the APKs.
--ks-pass	Keystore password, prefixed with pass: (plain text) or file: (path to a file).
--ks-key-pass	Password for the signing key. Can be omitted if identical to the keystore password.
--ks-key-alias	Alias of the signing key to use.

Example (Android with keystore):

shorebird preview \
  --platform android \
  --release-version 1.0.0+1 \
  --ks /path/to/keystore.jks \
  --ks-pass pass:my_keystore_password \
  --ks-key-alias my_key_alias

Hybrid apps

Because Flutter modules (.aars and .xcframeworks, created with shorebird release aar and shorebird release ios-framework, respectively) are embedded in apps that Shorebird does not know about, shorebird preview does not support them.

To test these releases, you can use your normal development flow with the artifacts that Shorebird creates. For example, if you launch your app normally from Xcode or Android Studio with a Release configuration, you will see Shorebird logs in its output. If you have published a patch, it should be downloaded on the first run of your app and visible on subsequent runs.

Previewing patches

You can also use shorebird preview to test patches locally before publishing them to production. This is highly recommended to verify your Dart changes and ensure the update downloads and runs as expected.

To test a patch locally:

1. Create a release (if you haven’t already):

   shorebird release [platform]

2. Run the release on your device:

   shorebird preview

3. Make changes to your Dart code.
4. Publish the patch to a staging track (e.g., staging):

   shorebird patch [platform] --track=staging

5. Run the staging patch on your device:

   shorebird preview --track=staging

6. Trigger the update:
   • On launch, Shorebird checks for patches in the background and downloads them.
   • Close the app completely (kill the process).
   • Relaunch the app. The downloaded patch will now be active, and you should see your changes.

:::tip For programmatic checks or showing custom update prompts, see the Update Strategies guide. :::

What’s next

Create a PatchPush over-the-air updates to your published release.

Staging PatchesValidate patches in a staging environment before promoting to production.