Onboarding Basics

10 examples for day-one machine setup - Xcode, Android Studio, EAS CLI, simulators, and SDK 57 pin - so a new teammate runs the app before lunch.

Prerequisites

Clone the team repo and confirm the SDK contract in package.json before installing native tooling. If the project uses the default template, expect Expo Router and managed workflow (no committed ios/ / android/ until prebuild or EAS).

git clone git@github.com:your-org/your-app.git
cd your-app
node -v   # expect 20.x
cat package.json | grep '"expo"'

Target stack for this section:

{
  "engines": { "node": ">=20.0.0" },
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Tooling: These examples target Expo SDK 57 (expo ~57.0.4), React Native 0.86.0, and React 19.2.3. See Project Setup Basics for scaffold flags and folder layout.

Basic Examples

1. Node 20 and Package Manager

Install Node 20 LTS with nvm, fnm, or mise - SDK 57 tooling and EAS CLI expect it.

# nvm example
nvm install 20
nvm use 20
node -v   # v20.x.x
 
npm install
# or: corepack enable && pnpm install

{
  "engines": {
    "node": ">=20.0.0"
  }
}

• One lockfile in the repo - use the same package manager the team documents in CONTRIBUTING.md
• npm ci on CI; locally npm install is fine after clone
• If engines fails, fix Node before chasing Metro errors - wrong Node causes cryptic transform failures

Related: Project Setup Basics - lockfile and .gitignore hygiene

2. SDK 57 Pin Verification

The expo package version is the compatibility contract for every expo-* module.

npm install
npx expo-doctor
npx expo install --check

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

• npx expo-doctor compares your graph to the SDK 57 matrix - run it on day one and after every git pull
• npx expo install <pkg> resolves peer versions - never hand-pick expo-camera without it
• Mismatch symptom: red screen mentioning native module version or Hermes parse errors
• New hires should not bump SDK in week one unless assigned - pin first, upgrade later

Related: create-expo-app Templates - default@sdk-57 scaffold

3. Environment Variables and Secrets

Copy the example env file before first run - missing API URLs cause silent blank screens.

cp .env.example .env.local

# .env.example (committed)
EXPO_PUBLIC_API_URL=https://api.staging.example.com
# EAS secrets - not in .env for production builds

// app.config.ts - surface public vars via extra when needed
export default {
  expo: {
    extra: {
      apiUrl: process.env.EXPO_PUBLIC_API_URL,
    },
  },
};

• EXPO_PUBLIC_* vars embed in the JS bundle - never put private keys here
• Production secrets live in EAS Environment Variables, not laptop .env files
• Ask your lead for 1Password / vault links to EXPO_TOKEN, staging accounts, and TestFlight invites
• Restart Metro after changing env vars: npx expo start -c

4. First Run - Metro and Expo Go

Confirm JavaScript boots before installing multi-gigabyte native IDEs.

npx expo start
# press i for iOS simulator (requires Xcode)
# press a for Android emulator (requires Android Studio)
# scan QR with Expo Go on a physical device

{
  "scripts": {
    "start": "expo start",
    "ios": "expo start --ios",
    "android": "expo start --android"
  }
}

• Expo Go is fastest for Router and UI work - limited native modules
• expo start -c clears Metro cache when imports look stale after branch switches
• If the project uses expo-dev-client, day-one may require a development build - check eas.json for development profile
• Success criteria: home screen loads, no redbox, tsc --noEmit passes

Related: Expo Router Basics - file-based routes in app/

5. Xcode and iOS Simulator (macOS)

iOS development requires Xcode from the Mac App Store and command-line tools.

xcode-select --install
sudo xcodebuild -license accept
xcode-select -p
# /Applications/Xcode.app/Contents/Developer
 
# List simulators
xcrun simctl list devices available
 
# Open Simulator app
open -a Simulator

npx expo start --ios
# or: npx expo run:ios

• Install Xcode 16+ compatible with SDK 57 - match what CI/EAS uses when documented
• First run:ios may trigger CocoaPods (pod install) if ios/ exists or after prebuild
• Apple Silicon: simulators are arm64 - faster than Rosetta x86 images
• Windows/Linux teammates use EAS Build for iOS artifacts - no local compile required

6. Android Studio and Emulator

Android builds need Android Studio with SDK Platform 35 and a virtual device (AVD).

# After Android Studio install - set ANDROID_HOME
export ANDROID_HOME=$HOME/Library/Android/sdk   # macOS
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools
 
adb devices
emulator -list-avds

Android Studio → SDK Manager:

• SDK Platforms: Android 15 (API 35) - matches RN 0.86 defaults
• SDK Tools: Android SDK Build-Tools, Platform-Tools, Emulator

npx expo start --android

• Create an AVD with Google Play image when testing Play Services features
• adb reverse helps Metro reach localhost APIs: adb reverse tcp:8081 tcp:8081
• Enable USB debugging on physical Android devices for on-device dev

7. EAS CLI and Expo Account

EAS CLI links your machine to Expo's cloud build service - required for store-shaped binaries.

npm install -g eas-cli@latest
# or project-local: npx eas-cli@latest
 
eas login
eas whoami
 
cd your-app
eas build:configure   # creates eas.json if missing

// eas.json (minimal starter)
{
  "cli": { "version": ">= 16.0.0" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {}
  }
}

• eas login uses your Expo account - request org invite from mobile lead
• eas build:configure wires project ID in app.config.ts via extra.eas.projectId
• CI uses EXPO_TOKEN robot account - humans use eas login; never commit tokens
• First cloud build: eas build --profile development --platform ios --local optional; default is cloud

Related: EAS Build Basics - profiles, credentials, first build

Intermediate Examples

8. Development Client vs Expo Go

When the app adds custom native modules or config plugins, Expo Go is not enough - install a dev client.

npx expo install expo-dev-client
eas build --profile development --platform ios
# Install IPA via QR from EAS dashboard
npx expo start --dev-client

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": { "simulator": true }
    }
  }
}

