Quick Start

Create and run your first Expo app in 5 minutes

Get your first Expo app running in just a few minutes. This guide will walk you through creating a new project and seeing it on your device or simulator.

This quickstart uses Expo Go, which means you don’t need to install Xcode or Android Studio. For custom native code, see Development Builds.

Prerequisites

Before starting, make sure you have:

• Node.js 18+ installed (nodejs.org)
• A code editor (VS Code recommended)
• A mobile device OR iOS Simulator / Android Emulator

1. Create a new app

   Open your terminal and run:

   npm

   npx create-expo-app my-app
   

   This creates a new Expo project with a working app template. The command will:

   • Create a my-app directory
   • Install all required dependencies
   • Set up the project structure with Expo Router

   What gets created?

   my-app/
   ├── app/
   │   ├── _layout.tsx          # Root layout
   │   ├── index.tsx            # Home screen
   │   └── explore.tsx          # Example screen
   ├── assets/                  # Images, fonts, etc
   ├── components/              # Reusable components
   ├── app.json                # Expo configuration
   ├── package.json            # Dependencies
   └── tsconfig.json           # TypeScript config
   
2. Navigate to project

   Change into your new project directory:

   cd my-app
   
3. Start the development server

   Start the Expo development server:

   npm

   npx expo start
   

   You’ll see a QR code in your terminal and output like this:

   › Metro waiting on exp://192.168.1.100:8081
   › Scan the QR code above with Expo Go (Android) or the Camera app (iOS)
   
   › Press a │ open Android
   › Press i │ open iOS simulator
   › Press w │ open web
   
   › Press r │ reload app
   › Press m │ toggle menu
   

   The development server uses Metro bundler to compile your JavaScript and serve it to your app.

4. Open on your device

   On your phone

   1. Install Expo Go on your device:

      • iOS App Store
      • Google Play Store

   2. Scan the QR code:

      • iOS: Use the Camera app
      • Android: Use the Expo Go app

   Using a simulator

   iOS Simulator (Mac only):

   Press i in the terminal. Expo will:

   • Open Xcode Simulator automatically
   • Install Expo Go if needed
   • Launch your app

   Android Emulator:

   Press a in the terminal. Make sure you have an Android emulator running first.

   Web Browser:

   Press w to open in your default browser.

5. Make your first change

   Open app/index.tsx in your editor and modify the welcome text:

   app/index.tsx

   export default function HomeScreen() {
     return (
       <ThemedView style={styles.container}>
         <SafeAreaView style={styles.safeArea}>
           <ThemedView style={styles.heroSection}>
             <AnimatedIcon />
             <ThemedText type="title" style={styles.title}>
               Hello from Expo! {/* Changed this line */}
             </ThemedText>
           </ThemedView>
           {/* ... rest of the component */}
         </SafeAreaView>
       </ThemedView>
     );
   }
   

   Save the file and watch your app update instantly thanks to Fast Refresh!

What Just Happened?

Congratulations! You just:

1. Created a new Expo app with Expo Router for navigation
2. Started a development server with Metro bundler
3. Opened your app on a device or simulator
4. Made a change and saw it update in real-time

Understanding Your Project

File-Based Routing

Your app uses Expo Router for navigation. Files in the app/ directory automatically become routes:

app/
  _layout.tsx     # Layout wrapping all screens
  index.tsx       # Home screen (route: /)
  explore.tsx     # Explore screen (route: /explore)

Navigate between screens using the Link component:

import { Link } from 'expo-router';

<Link href="/explore">Go to Explore</Link>

Key Files

app.json - App Configuration

Controls your app’s settings:

app.json

{
  "expo": {
    "name": "my-app",
    "slug": "my-app",
    "version": "1.0.0",
    "orientation": "portrait",
    "icon": "./assets/images/icon.png",
    "scheme": "myapp",
    "userInterfaceStyle": "automatic",
    "ios": {
      "bundleIdentifier": "com.yourcompany.myapp"
    },
    "android": {
      "package": "com.yourcompany.myapp"
    }
  }
}

package.json - Dependencies

Lists your app’s dependencies and scripts:

package.json

{
  "name": "my-app",
  "main": "expo-router/entry",
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web"
  },
  "dependencies": {
    "expo": "~55.0.0",
    "expo-router": "~55.0.0",
    "react": "19.2.0",
    "react-native": "0.83.2"
  }
}

Development Commands

Start development server

npx expo start

Interactive Terminal

When the dev server is running, press:

• a - Open on Android emulator
• i - Open on iOS simulator
• w - Open in web browser
• r - Reload the app
• m - Toggle developer menu
• j - Open React DevTools (web)
• c - Show project QR code

Common Issues

Can't scan QR code

Make sure your phone and computer are on the same WiFi network. If using a corporate network, try:

npx expo start --tunnel

This uses a public URL that works on any network.

Port already in use

The default port (8081) is taken. Try:

npx expo start --port 8082

iOS Simulator won't open

Make sure Xcode is installed:

xcode-select --install

Then try running the simulator first:

open -a Simulator

Metro bundler errors

Clear the cache and restart:

npx expo start --clear

Next Steps

Learn Core Concepts

Understand how Expo works under the hood

Follow the Tutorial

Build a complete app step-by-step

Explore the SDK

Browse 100+ native modules for camera, location, notifications, and more

Complete Installation

Set up for production builds with Xcode and Android Studio

Remember: Expo Go is perfect for learning and prototyping, but for custom native code or third-party native libraries, you’ll need to create a development build.