Installation & Setup

Complete guide to setting up your Expo development environment

This guide covers everything you need to develop, build, and deploy Expo apps. Choose your setup based on what you’re building:

• Quick start: Just Node.js and a phone → Use Expo Go
• Full setup: Native builds → Install platform-specific tools

System Requirements

Required for All

• Node.js 18 or newer
• npm, yarn, or pnpm
• Code editor (VS Code recommended)

For Native Builds

• macOS (for iOS development)
• Xcode 15+ (iOS)
• Android Studio (Android)
• CocoaPods (iOS)

Step 1: Install Node.js

Expo requires Node.js version 18 or newer.

macOS

Using Homebrew (recommended):

brew install node

Or download from nodejs.org:

Visit nodejs.org and download the LTS version.

Verify installation:

node --version  # Should show v18.0.0 or higher
npm --version

Windows

Download installer:

Visit nodejs.org and download the LTS version for Windows.

Or use winget:

winget install OpenJS.NodeJS

Verify installation:

node --version  # Should show v18.0.0 or higher
npm --version

You may need to restart your terminal after installation.

Linux

Using package manager:

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install -y nodejs

Verify installation:

node --version  # Should show v18.0.0 or higher
npm --version

The Expo SDK requires Node.js 22.14.0 as specified in the monorepo, but Node 18+ is generally supported for app development.

Step 2: Install Expo CLI

Expo CLI is included with the expo package. You don’t need to install it globally!

Create new project (includes CLI)

npx create-expo-app my-app
cd my-app

Why no global install?

The @expo/cli package is versioned with the Expo SDK, ensuring compatibility. Running npx expo uses your project’s local version automatically.

Benefits:

• No version conflicts between projects
• Automatic updates with SDK upgrades
• Faster CI/CD (no global install needed)

Verify CLI Installation

npx expo --version

You should see output like:

55.0.9

Step 3: Platform-Specific Setup

iOS Development

iOS development requires a Mac with macOS.

Install Xcode

1. Install Xcode from the Mac App Store (15+ required)
2. Open Xcode and accept the license agreement
3. Install command line tools:

xcode-select --install

Install CocoaPods

CocoaPods manages iOS native dependencies:

sudo gem install cocoapods

Or using Homebrew:

brew install cocoapods

Verify iOS Setup

# Check Xcode
xcodebuild -version

# Check CocoaPods
pod --version

# List available simulators
xcrun simctl list devices

Set Up iOS Simulator

Open the iOS Simulator:

open -a Simulator

In Xcode, go to Xcode → Settings → Platforms to download additional iOS versions.

Android Development

Install Android Studio

1. Download from developer.android.com/studio
2. Run the installer and follow the setup wizard
3. Install the Android SDK through Android Studio

Configure Android SDK

In Android Studio:

1. Open Settings → Languages & Frameworks → Android SDK
2. Under SDK Platforms, install:
   • Android 14 (API 34)
   • Android 13 (API 33)
3. Under SDK Tools, install:
   • Android SDK Build-Tools
   • Android Emulator
   • Android SDK Platform-Tools

Set Environment Variables

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Windows: Add to System Environment Variables:

• ANDROID_HOME: C:\Users\YourUsername\AppData\Local\Android\Sdk
• Add to Path: %ANDROID_HOME%\platform-tools

Reload your shell:

source ~/.zshrc  # or ~/.bashrc

Verify Android Setup

# Check ADB
adb --version

# List available emulators
emulator -list-avds

Create Android Emulator

1. Open Android Studio
2. Go to Tools → Device Manager
3. Click Create Device
4. Select a device (e.g., Pixel 6)
5. Download and select a system image (e.g., Android 14)
6. Finish creation

Start an Emulator

# List available emulators
emulator -list-avds

# Start an emulator
emulator -avd Pixel_6_API_34

Web Development

Web development requires no additional setup! Expo uses Metro bundler which includes web support.

Browser Requirements

• Chrome, Firefox, Safari, or Edge (latest version)
• JavaScript enabled
• Local development: localhost access

Start Web Development

npx expo start --web

Or press w in the Expo dev server terminal.

Web-Specific Configuration

Configure web settings in app.json:

app.json

{
  "expo": {
    "web": {
      "bundler": "metro",
      "favicon": "./assets/favicon.png"
    }
  }
}

Expo Go (No Build)

Skip native tool installation if you’re only using Expo Go:

Install Expo Go on Your Device

• iOS: App Store
• Android: Play Store

What You Can Do

• Develop and test apps instantly
• Use all built-in Expo SDK modules
• Share with QR code
• Hot reload during development

Limitations

• Cannot add custom native code
• Limited to modules included in Expo Go
• Cannot use some third-party native libraries

For custom native code, you’ll need to create a development build.

Step 4: Editor Setup

Visual Studio Code (Recommended)

Install VS Code Extensions:

1. Open VS Code
2. Install these extensions:
   • ES7+ React/Redux/React-Native snippets
   • React Native Tools
   • Prettier - Code formatter
   • ESLint

Configure VS Code:

Create .vscode/settings.json in your project:

.vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Step 5: Verify Installation

Create a test project to verify everything works:

1. Create test project

   npx create-expo-app test-app
   cd test-app
   
2. Start development server

   npx expo start
   
3. Test on platforms

   iOS Simulator (Mac only):

   Press 'i' in the terminal
   

   Android Emulator:

   Press 'a' in the terminal
   

   Web Browser:

   Press 'w' in the terminal
   

   Physical Device:

   • Scan QR code with Expo Go app

If your app opens successfully on any platform, your setup is complete!

Troubleshooting

iOS: 'command line tools are not installed'

Install Xcode command line tools:

xcode-select --install

If that doesn’t work, reset the path:

sudo xcode-select --reset

Android: 'ANDROID_HOME not set'

Add to your shell profile:

~/.zshrc

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

Reload:

source ~/.zshrc

iOS: 'Unable to boot simulator'

Reset iOS Simulator:

1. Open Simulator app
2. Go to Device → Erase All Content and Settings
3. Try again

Or from command line:

xcrun simctl erase all

Android: 'No emulators found'

Create a new emulator in Android Studio:

1. Open Android Studio
2. Tools → Device Manager
3. Click Create Device
4. Follow the wizard

CocoaPods: 'pod install' fails

Update CocoaPods and try again:

sudo gem install cocoapods
cd ios
pod repo update
pod install

Node version issues

Use a Node version manager:

nvm (Mac/Linux):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node 18
nvm install 18
nvm use 18

nvm-windows:

Download from github.com/coreybutler/nvm-windows

Package Manager Choice

Expo works with npm, yarn, or pnpm:

npm

npx create-expo-app my-app
npm install
npm start

Once you choose a package manager, stick with it for the entire project. Don’t mix them!

Next Steps

Quick Start

Create your first app in 5 minutes

Core Concepts

Learn how Expo works

Tutorial

Build a complete app step-by-step

Development Builds

Set up for custom native code