Skip to content

docs: add FAQ about iOS Simulator not being supported #527

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
eseidel wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

docs: add FAQ about iOS Simulator not being supported #527

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
22f0777
docs: add caution about optional applicationIdSuffix in Android flavo…
eseidel Apr 1, 2026
48ccba2
docs: add FAQ entry about iOS Simulator not being supported
eseidel Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions src/content/docs/code-push/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,17 @@ the latest version from the server if needed.
If you have a use case for code push with Fluter web, we'd
[love to know](mailto:contact@shorebird.dev)!

### Does Shorebird work on the iOS Simulator?

No. Shorebird's code push does not work on the iOS Simulator. On physical iOS
devices, Shorebird uses a custom ARM interpreter to run patched Dart code. The
iOS Simulator runs on your Mac's native architecture (x86_64 or Apple Silicon),
which is fundamentally different from the ARM environment on real iOS devices.
Because the patching mechanism is built specifically for the iOS device runtime,
it cannot function in the simulator.

To test patches on iOS, you will need to use a physical iOS device.

## Technical Details

### What does the Shorebird updater store on disk?
Expand Down
8 changes: 8 additions & 0 deletions src/content/docs/code-push/guides/flavors/android.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,14 @@ buildTypes {
</TabItem>
</Tabs>

:::caution

The `applicationIdSuffix` property is optional. If you use services that depend
on a consistent package name (e.g., Firebase), removing `applicationIdSuffix`
may be necessary to avoid configuration issues.

:::

Lastly, edit `android/app/src/main/AndroidManifest.xml` to use the
`applicationLabel` so that we can differentiate the two apps easily:

Expand Down
Loading