Use Fast Refresh with Metro on a remote simulator

Create a development build for the simulator

If you cannot create the native build on your computer, add an EAS Build profile with both developmentClient: true and ios.simulator: true:

{
  "build": {
    "development-simulator": {
      "developmentClient": true,
      "ios": {
        "simulator": true
      }
    }
  }
}

Create the build before you start the session:

For Android, run the same command with --platform android. The profile produces an APK.

Start Metro with a tunnel

The remote device must reach Metro over the internet. Start Metro with the Expo tunnel before you start the session, because EAS opens the Metro URL while the session starts:

EXPO_UNSTABLE_TUNNEL_V2=1 selects a tunnel that is signed for your Expo account. It works with an EXPO_TOKEN or a robot user, and it accepts any --port. Use your own free port if another Metro process uses port 8081.

From SDK 58, npx expo start --tunnel uses this tunnel by default and ignores EXPO_UNSTABLE_TUNNEL_V2. You can leave the variable out in an SDK 58 project.

Start the session with the build and the Metro URL

Pass the build ID and the development client URL:

Replace <scheme> with the scheme value from your app config, or with exp+<slug>. expo-dev-client adds the exp+<slug> scheme to a development build. Here, <slug> is the slug from your app config in lowercase, without characters that are not valid in a URL scheme. Do not use the slug without the exp+ prefix. URL-encode the Metro URL when it contains a path or a query.

The launch arguments hide the developer menu onboarding screen and stop the developer menu from opening at launch. Add --launch-arg "-EXDevMenuShowFloatingActionButton" --launch-arg "0" to hide the floating button. These -EXDevMenu* launch arguments work only on iOS. For an Android session, do not pass them.

On SDK 58 and later, you can control the same behavior on both platforms from the URL instead. Add __expo_disable_onboarding=1, __expo_disable_fab=1, and __expo_disable_auto_launch=1 as query parameters of the development client URL. SDK 58 also accepts the <scheme>://?__expo_url=<encoded-public-metro-url> form that npx expo start prints. The expo-development-client/?url= form in the example keeps working, with the legacy disableOnboarding=1, disableFab=1, and disableAutoLaunch=1 parameters placed next to url. See Using launch URLs in automation scenarios.

Attach the controller and confirm

When the start command launches the app, agent-device does not have an open app session yet. Attach to the running app without a relaunch, then take a screenshot:

Edit a source file, then take another screenshot to confirm the change.