From 1e98401a202e3a609144d65c89fb1d705c012428 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Tue, 20 Oct 2026 00:01:28 -0600 Subject: [PATCH 1/3] docs: say add-to-app releases and patches need a prebuilt module The Flutter Concepts add-to-app page only showed the Android source dependency setup, which Shorebird can't release or patch. Split it into a source dependency (development) and a prebuilt AAR (release and patch), and add the Android guide note the iOS guide already has. Co-Authored-By: Claude Opus 5.5 --- .../code-push/guides/add-to-app/android.mdx | 14 ++++++ .../docs/flutter-concepts/add-to-app.mdx | 46 ++++++++++++++++++- 2 files changed, 58 insertions(+), 2 deletions(-) diff --git a/src/content/docs/code-push/guides/add-to-app/android.mdx b/src/content/docs/code-push/guides/add-to-app/android.mdx index ffb21322..ddad73f4 100644 --- a/src/content/docs/code-push/guides/add-to-app/android.mdx +++ b/src/content/docs/code-push/guides/add-to-app/android.mdx @@ -33,6 +33,20 @@ not, see the [Code Push guide](/code-push/initialize) for instructions. The reference code for this guide is available at https://github.com/shorebirdtech/samples/tree/main/add_to_app. +:::note + +Shorebird only supports the prebuilt AAR method of adding Flutter to a native +Android app (see "Depend on the Android Archive (AAR)" in the +[official integration docs](https://docs.flutter.dev/add-to-app/android/project-setup)). +Shorebird does not support depending on the module's source code (the +`include_flutter.groovy` setup) for releases and patches. You can still use a +source dependency during development, but build what you ship with +`shorebird release aar` and patch it with `shorebird patch aar`. There is an +open issue to support source dependencies +([link](https://github.com/shorebirdtech/shorebird/issues/653)). + +::: + ## Add Shorebird to your Flutter module First, run `shorebird init` in your Flutter module: diff --git a/src/content/docs/flutter-concepts/add-to-app.mdx b/src/content/docs/flutter-concepts/add-to-app.mdx index 200cbebd..3573a3b2 100644 --- a/src/content/docs/flutter-concepts/add-to-app.mdx +++ b/src/content/docs/flutter-concepts/add-to-app.mdx @@ -199,8 +199,22 @@ resources are managed internally and do not affect isolation between engines. ### 1. Add the module as a Gradle dependency -Add the Flutter module to your Android project as a source dependency. Both -projects must sit on the same machine. Gradle locates the module at build time: +Flutter offers two ways to add a module to an Android app: as a source +dependency, or as a prebuilt Android Archive (AAR). + +:::caution + +Shorebird only supports the **prebuilt AAR** method for releases and patches. +You can use a source dependency during development, but build the AAR you ship +with `shorebird release aar` and patch it with `shorebird patch aar`. See the +[Code Push for Android add-to-app](/code-push/guides/add-to-app/android/) guide. + +::: + +#### Source dependency (development only) + +Both projects must sit on the same machine. Gradle builds the module from source +along with the host app: ```groovy // settings.gradle (host app) @@ -220,6 +234,34 @@ dependencies { } ``` +#### Prebuilt AAR (release and patch) + +Build the module into a local Maven repository, then depend on it like any other +library. With Shorebird, `shorebird release aar` builds the AAR: + +```bash +shorebird release aar --release-version 1.0.0+1 +``` + +```groovy +// settings.gradle (host app) +dependencyResolutionManagement { + repositories { + google() + mavenCentral() + maven { url '../my_flutter_module/build/host/outputs/repo' } + maven { url 'https://download.shorebird.dev/download.flutter.io' } + } +} +``` + +```groovy +// app/build.gradle +dependencies { + releaseImplementation 'com.example.my_flutter_module:flutter_release:1.0' +} +``` + ### 2. Choose a display mechanism Flutter provides three ways to show Flutter content in an Android app: From 27183b17aecdeb4d58ca750ddb0dfc05c9924e43 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Tue, 20 Oct 2026 00:08:50 -0600 Subject: [PATCH 2/3] docs: address adversarial review on add-to-app prebuilt notes Point the concepts page's prebuilt AAR section at the Android guide instead of duplicating (and getting wrong) its Gradle setup, add the matching iOS caution, say to switch to the AAR before releasing, fix the stale repo-path comment in the Android guide, and tighten wording. Co-Authored-By: Claude Opus 5.5 --- .../code-push/guides/add-to-app/android.mdx | 16 +++--- .../docs/flutter-concepts/add-to-app.mdx | 51 ++++++++----------- 2 files changed, 30 insertions(+), 37 deletions(-) diff --git a/src/content/docs/code-push/guides/add-to-app/android.mdx b/src/content/docs/code-push/guides/add-to-app/android.mdx index ddad73f4..21dd5c60 100644 --- a/src/content/docs/code-push/guides/add-to-app/android.mdx +++ b/src/content/docs/code-push/guides/add-to-app/android.mdx @@ -35,14 +35,14 @@ https://github.com/shorebirdtech/samples/tree/main/add_to_app. :::note -Shorebird only supports the prebuilt AAR method of adding Flutter to a native -Android app (see "Depend on the Android Archive (AAR)" in the +For releases and patches, Shorebird supports only the prebuilt AAR method of +adding Flutter to a native Android app (see "Depend on the Android Archive +(AAR)" in the [official integration docs](https://docs.flutter.dev/add-to-app/android/project-setup)). -Shorebird does not support depending on the module's source code (the -`include_flutter.groovy` setup) for releases and patches. You can still use a -source dependency during development, but build what you ship with -`shorebird release aar` and patch it with `shorebird patch aar`. There is an -open issue to support source dependencies +You can depend on the module's source code (the `include_flutter.groovy` setup) +during development, but switch the host app to the AAR from +`shorebird release aar` before you release, and patch it with +`shorebird patch aar`. There is an open issue to support source dependencies ([link](https://github.com/shorebirdtech/shorebird/issues/653)). ::: @@ -101,7 +101,7 @@ dependencyResolutionManagement { mavenCentral() + maven { + // This is a relative path from this settings.gradle file to the -+ // my_flutter_module/build/host/outputs/repo directory. ++ // my_flutter_module/release directory. + url '../my_flutter_module/release' + } + maven { diff --git a/src/content/docs/flutter-concepts/add-to-app.mdx b/src/content/docs/flutter-concepts/add-to-app.mdx index 3573a3b2..2437f5d7 100644 --- a/src/content/docs/flutter-concepts/add-to-app.mdx +++ b/src/content/docs/flutter-concepts/add-to-app.mdx @@ -204,10 +204,12 @@ dependency, or as a prebuilt Android Archive (AAR). :::caution -Shorebird only supports the **prebuilt AAR** method for releases and patches. -You can use a source dependency during development, but build the AAR you ship -with `shorebird release aar` and patch it with `shorebird patch aar`. See the -[Code Push for Android add-to-app](/code-push/guides/add-to-app/android/) guide. +Shorebird releases and patches only a **prebuilt AAR**. You can use a source +dependency during development, but switch the host app to the AAR built by +`shorebird release aar` before you release, and patch it with +`shorebird patch aar`. The +[Code Push for Android add-to-app](/code-push/guides/add-to-app/android/) guide +walks through the setup. ::: @@ -236,31 +238,13 @@ dependencies { #### Prebuilt AAR (release and patch) -Build the module into a local Maven repository, then depend on it like any other -library. With Shorebird, `shorebird release aar` builds the AAR: - -```bash -shorebird release aar --release-version 1.0.0+1 -``` - -```groovy -// settings.gradle (host app) -dependencyResolutionManagement { - repositories { - google() - mavenCentral() - maven { url '../my_flutter_module/build/host/outputs/repo' } - maven { url 'https://download.shorebird.dev/download.flutter.io' } - } -} -``` - -```groovy -// app/build.gradle -dependencies { - releaseImplementation 'com.example.my_flutter_module:flutter_release:1.0' -} -``` +Build the module into a local Maven repository (`flutter build aar`, or +`shorebird release aar` with Shorebird), then add that repository to the host +app and depend on the AAR like any other library. See Flutter's +[Depend on the Android Archive (AAR)](https://docs.flutter.dev/add-to-app/android/project-setup) +instructions, or the +[Code Push for Android add-to-app](/code-push/guides/add-to-app/android/) guide +for the Shorebird setup. ### 2. Choose a display mechanism @@ -333,6 +317,15 @@ flutter build ios-framework --xcframework --output=../MyFlutterPackage Then add the local package in Xcode: **File > Add Package Dependencies > Add Local**, and point to the generated `MyFlutterPackage` directory. +:::caution + +Shorebird releases and patches only a prebuilt iOS framework built by +`shorebird release ios-framework`. See the +[Code Push for iOS add-to-app](/code-push/guides/add-to-app/ios/) guide for the +setup Shorebird supports. + +::: + ### 2. Display Flutter content #### Full-screen: FlutterViewController From ee76198c7733ac5fe078a1751921cf34658f38cb Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 21 Oct 2026 16:30:06 +0530 Subject: [PATCH 3/3] docs: name the XCFrameworks in the iOS caution, link the AAR section --- src/content/docs/code-push/guides/add-to-app/android.mdx | 2 +- src/content/docs/flutter-concepts/add-to-app.mdx | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/content/docs/code-push/guides/add-to-app/android.mdx b/src/content/docs/code-push/guides/add-to-app/android.mdx index 21dd5c60..28819488 100644 --- a/src/content/docs/code-push/guides/add-to-app/android.mdx +++ b/src/content/docs/code-push/guides/add-to-app/android.mdx @@ -38,7 +38,7 @@ https://github.com/shorebirdtech/samples/tree/main/add_to_app. For releases and patches, Shorebird supports only the prebuilt AAR method of adding Flutter to a native Android app (see "Depend on the Android Archive (AAR)" in the -[official integration docs](https://docs.flutter.dev/add-to-app/android/project-setup)). +[official integration docs](https://docs.flutter.dev/add-to-app/android/project-setup#depend-on-the-android-archive-aar)). You can depend on the module's source code (the `include_flutter.groovy` setup) during development, but switch the host app to the AAR from `shorebird release aar` before you release, and patch it with diff --git a/src/content/docs/flutter-concepts/add-to-app.mdx b/src/content/docs/flutter-concepts/add-to-app.mdx index 2437f5d7..1a670e64 100644 --- a/src/content/docs/flutter-concepts/add-to-app.mdx +++ b/src/content/docs/flutter-concepts/add-to-app.mdx @@ -241,7 +241,7 @@ dependencies { Build the module into a local Maven repository (`flutter build aar`, or `shorebird release aar` with Shorebird), then add that repository to the host app and depend on the AAR like any other library. See Flutter's -[Depend on the Android Archive (AAR)](https://docs.flutter.dev/add-to-app/android/project-setup) +[Depend on the Android Archive (AAR)](https://docs.flutter.dev/add-to-app/android/project-setup#depend-on-the-android-archive-aar) instructions, or the [Code Push for Android add-to-app](/code-push/guides/add-to-app/android/) guide for the Shorebird setup. @@ -319,8 +319,10 @@ Local**, and point to the generated `MyFlutterPackage` directory. :::caution -Shorebird releases and patches only a prebuilt iOS framework built by -`shorebird release ios-framework`. See the +Shorebird releases and patches only the XCFrameworks that +`shorebird release ios-framework` builds (`App.xcframework` and +`ShorebirdFlutter.xcframework`), embedded directly in your Xcode project. It +does not release or patch the Swift package setup above. See the [Code Push for iOS add-to-app](/code-push/guides/add-to-app/ios/) guide for the setup Shorebird supports.