---
title: "Release a module once for every host app"
description: "Give your Flutter module its own release version, so one release and its patches reach every host app, and every host app version, that embeds it."
---

A Flutter module’s release version is the module’s own version. You pick it when you release the module, and devices report it from whatever host app runs that build of the module. One `shorebird release aar` or `shorebird release ios-framework`, and the patches you make to it, reach every host app that embeds that build, at every host app version:

* A host app can bump its version or ship a new store release without a new module release, and its users keep getting your patches.
* A module embedded in several host apps is released once and patched once.

This needs Shorebird 1.6.142 or newer with Flutter 3.47.9 or newer. Patch these releases with Shorebird 1.6.142 or newer too: an older Shorebird sees the `release_version` built into the module’s `shorebird.yaml` as a changed asset, and stops in CI. For modules built on older versions, see [Modules built on older versions](#modules-built-on-older-versions).

## Pick a release version

Pass the module’s version as `--release-version` when you release it:

* Android

  Android

  ```
  shorebird release aar --release-version 2.4.0+1
  ```

* iOS

  iOS

  ```
  shorebird release ios-framework --release-version 2.4.0+1
  ```

- Each module build needs a release version that platform hasn’t used yet, as with any release. An Android and an iOS build can share one, as above, if they’re built with the same Flutter version.
- It doesn’t depend on the host app’s version. Any scheme works, such as the `version` in your module’s `pubspec.yaml` or a CI build number. Use ASCII letters, digits, `.`, `_`, `+` and `-`, up to 128 characters. While devices still run host app builds that embed a module built on older versions, pick versions that can’t equal one of those host app versions, for example with a prefix such as `m2.4.0+1`: those devices report the host app’s version, so they’d be offered this release’s patches, which can’t install on their build.
- On Android, `--build-number` sets only the version of the `aar` in its Maven repository, which the host app’s `build.gradle` names. It never reaches devices. Pass the same `--build-number` to `shorebird patch aar` as to the release. If you publish the `aar` to Maven, you may want it to match the release version.

Patch a release with the same release version:

* Android

  Android

  ```
  shorebird patch aar --release-version 2.4.0+1 --track=stable
  ```

* iOS

  iOS

  ```
  shorebird patch ios-framework --release-version 2.4.0+1 --track=stable
  ```

To check that a module carries its own version, look at the patch check line in the [device logs](/code-push/device-logs/): `release_version` is the module’s version, and `host_version` shows the host app’s when they differ. If you released with a version that differs from the host app’s and the line still shows the host app’s version as `release_version`, with no `host_version`, the host app isn’t running a module build made with Shorebird 1.6.142 and Flutter 3.47.9 or newer; see [Modules built on older versions](#modules-built-on-older-versions).

## Which host apps get a patch

Each host app embeds a module build from a module release’s `release` directory, as the [Android](/code-push/guides/add-to-app/android/) and [iOS](/code-push/guides/add-to-app/ios/) guides describe. A host app gets the patches of the module release it embeds:

* When you release a new module build, a host app gets that release’s patches once it ships the new build. A host app that still ships an older build gets only the older release’s patches. To fix a bug in both, patch both releases.
* A patch reaches every host app that embeds the release and checks the patch’s track, and a rollback reaches all of them: Shorebird doesn’t choose patches by host app. To try a patch in one host app first, give that host app’s QA build its own track, as [QA builds](/code-push/guides/add-to-app/qa-builds/) does. Store builds keep checking `stable`.

## Your existing CI keeps working

If your CI passes the host app’s version as `--release-version`, as older versions required, it keeps working:

* `shorebird release` builds with the Flutter version your Shorebird version pins unless you pass `--flutter-version`, so upgrading Shorebird to 1.6.142 also builds the module with Flutter 3.47.9. Devices then report the release version you passed, which still equals the host app’s version, so they get the same patches as before, as long as each host app embeds the module build released for it. To give the module its own versions, pass one at your next module release.
* If you build with an older Flutter through `--flutter-version` (a version, `system` or `fvm`), or with the `flutter-version` input of the `shorebird-release` GitHub Action, the module can’t carry its own version, and devices report the host app’s version as before.

Three cases need a change:

* If a host app build embeds a module build from a different release (an earlier one, or one released under another host app’s version, such as the latest `aar` both host apps pull from Maven), its devices report that release’s version and get only its patches. Build each host app from the `release` directory of the module release made for it, or release the module once for all of them and patch that release.
* Shorebird 1.6.142 and newer accept a module’s `--release-version` only if it uses ASCII letters, digits, `.`, `_`, `+` and `-`, up to 128 characters. If the host app’s version uses anything else, such as a space in `versionName`, pass a module version of your own instead, and build the module with Flutter 3.47.9 or newer: a module built with an older Flutter reports the host app’s version, so a version of your own gets no patches.
* Patch with Shorebird 1.6.142 or newer too. A patch job on an older Shorebird sees the `release_version` the release built into `shorebird.yaml` as a changed asset, and stops in CI.

## Modules built on older versions

A module built with Shorebird older than 1.6.142 or Flutter older than 3.47.9 can’t carry its own version. Devices report the host app’s version instead, so `--release-version` must equal it:

* Android: `versionName+versionCode` from the host app’s `app/build.gradle`.
* iOS: `CFBundleShortVersionString+CFBundleVersion` from the host app’s `Info.plist`.

Each new host app version then needs a new module release before its users get patches.

Shorebird 1.6.142 and newer accept a module’s `--release-version` only if it uses ASCII letters, digits, `.`, `_`, `+` and `-`, up to 128 characters, so the host app’s version has to fit that rule too.

## What devices send

Besides the module’s release version, Android and iOS releases built with Flutter 3.47.9 or newer send the host app’s package name or bundle ID, as `host_bundle_id`, with each patch check and patch event. A module whose release version differs from the host app’s version also sends the host app’s version, as `host_version`. See [What Shorebird Collects](/system/what-shorebird-collects/#patch-checks).
