Overview
Code Push is a tool that allows you to update your Flutter app instantly over the air, without going through the store update process. This allows you to directly deploy fixes and new features to your end users’ devices.
Apps built with Shorebird include a modified Flutter engine, which checks for updates to your app’s Dart code on startup. If an update is available, the engine downloads the update. The user will see the update on the next app restart after the update is downloaded.
A typical Code Push workflow looks like this:
- Use the Shorebird CLI to create a new release of your app.
- Distribute that release through the App Store or Google Play.
- Make changes to your app’s Dart code. This could be a bug fix, a new feature, or anything else, and is not limited to your app’s UI – this can include updated Dart dependencies as well.
- Use the Shorebird CLI to create a new patch to the release you created in the first step.
- That’s it! Your users will see the update the next time they restart your app.
A more detailed walkthrough of this process is available in the Getting Started guide.
This section contains a high-level overview of various concepts within Shorebird. Feel free to skip it now and come back later if you need.
Code push, also referred to as “over the air updates” (OTA) is a cloud service enabling Flutter developers to deploy updates to their apps in production. Shorebird currently works on Android and iOS and will eventually work everywhere Flutter works.
”Code Push” is a reference to the name of a deploy feature used by the React Native community from Microsoft and Expo, neither of which support Flutter.
Patching is the process of updating an application’s code without requiring the user to download a new version from the App Store or Play Store. This is done by creating a patch, which is a set of changes to the application’s code that can be applied over-the-air.
Patches can change any Dart code in your application. This includes:
- App code
- Generated code
- Dependencies in
pubspec.yaml, as long as they don’t include native code changes.
This does not include:
- Asset files (images, fonts, etc.), although we have plans to support this in the near future (see https://github.com/shorebirdtech/shorebird/issues/318).
- Native code (e.g. Java/Kotlin on Android or Objective-C/Swift on iOS).
- Flutter engine changes (i.e., you cannot change the Flutter version of your app using Code Push).
An application is what is created by running flutter create [app_name] and corresponds to a listing in the App Store or Play Store.
Each application has a unique app_id that is assigned when you run shorebird init. You can find your application’s id in the shorebird.yaml file at the root of your project.
An application can have zero or more releases.
A release is a specific version of an application, identified by a version and build number (e.g. 1.0.0+1). Although code push works for apps distributed outside of the App Store and Play Store, a release most often corresponds with a specific version of your app that is published to the App Store or Play Store.
A release can have zero or more patches applied to it.
Releases are created by running shorebird release [platform], where platform is android, aar, ios, or macos.
A patch is a change to a specific release, applied as an over-the-air update. For example, a patch could be a bug fix or a new feature. Multiple patches can be published for a given release, although only one patch can be active at a time. Patches are identified by their associated release version and a patch number, which is an auto-incrementing integer.
When your application starts, it checks for available patches and applies the latest one. This patch will be visible the next time your application launches.
Patches are created by running shorebird patch [platform], where platform is android, aar, ios, or macos.
An artifact is the output of a build or patch operation. For example:
shorebird release androidgenerates and uploads several architecture-specificlibapp.sofiles and an Android archive (.aab) file. These are release artifacts.shorebird patch androidgenerates and uploads diff files that capture differences between your Dart code at patch time and the code in the associated release. These are patch artifacts.