Skip to content
  • 6 min read

Expo Runtime

Amplify supports building and previewing Expo/React Native mobile applications directly in the browser using the Expo Go runtime inside WebContainers.

Expo in WebContainers

The Expo App starter template provides a complete Expo project that runs inside the WebContainer sandbox. When you select the Expo template, Amplify:

  1. Injects the Expo starter template from Amplytic-Labs/Expo-Starter-Template
  2. Runs npm install on the init terminal (auto-setup)
  3. Starts expo start as a backgrounded process via spawnDetached()
  4. Detects the Expo URL from terminal output
  5. Shows a QR code modal for testing on your physical device
Expo URL detection

The AmplifyShell class watches terminal output for Expo URLs via the regex:

regex
/(exp:\/\/[^\s]+|https?:\/\/[^\s]+\.boltexpo\.dev[^\s]*)/

When a URL is detected, it's stored in the expoUrlAtom Nanostore and displayed in the ExpoQrModal component.

Expo QR Code Preview

Instead of the standard iframe preview, Expo projects show a QR code modal (ExpoQrModal.tsx) that:

  • Displays a QR code with the Expo Go deep link
  • Converts exp:// URLs to Expo Go universal links: https://expo.go/--/to?exp=...
  • Shows an "Open in Expo Go" button on mobile devices
  • Provides the direct URL for manual entry

How to use:

  1. Install Expo Go on your iOS or Android device
  2. Scan the QR code shown in Amplify's preview area
  3. The Expo Go app loads your project and renders it on your device

Expo starter template

Uses the Amplytic-Labs/Expo-Starter-Template GitHub repo with Expo Router support.

WebContainer runtime

Expo dev server runs inside the browser — no local Node.js required.

Expo Router support

The Expo starter template includes Expo Router : a file-based routing system for React Native:

  • File-based navigation : Routes defined by file structure in the app/ directory
  • Deep linking : Automatic deep link support for each route
  • Type-safe navigation : TypeScript support for route params
  • Layouts : Shared layouts with _layout.tsx files

The AI is instructed to use Expo Router conventions when building mobile apps. The mobile-app-development design skill provides detailed guidance for screen navigation, tab bars, and modal presentation.

  • Example Expo Router file structure
    app/
  _layout.tsx       — Root layout with Stack navigator
  index.tsx         — Home screen
  login.tsx         — Login screen
  profile.tsx       — Profile screen
  tabs/
    _layout.tsx     — Tab navigator layout
    home.tsx        — Tab: Home
    settings.tsx    — Tab: Settings

    Each file exports a React component that becomes a route. The _layout.tsx files define the navigation container.

Expo project setup

When you create an Expo project in Amplify:

  1. Template is injected with files from GitHub
  2. runProjectAutoSetup() executes:
    • npm install on the init terminal (waits for completion)
    • npx expo start via spawnDetached() (backgrounded)
  3. The dev server starts and the Expo URL appears
  4. QR modal renders automatically
Template detection

Amplify detects Expo projects via: isExpo = template.tags?.includes('expo') || template.name.toLowerCase().includes('expo'). When an Expo project is detected, the QR code modal replaces the standard iframe preview.

Limitations and considerations

Expo in WebContainers has specific limitations:

LimitationDetail
Expo Go requiredMust install Expo Go app on physical device; no browser preview
No native compilationCannot build standalone .apk/.ipa; Expo Go handles native modules
Limited native APIsOnly APIs available in Expo Go client (no custom native modules)
Performance constraintsWebContainer has memory limits; large Expo projects may struggle
No native binary modulesSame WebContainer limitations apply (no sharp, bcrypt, etc.)
Expo Router onlyBest experience with Expo Router; bare React Native less supported

Learn about the Next.js runtime

Was this page helpful?