Expo EAS Simulator: Bug to Verified PR

This article explains the full journey of a bug report through to a verified pull request that fixes bugs encountered when using Expo’s EAS (Expo Application Services) with the iOS Simulator or Android Emulator. You will learn the exact steps, common pitfalls, and how to verify a fix locally before submitting a PR.

Background: EAS and Local Simulators

Expo Application Services (EAS) is a cloud-based suite for building, submitting, and updating React Native and Expo apps. While EAS Build compiles your project in the cloud, developers often run the resulting app locally on a simulator or emulator to test it quickly. Bugs arise because EAS builds are optimized for physical devices and production, not for the simulator environment. Common issues include missing simulator architectures (x86_64 vs arm64), incorrect bundle identifiers, or problems with the expo-dev-client when connecting to a local development server.

How a Bug Report Should Be Structured

A good bug report for an EAS simulator issue includes the following elements:

• Environment details: macOS version, Xcode version, Android Studio version, Node.js version, and the exact EAS CLI version (eas --version).
• Reproduction steps: The exact commands you run, such as eas build --profile development --platform ios followed by eas build:run.
• Expected vs actual behavior: What you expected to happen (app launches in simulator) versus what actually happened (app crashes, white screen, or error message).
• Logs: The full console output from the build and the simulator, including any stack traces.
• Project configuration: The relevant parts of app.json, eas.json, and package.json.

This structure helps maintainers reproduce the issue quickly and is the first step toward a verified fix.

Reproducing the Bug Locally

Before writing a fix, you must reproduce the bug on your own machine. For an EAS simulator bug, this usually means:

1. Build the app with EAS for the simulator platform: eas build --profile development --platform ios --local (or android).
2. Install the resulting build artifact on the simulator using eas build:run or by dragging the .app or .apk onto the simulator.
3. Observe the failure. Note whether it happens on a fresh install or only after a reload.
4. Check the simulator system log (xcrun simctl spawn booted log stream for iOS, adb logcat for Android) for errors.

If you cannot reproduce it locally, the bug report should be marked as such, and you may need to ask the reporter for more details or a minimal reproduction repository.

Common EAS Simulator Bugs and Their Fixes

Several recurring bugs have been reported and fixed in the EAS CLI and related packages. Here are a few examples with the kind of fix a PR would contain:

• Architecture mismatch: On Apple Silicon Macs, the simulator runs x86_64 binaries under Rosetta, but EAS Build may produce an arm64-only binary. A fix might adjust the build script to include both architectures or set the EXPO_ARCH environment variable.
• Development server URL not injected: When using expo-dev-client, the app needs the correct packager URL. A bug might cause the URL to be the production URL instead of http://localhost:8081. The fix would correct how the URL is passed during the build phase.
• Simulator not detected: The EAS CLI sometimes fails to detect that a simulator is booted. This can be fixed by improving the detection logic to check xcrun simctl list devices more reliably.
• Android emulator network issues: The emulator uses 10.0.2.2 to reach the host machine, but EAS might hardcode localhost. A fix would replace it with the correct host IP based on the platform.

Writing and Testing the Pull Request

Once you have identified the root cause and implemented a fix in your local clone of the relevant repository (usually expo/expo or expo/eas-cli), follow these steps:

1. Create a new branch with a descriptive name like fix/simulator-url.
2. Write a test that reproduces the bug. For EAS CLI, this might be a Jest test that mocks the simulator detection module.
3. Run the existing test suite and your new test to ensure nothing breaks.
4. Manually verify the fix by building a test project and running it on a simulator.
5. Commit your changes with a clear message, referencing the original bug report issue number.
6. Push the branch and open a pull request against the main repository.

In the PR description, include the steps to reproduce the original bug, the root cause, and how your fix resolves it. Attach screenshots or logs showing the app running successfully on the simulator after the fix.

Verifying the Fix in CI and on a Fresh Machine

Maintainers will run the project’s continuous integration (CI) on your PR. This typically includes linting, unit tests, and type checking. To ensure your fix is robust, also test it on a clean environment:

• Clone the repository fresh and apply your patch.
• Run npm install and npm test to verify the tests pass.
• Use a simulator that you haven’t used before to confirm the fix works universally.

If the CI passes and the maintainers approve, your PR will be merged. The final step is to verify the fix in a release: the next time EAS CLI or Expo SDK is published, the bug should no longer occur for other developers.

Frequently Asked Questions

How do I run an EAS build on a simulator?

Use the command eas build --profile development --platform ios (or android). After the build completes, run eas build:run and select the simulator you want to install it on. You must have the simulator booted beforehand.

Why does my EAS build crash on the simulator but work on a physical device?

This is often due to architecture differences. Simulators on Apple Silicon run x86_64 binaries through Rosetta, but EAS may produce an arm64-only binary. Check the build logs for the architecture and ensure you are using a profile that includes simulator support (e.g., development profile).

What is the difference between eas build:run and eas build --local?

eas build --local runs the build on your own machine instead of EAS’s cloud servers. eas build:run takes an existing build ID or lets you choose one, then installs it on a connected simulator or device. You can combine them: eas build --local && eas build:run.

How do I get the full logs from a simulator?

For iOS, open the Console app on macOS and select the simulator device, or use xcrun simctl spawn booted log stream in Terminal. For Android, use adb logcat from the Android SDK platform-tools directory.

Can I submit a PR to fix an EAS bug if I don’t have a Mac?

Yes, many EAS CLI bugs are cross-platform. You can test Android emulator fixes on Windows or Linux. For iOS-specific issues, you may need to rely on CI or ask a maintainer to run the simulator tests.

How long does it take for a merged PR to appear in a release?

It varies. EAS CLI publishes new versions frequently (often weekly). Expo SDK releases are tied to the React Native release schedule. Check the CHANGELOG in the repository to see when your fix is included.

Related

• 3D Printer Nozzle: Key Facts & Care
• When to Replace Console? Signs & Lifespan
• How to Capture & Export Rejected Rows in Snowflake