Skip to content

Release a module once for every host app

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.

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

shorebird release aar --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:

shorebird patch aar --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: 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.

Each host app embeds a module build from a module release’s release directory, as the Android and 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 does. Store builds keep checking stable.

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.

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.

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.