From f028c5727fe52f8961ad963f87057b0071798faa Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 21 Oct 2026 16:45:54 +0530 Subject: [PATCH 1/5] docs: current Flutter iOS add-to-app setup and sample module names --- .../code-push/guides/add-to-app/android.mdx | 2 +- .../docs/code-push/guides/add-to-app/ios.mdx | 17 ++++---- .../docs/flutter-concepts/add-to-app.mdx | 40 ++++++++++++++----- 3 files changed, 39 insertions(+), 20 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 28819488..31e579b2 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 @@ -25,7 +25,7 @@ If your app is a pure Flutter app, follow the This guide assumes you have already have an Android app and a Flutter module. The Android app will be named `android_app` and the Flutter module will be named -`flutter_module`. +`my_flutter_module`. This guide also assumes that you have created a Shorebird account. If you have not, see the [Code Push guide](/code-push/initialize) for instructions. diff --git a/src/content/docs/code-push/guides/add-to-app/ios.mdx b/src/content/docs/code-push/guides/add-to-app/ios.mdx index 16242962..83b3410b 100644 --- a/src/content/docs/code-push/guides/add-to-app/ios.mdx +++ b/src/content/docs/code-push/guides/add-to-app/ios.mdx @@ -29,7 +29,7 @@ If your app is a pure Flutter app, follow the This guide assumes you have already have an iOS app and a Flutter module. The example iOS app will be named `IosCodePushDemo` and the example Flutter module -will be named `flutter_module`. +will be named `my_flutter_module`. This guide also assumes that you have created a Shorebird account. If you have not created a Shorebird account, please see the @@ -41,9 +41,10 @@ https://github.com/shorebirdtech/samples/tree/main/add_to_app. :::note Shorebird only supports the iOS Framework embedding method of adding Flutter to -a native iOS app (see "Use iOS frameworks" in the -[official integration docs](https://docs.flutter.dev/add-to-app/ios/project-setup)). -There is an open issue to support embedding via CocoaPods +a native iOS app (see "Link and Embed frameworks in Xcode" in Flutter's +[legacy integration docs](https://docs.flutter.dev/add-to-app/ios/project-setup-legacy#method-b)). +It doesn't support the Swift Package Manager integration that Flutter recommends +since Flutter 3.44. There is an open issue to support embedding via CocoaPods ([link](https://github.com/shorebirdtech/shorebird/issues/1198)), but given that [Flutter plans to deprecate CocoaPods support](https://github.com/flutter/flutter/issues/168015), it is unlikely that this will be implemented. @@ -99,10 +100,10 @@ requires that your Flutter module be embedded in your iOS app as an :::note -The steps to do this are the same as the -[option B in the official instructions](https://docs.flutter.dev/add-to-app/ios/project-setup#option-b---embed-frameworks-in-xcode), -so in the event of a conflict between the docs here and the official docs, defer -to the official docs. +The steps to do this are the same as Flutter's +[Link and Embed frameworks in Xcode](https://docs.flutter.dev/add-to-app/ios/project-setup-legacy#method-b) +instructions, so in the event of a conflict between the docs here and the +official docs, defer to the official docs. ::: diff --git a/src/content/docs/flutter-concepts/add-to-app.mdx b/src/content/docs/flutter-concepts/add-to-app.mdx index 1a670e64..ae836dda 100644 --- a/src/content/docs/flutter-concepts/add-to-app.mdx +++ b/src/content/docs/flutter-concepts/add-to-app.mdx @@ -306,28 +306,46 @@ different view. An engine can only render into one view at a time. ### 1. Add the module as a dependency -Since Flutter 3.44, the recommended method is **Swift Package Manager (SPM)**. -Run the following command in the Flutter module directory to generate an -XCFramework: - -```bash -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. +Flutter offers two ways to add a module to an iOS app: as a Swift package, or as +prebuilt XCFrameworks linked and embedded in Xcode. :::caution 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 +does not release or patch a Swift package integration. See the [Code Push for iOS add-to-app](/code-push/guides/add-to-app/ios/) guide for the setup Shorebird supports. ::: +#### Swift package + +Since Flutter 3.44, Flutter recommends **Swift Package Manager (SPM)**. Run the +following command in the Flutter module directory: + +```bash +flutter build swift-package --platform ios +``` + +It generates a `FlutterNativeIntegration` Swift package in +`build/ios/SwiftPackages/`. Add that package to your Xcode project with **Add +Files to "MyApp"...**, then add the build settings and Run Script steps from +Flutter's +[Integrate with Swift Package Manager](https://docs.flutter.dev/add-to-app/ios/project-setup#integrate-with-swiftpm) +instructions. + +#### Prebuilt XCFrameworks (release and patch) + +Build the module into XCFrameworks (`flutter build ios-framework`, or +`shorebird release ios-framework` with Shorebird), then link and embed them in +your app target. See Flutter's +[Link and Embed frameworks in Xcode](https://docs.flutter.dev/add-to-app/ios/project-setup-legacy#method-b) +instructions, or the +[Code Push for iOS add-to-app](/code-push/guides/add-to-app/ios/) guide for the +Shorebird setup. + ### 2. Display Flutter content #### Full-screen: FlutterViewController From ea62ca78f147bab35d31a1cbf53cf77e1f418b72 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 21 Oct 2026 16:49:22 +0530 Subject: [PATCH 2/5] docs: address round 1 review on add-to-app iOS setup --- .../code-push/guides/add-to-app/android.mdx | 6 ++--- .../docs/code-push/guides/add-to-app/ios.mdx | 23 ++++++++++--------- .../docs/flutter-concepts/add-to-app.mdx | 13 ++++++----- 3 files changed, 22 insertions(+), 20 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 31e579b2..ba54dd64 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 @@ -23,9 +23,9 @@ If your app is a pure Flutter app, follow the ## Prerequisites -This guide assumes you have already have an Android app and a Flutter module. -The Android app will be named `android_app` and the Flutter module will be named -`my_flutter_module`. +This guide assumes you already have an Android app and a Flutter module. The +Android app will be named `AndroidAddToAppDemo` and the Flutter module will be +named `my_flutter_module`. This guide also assumes that you have created a Shorebird account. If you have not, see the [Code Push guide](/code-push/initialize) for instructions. diff --git a/src/content/docs/code-push/guides/add-to-app/ios.mdx b/src/content/docs/code-push/guides/add-to-app/ios.mdx index 83b3410b..0906dac6 100644 --- a/src/content/docs/code-push/guides/add-to-app/ios.mdx +++ b/src/content/docs/code-push/guides/add-to-app/ios.mdx @@ -27,9 +27,9 @@ If your app is a pure Flutter app, follow the ## Prerequisites -This guide assumes you have already have an iOS app and a Flutter module. The -example iOS app will be named `IosCodePushDemo` and the example Flutter module -will be named `my_flutter_module`. +This guide assumes you already have an iOS app and a Flutter module. The example +iOS app will be named `IosAddToAppDemo` and the example Flutter module will be +named `my_flutter_module`. This guide also assumes that you have created a Shorebird account. If you have not created a Shorebird account, please see the @@ -43,9 +43,10 @@ https://github.com/shorebirdtech/samples/tree/main/add_to_app. Shorebird only supports the iOS Framework embedding method of adding Flutter to a native iOS app (see "Link and Embed frameworks in Xcode" in Flutter's [legacy integration docs](https://docs.flutter.dev/add-to-app/ios/project-setup-legacy#method-b)). -It doesn't support the Swift Package Manager integration that Flutter recommends -since Flutter 3.44. There is an open issue to support embedding via CocoaPods -([link](https://github.com/shorebirdtech/shorebird/issues/1198)), but given that +It doesn't support the Swift Package Manager integration that Flutter has +recommended since Flutter 3.44. There is an open issue to support embedding via +CocoaPods ([link](https://github.com/shorebirdtech/shorebird/issues/1198)), but +given that [Flutter plans to deprecate CocoaPods support](https://github.com/flutter/flutter/issues/168015), it is unlikely that this will be implemented. @@ -65,7 +66,7 @@ First, package the Flutter module for release. This will produce an `.xcframework` that can be embedded in your iOS app and provides Shorebird with the information it needs to apply patches. -To create a release, run the following the root directory of your Flutter +To create a release, run the following in the root directory of your Flutter module: ```sh @@ -109,8 +110,8 @@ official docs, defer to the official docs. :::note -`ShorebirdFlutter.xcframework` is nearly identically to `Flutter.xcframework` -from Google, but as part of compliance with Apple's signing requirements, the +`ShorebirdFlutter.xcframework` is nearly identical to `Flutter.xcframework` from +Google, but as part of compliance with Apple's signing requirements, the framework has been renamed when applying Shorebird's (legally Code Town, Inc's) digital signature. @@ -131,10 +132,10 @@ In Xcode: Xcode framework search paths -### Embed App.xcframework and Flutter.xcframework in your app +### Embed App.xcframework and ShorebirdFlutter.xcframework in your app In the "General" tab of your app target, add `App.xcframework` and -`ShorebirdFlutter.xcframework` from to the "Frameworks, Libraries, and Embedded +`ShorebirdFlutter.xcframework` to the "Frameworks, Libraries, and Embedded Content" section. Make sure to select "Embed & Sign" for both frameworks. Xcode embed frameworks diff --git a/src/content/docs/flutter-concepts/add-to-app.mdx b/src/content/docs/flutter-concepts/add-to-app.mdx index ae836dda..01562e20 100644 --- a/src/content/docs/flutter-concepts/add-to-app.mdx +++ b/src/content/docs/flutter-concepts/add-to-app.mdx @@ -306,8 +306,9 @@ different view. An engine can only render into one view at a time. ### 1. Add the module as a dependency -Flutter offers two ways to add a module to an iOS app: as a Swift package, or as -prebuilt XCFrameworks linked and embedded in Xcode. +Flutter recommends adding a module to an iOS app as a Swift package. Its legacy +docs also cover CocoaPods and prebuilt XCFrameworks linked and embedded in +Xcode. :::caution @@ -330,11 +331,11 @@ flutter build swift-package --platform ios ``` It generates a `FlutterNativeIntegration` Swift package in -`build/ios/SwiftPackages/`. Add that package to your Xcode project with **Add -Files to "MyApp"...**, then add the build settings and Run Script steps from -Flutter's +`build/ios/SwiftPackages/`. To add it to your app, follow Flutter's [Integrate with Swift Package Manager](https://docs.flutter.dev/add-to-app/ios/project-setup#integrate-with-swiftpm) -instructions. +instructions: add the package to your Xcode project with **Add Files to +"MyApp"...**, add it to your app target, then add the build settings and Run +Script steps. #### Prebuilt XCFrameworks (release and patch) From a65f5d039edb785d66f7648e5a56bade307ba49c Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 21 Oct 2026 16:52:18 +0530 Subject: [PATCH 3/5] docs: state the SPM recommendation once in the iOS section --- src/content/docs/flutter-concepts/add-to-app.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/content/docs/flutter-concepts/add-to-app.mdx b/src/content/docs/flutter-concepts/add-to-app.mdx index 01562e20..e2935085 100644 --- a/src/content/docs/flutter-concepts/add-to-app.mdx +++ b/src/content/docs/flutter-concepts/add-to-app.mdx @@ -306,9 +306,9 @@ different view. An engine can only render into one view at a time. ### 1. Add the module as a dependency -Flutter recommends adding a module to an iOS app as a Swift package. Its legacy -docs also cover CocoaPods and prebuilt XCFrameworks linked and embedded in -Xcode. +Since Flutter 3.44, Flutter recommends adding a module to an iOS app as a Swift +package with **Swift Package Manager (SPM)**. Its legacy docs also cover +CocoaPods and prebuilt XCFrameworks linked and embedded in Xcode. :::caution @@ -323,8 +323,7 @@ setup Shorebird supports. #### Swift package -Since Flutter 3.44, Flutter recommends **Swift Package Manager (SPM)**. Run the -following command in the Flutter module directory: +Run the following command in the Flutter module directory: ```bash flutter build swift-package --platform ios From b4f798c077a84fd79575ff840c51fe3e36607490 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 21 Oct 2026 16:57:34 +0530 Subject: [PATCH 4/5] docs: the Android sample app is AddToAppDemo --- src/content/docs/code-push/guides/add-to-app/android.mdx | 4 ++-- 1 file changed, 2 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 ba54dd64..483202fc 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 @@ -24,8 +24,8 @@ If your app is a pure Flutter app, follow the ## Prerequisites This guide assumes you already have an Android app and a Flutter module. The -Android app will be named `AndroidAddToAppDemo` and the Flutter module will be -named `my_flutter_module`. +Android app will be named `AddToAppDemo` (in the sample's `AndroidAddToAppDemo` +directory) and the Flutter module will be named `my_flutter_module`. This guide also assumes that you have created a Shorebird account. If you have not, see the [Code Push guide](/code-push/initialize) for instructions. From b217a02e9f4cd965ac370a98a189c746a1b0a752 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 21 Oct 2026 17:00:04 +0530 Subject: [PATCH 5/5] docs: has recommended, matching the iOS guide --- src/content/docs/flutter-concepts/add-to-app.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/flutter-concepts/add-to-app.mdx b/src/content/docs/flutter-concepts/add-to-app.mdx index e2935085..ec7893c6 100644 --- a/src/content/docs/flutter-concepts/add-to-app.mdx +++ b/src/content/docs/flutter-concepts/add-to-app.mdx @@ -306,8 +306,8 @@ different view. An engine can only render into one view at a time. ### 1. Add the module as a dependency -Since Flutter 3.44, Flutter recommends adding a module to an iOS app as a Swift -package with **Swift Package Manager (SPM)**. Its legacy docs also cover +Since Flutter 3.44, Flutter has recommended adding a module to an iOS app as a +Swift package with **Swift Package Manager (SPM)**. Its legacy docs also cover CocoaPods and prebuilt XCFrameworks linked and embedded in Xcode. :::caution