From 2e855af9f804b80aa84e71aa445f404f1f2ad1c2 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Fri, 24 Apr 2026 08:46:02 -0700 Subject: [PATCH 1/3] faq: replace stale "<1 MB" engine overhead claim with real numbers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #19. The existing "less than one megabyte" figure in the code-push FAQ never matched reality — Shorebird ships its own Flutter engine build with the patching runtime included, and the actual overhead is in the 1–5 MB range depending on platform and whether you're measuring on-disk or download. Replace the claim with a table of concrete stripped sizes (Shorebird vs. stock Flutter, on-disk and download, iOS and Android) for the current Flutter 3.41.7 engine, plus a note that earlier engines were larger so the numbers get better over time. --- src/content/docs/code-push/faq.mdx | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index d54804e0..68ec1f2f 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -331,10 +331,28 @@ your system should you choose. ### How big of a dependency footprint does this add? -We expect the code push library to add less than one megabyte to Flutter apps. -`flutter build apk --release` vs. `shorebird build apk --release` should give -you a rough idea but keep in mind that many store distributions do also -automatically thin your app for the device that it is being installed on. +Shorebird ships its own build of the Flutter engine with the patching runtime +included, which is where the overhead comes from. The table below compares +Shorebird's engine against stock Flutter for the same engine version, measured +on the stripped binaries that actually ship to users: + +| Platform | Shorebird (on-disk / download) | Flutter (on-disk / download) | Shorebird overhead | +| ------------------- | ------------------------------ | ---------------------------- | ------------------- | +| iOS (arm64) | 13.25 MB / 5.68 MB | 8.58 MB / 3.67 MB | +4.67 MB / +2.01 MB | +| Android (arm64-v8a) | 13.38 MB / 6.40 MB | 10.79 MB / 5.06 MB | +2.58 MB / +1.35 MB | + +"On-disk" is the uncompressed size installed on the device. "Download" is the +approximate size shipped over the store — APKs and IPAs use DEFLATE compression, +which `gzip -9` closely mimics, so the gzipped size is a good proxy for what a +user's device actually pulls down. + +These numbers are for Flutter 3.41.7 (April 2026). Earlier Shorebird engines +were meaningfully larger — iOS overhead alone came down by roughly 2 MB on-disk +in the preceding month — and we continue to shrink the overhead as we optimize. +You can reproduce a rough measurement on your own app by comparing the output of +`flutter build apk --release` against `shorebird build apk --release`. Keep in +mind that app stores thin distributions for the installing device, so the real +number a given user downloads may be smaller. ### When do updates happen? From e7ba24a8726fe1d95cf87dbc57450da0d684d073 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Fri, 24 Apr 2026 08:47:25 -0700 Subject: [PATCH 2/3] =?UTF-8?q?faq:=20drop=20store-thinning=20caveat=20?= =?UTF-8?q?=E2=80=94=20doesn't=20apply=20to=20engine=20binary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/content/docs/code-push/faq.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index 68ec1f2f..823523d7 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -350,9 +350,7 @@ These numbers are for Flutter 3.41.7 (April 2026). Earlier Shorebird engines were meaningfully larger — iOS overhead alone came down by roughly 2 MB on-disk in the preceding month — and we continue to shrink the overhead as we optimize. You can reproduce a rough measurement on your own app by comparing the output of -`flutter build apk --release` against `shorebird build apk --release`. Keep in -mind that app stores thin distributions for the installing device, so the real -number a given user downloads may be smaller. +`flutter build apk --release` against `shorebird build apk --release`. ### When do updates happen? From 461c155d8df8792bfc52a9dd2ded6ce6aa28d103 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Fri, 24 Apr 2026 08:49:03 -0700 Subject: [PATCH 3/3] faq: link engine-overhead tracking issue (shorebird#3715) --- src/content/docs/code-push/faq.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index 823523d7..9e1c4412 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -348,8 +348,10 @@ user's device actually pulls down. These numbers are for Flutter 3.41.7 (April 2026). Earlier Shorebird engines were meaningfully larger — iOS overhead alone came down by roughly 2 MB on-disk -in the preceding month — and we continue to shrink the overhead as we optimize. -You can reproduce a rough measurement on your own app by comparing the output of +in the preceding month — and we continue to shrink the overhead; progress is +tracked in +[shorebird#3715](https://github.com/shorebirdtech/shorebird/issues/3715). You +can reproduce a rough measurement on your own app by comparing the output of `flutter build apk --release` against `shorebird build apk --release`. ### When do updates happen?