Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

Running Your App on Devices

Run an Expo app on a real phone with Expo Go, on iOS and Android simulators, in the browser and in a development build, and understand Metro, Fast Refresh and debugging.

An Expo project is only useful when you can see it. There are several ways to run it, each with trade-offs: Expo Go (instant, limited), development builds (your own native app, fully flexible), simulators/emulators (no phone needed) and web (a browser). Underneath all of them is the same loop: Metro bundles your code and the app loads the bundle from your computer.

All commands here are read-only (they need the real CLI and devices). The live examples model Fast Refresh and the dev-server URL.

How the dev server works

npx expo start launches Metro, the JavaScript bundler. Metro watches your files, turns TypeScript and JSX into a bundle and serves it over HTTP on port 8081. Your phone downloads the bundle, runs it, and keeps a WebSocket open so Metro can say "file X changed".

flowchart LR
  A["Your editor<br/>save a file"] --> B["Metro bundler<br/>(laptop, port 8081)"]
  B -- "bundle over HTTP" --> C["App on phone / simulator"]
  B -- "change event over WebSocket" --> C
  C --> D["Fast Refresh updates screen"]

Metro serves the JavaScript; the app runs it and applies edits live.

The terminal shows a QR code and shortcuts:

Key Action
a open on an Android device or emulator
i open in the iOS simulator (macOS only)
w open in the browser
r reload the app
j open the JavaScript debugger
m toggle the developer menu
s switch between Expo Go and a development build

Option 1: Expo Go on a real phone

Install Expo Go from the App Store or Google Play, make sure your phone and laptop are on the same network, then scan the QR code (the camera app on iOS, the Expo Go app on Android). If your network blocks local traffic, use a tunnel:

Terminal
npx expo start --tunnel

Expo Go is perfect for learning and for projects that only use SDK libraries. Its limits: it contains a fixed set of native modules, so libraries with custom native code will not work, and some features (like push notifications on Android in recent SDKs) need a development build.

Option 2: simulators and emulators

  • iOS Simulator needs macOS and Xcode. Press i.
  • Android Emulator works on Windows, macOS and Linux. Install Android Studio, create a virtual device in the Device Manager, start it, then press a.

Simulators are great for layout checks and quick iteration, but a real device is the only way to test performance, camera, haptics and push notifications accurately.

Option 3: the web

Add the web dependencies once, then press w:

Terminal
npx expo install react-dom react-native-web @expo/metro-runtime

The same components render with DOM elements through React Native for Web. Use the web target for fast checks and for deploying a website (npx expo export --platform web), but test the native result too.

Option 4: a development build

A development build is your own version of Expo Go containing exactly the native modules your project needs, plus the dev tools (menu, Fast Refresh). Create one when Expo Go is not enough:

Terminal
npx expo install expo-dev-client
npx expo run:android      # builds locally and installs on a device/emulator
npx expo run:ios          # macOS only
# or in the cloud:
eas build --profile development --platform android

After the first install you rarely rebuild: you only do it when native dependencies or native config change. Everyday work still uses Metro and Fast Refresh. See Prebuild and Config Plugins for what run:android does.

Which one should I use?

Choose where to run

Expo Go Learning, quick demos
Development build Custom native modules
Simulator Fast layout checks
Web Browser preview

Use a real device before you ship.

1 / 2

Fast Refresh

When you save a file, Metro sends only the changed module. React re-renders the affected components while keeping their state, if the file only exports components. If you edit a file that exports non-components too (constants, helpers used elsewhere), Fast Refresh falls back to re-running the importing modules; state may reset. The stand-in below models a module registry with state-preserving hot swaps.

JS Fast Refresh, modeled

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The dev server URL

The QR code encodes a URL such as exp://192.168.1.20:8081 (Expo Go) or myapp://expo-development-client/?url=http%3A%2F%2F192.168.1.20%3A8081 (development build). The stand-in below parses these shapes to show where the pieces are.

JS Read a dev-server URL

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Debugging

  • Developer menu: shake the device, or press m in the terminal, or Cmd+D / Ctrl+M in a simulator.
  • console.log output appears in the terminal where Metro runs.
  • React Native DevTools: press j to open a Chrome-based debugger with Console, Sources (breakpoints), Network and the React Components/Profiler tabs.
  • Red and yellow boxes: errors and warnings drawn on the screen (LogBox). Fix the first error first; later ones are often consequences.
  • Clear the cache when things seem stuck: npx expo start --clear.

Common problems

  • Phone cannot connect: same Wi-Fi? VPN? Try --tunnel or check the firewall for port 8081.
  • "Unable to resolve module": run npx expo install <package>, then restart with --clear.
  • A library works on the simulator but crashes in Expo Go: it needs native code, so make a development build.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Metro do in an Expo project?

    Metro is the JavaScript bundler and dev server behind Fast Refresh.
  2. 2. When do you need a development build instead of Expo Go?

    Expo Go contains a fixed set of modules; extra native code requires your own build.
  3. 3. What does Fast Refresh try to preserve when you save a component file?

    Fast Refresh swaps the changed code and keeps component state where possible.
  4. 4. Which flag helps when the phone cannot reach your laptop on the local network?

    npx expo start --tunnel routes the connection through a tunnel service.

Summary

  • npx expo start runs Metro; the app downloads the bundle and receives live updates.
  • Run on Expo Go, simulators, the web or a development build; use a real device before shipping.
  • Development builds contain your native modules and are rebuilt only when native things change.
  • Debug with the developer menu, terminal logs and React Native DevTools; clear the cache when stuck.

Next: App Configuration