• Development profile includes expo-dev-client and native code from config plugins
• Simulator builds (ios.simulator: true) install faster for iOS-only UI work
• Rebuild dev client when native deps change - JS-only changes still hot-reload
• Document which profile new hires should install in onboarding doc

Related: EAS Build Basics - developmentClient: true

9. Simulator and Emulator Shortcuts

Standardize device names so pairing sessions and screenshots match.

# iOS - boot named simulator
xcrun simctl boot "iPhone 16"
open -a Simulator
 
# Android - start AVD by name
emulator -avd Pixel_8_API_35 &
 
# Expo targets specific device
npx expo run:ios --device "iPhone 16"
npx expo run:android --device Pixel_8_API_35

// package.json - team shortcuts (optional)
{
  "scripts": {
    "ios:16": "expo run:ios --device 'iPhone 16'",
    "android:pixel": "expo run:android --device Pixel_8_API_35"
  }
}

• Same device class in design reviews - avoid "works on my iPhone SE" surprises
• Reset simulators when Keychain or push state gets corrupted: xcrun simctl erase all (destructive)
• Physical devices: register UDIDs for iOS internal distribution in EAS credentials

10. Day-One Verification Checklist

Run this script block before opening your first PR - catches 90% of onboarding drift.

node -v                    # 20.x
npm ci
npx expo-doctor
npm run typecheck          # or: npx tsc --noEmit
npm run lint
npm test -- --passWithNoTests
npx expo start

## CONTRIBUTING.md excerpt - Machine setup
1. Node 20 via nvm
2. Clone + `npm ci`
3. `cp .env.example .env.local` (ask #mobile for values)
4. `npx expo-doctor` - must pass
5. `npx expo start` - iOS sim + Android emu smoke
6. `eas login` + org invite
7. Install dev client from EAS `development` profile if repo has expo-dev-client

• Add npx expo customize tsconfig.json if typed routes fail on clean clone
• Screenshot passing expo-doctor in your onboarding PR if your team tracks hire checklists
• Escalate to platform channel when doctor fails on fresh clone - likely repo drift, not hire error

Related: Project Setup Best Practices - conventions that survive week two

FAQs

Related

• Project Setup Basics - scaffold, SDK pin, folder layout
• EAS Build Basics - first cloud build
• Expo Router Basics - app/ mental model
• First-Week Learning Path - what to learn after machine setup
• Codebase Tour Checklist - where code lives

Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (expo ~57.0.4).