Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/expo/expo/llms.txt

Use this file to discover all available pages before exploring further.

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:
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
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:
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:
  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

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"
    }
  }
}
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

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

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.
The default port (8081) is taken. Try:
npx expo start --port 8082
Make sure Xcode is installed:
xcode-select --install
Then try running the simulator first:
open -a Simulator
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us