---
title: "Overview"
description: "A high-level explanation of what Code Push is and how it works."
---

For a quick overview, check out the demo below.

[Send over the air updates to Flutter app](https://demo.arcade.software/x5ifkvJ8yFZh63hYJF0g?embed\&embed_mobile=tab\&embed_desktop=inline\&show_copy_link=true)

## What is Code Push?

[Section titled “What is Code Push?”](#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?

[Section titled “How does Code Push work?”](#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 your change patchable?

[Section titled “Is your change patchable?”](#is-your-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')"]
```

Patch compliance

Shorebird automatically checks for native code and asset changes before creating a patch. Ensuring the *content* of your Dart changes complies with App Store and Play Store behavioral policies remains your responsibility. See [Store Compliance](/code-push/faq#store-compliance) and [What can’t Shorebird be used for](/code-push/faq#what-cant-shorebird-code-push-be-used-for) for details.

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.

### Platform feature support matrix

[Section titled “Platform feature support matrix”](#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**](/flutter-concepts/add-to-app/) |    ✅    |  ✅  |   ❌   |    ❌    |   ❌   |
| **Code Obfuscation (`--obfuscate`)**            |    ✅    |  ✅  |   ✅   |    ✅    |   ✅   |
| **Patch Signing / KMS**                         |    ✅    |  ✅  |   ✅   |    ✅    |   ✅   |

Note

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

## Concepts

[Section titled “Concepts”](#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

[Section titled “Code Push”](#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](https://appcenter.ms) and [Expo](https://expo.dev), neither of which support Flutter.

### Patching

[Section titled “Patching”](#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?

[Section titled “What types of changes can be included in a patch?”](#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](https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization))
* Dependencies in `pubspec.yaml`, as long as they don’t include native code changes.

This does **not** include:

* Asset files (images, fonts, etc.), although support for this is planned for 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

[Section titled “Glossary”](#glossary)

#### Application

[Section titled “Application”](#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](#release).

Note

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

#### Release

[Section titled “Release”](#release)

A release is a specific version of an [application](#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](#patch) applied to it.

Releases are created by running `shorebird release [platform]`, where `platform` is `android`, `ios`, `windows`, `linux` or `macos`.

`shorebird release` is a drop-in replacement for `flutter build`. It builds your app and uploads the compiled Dart artifacts to Shorebird’s servers. After running this command, you still need to upload the generated artifact (`.aab` for Android, `.ipa` for iOS) to the respective store.

#### Patch

[Section titled “Patch”](#patch)

A patch is a change to a specific [release](#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

There is no limit on the number of patches you can publish. See [Is there a limit to how many patches you can ship?](/code-push/faq#is-there-a-limit-to-how-many-patches-i-can-ship-per-release) for more details.

#### Track

[Section titled “Track”](#track)

A track is a named deployment channel that controls which devices receive a patch. Every app has a built-in `stable` track (the default). Additional tracks such as `staging` or `beta` are created on demand by naming them when publishing a patch, and allow you to validate patches with a subset of devices before promoting them to all users.

For a full explanation, see [Tracks](/code-push/tracks).

#### Artifact

[Section titled “Artifact”](#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**.