Overview

What is Code Push?

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.

How does Code Push work?

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.

When do users see the update?

By default, the Shorebird updater runs on a background thread on startup to prevent blocking app launch. The patch is downloaded in the background while the user is using the app and will be applied on the next launch (meaning users will see the update on their second launch of the app). If you require immediate/mandatory updates, you can trigger checks programmatically using package:shorebird_code_push.

Is my change patchable?

Not all changes can be shipped via a patch. Use this flowchart to decide whether you need to publish a new release to the app stores or if you can push a patch:

flowchart TD
    A["Did you make changes?"] --> B{"Do changes include native code?\n(Java, Kotlin, Swift, Obj-C)"}
    B -- Yes --> C["New Store Release Required\n(Run 'shorebird release')"]
    B -- No --> D{"Do changes include asset updates?\n(Images, fonts, pubspec assets)"}
    D -- Yes --> C
    D -- No --> E["Patchable OTA!\n(Run 'shorebird patch')"]

A typical Code Push workflow looks like this:

1. Use the Shorebird CLI to create a new release of your app.
2. Distribute that release through the App Store or Google Play.
3. 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.
4. Use the Shorebird CLI to create a new patch to the release you created in the first step.
5. That’s it. Your users will see the update the next time they restart your app.

For a quick overview, check out the demo below.

Platform feature support matrix

Below is a summary of feature support status across all Shorebird target platforms:

Feature	Android	iOS	macOS	Windows	Linux
Dart Code Patching (OTA)	✅	✅	✅	✅	✅
Flavors / Custom Targets	✅	✅	✅	✅	✅
Add-to-App (Hybrid Apps)	✅	✅	❌	❌	❌
Code Obfuscation (--obfuscate)	✅	✅	✅	✅	✅
Patch Signing / KMS	✅	✅	✅	✅	✅

Note

Code Obfuscation support on all platforms requires Flutter 3.41.2 or later.

Concepts

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

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 works on Android, iOS, macOS, Linux and Windows.

“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

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.

What types of changes can be included in a patch?

Patches can change any Dart code in your application. This includes:

• App code
• Generated code (including app_localizations if following the recommended Internationalization Approach)
• 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).

Glossary

Application

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.

Note

Applications that use build flavors will have a unique app_id for each flavor.

Release

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, ios, windows, linux or macos.

Patch

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, ios, windows, linux, or macos.

Note

For more information regarding when to create a patch, refer to the FAQs.

Artifact

An artifact is the output of a build or patch operation. For example:

• shorebird release android generates and uploads several architecture-specific libapp.so files and an Android App Bundle (.aab) file. These are release artifacts.
• shorebird patch android generates 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.