react-native-setup

When to use

• Initial React Native 0.76+ / Expo SDK 52+ environment setup
• Installing or configuring Xcode, Android Studio, or their command-line tools
• Setting up iOS simulators or Android emulators for development
• Troubleshooting "Command not found", ANDROID_HOME, or SDK path errors
• Fixing CocoaPods install failures (Apple Silicon, FFI, Ruby mismatches)
• Clearing Metro / Watchman cache or diagnosing reload loops
• Configuring EAS Build, dev clients, or OTA updates
• Migrating to or troubleshooting the New Architecture (Fabric / Turbo Modules)

Cross-links: mobile-e2e-strategy (Detox / Appium / Maestro selection), docs/guidelines/agent-infra/ios-simulator-guide.md (iOS simulator decision matrix).

Assess current setup before changing anything

Before installing or upgrading anything, inspect what's already there — modifying a working toolchain blindly is the most common source of wasted hours.

1. Read package.json — RN version, Expo SDK, scripts, native dependencies.
2. Check ios/Podfile and ios/Podfile.lock — CocoaPods version, deployment target, RCT_NEW_ARCH_ENABLED flag.
3. Check android/build.gradle and android/gradle.properties — Gradle version, compile/target SDK, newArchEnabled, NDK version.
4. Verify host tools — node --version, xcodebuild -version, sdkmanager --list_installed, pod --version, watchman --version.
5. Check for an existing .nvmrc, .tool-versions, or Brewfile — honour the project's pinned versions over global ones.
6. Read project README and CONTRIBUTING — many RN repos document one-time setup quirks (Apple Silicon Rosetta, Hermes flags, EAS profile names).

Procedure

1. Identify the target stack — RN CLI vs Expo, target SDK, supported OS, monorepo or single-package.
2. Verify prerequisites — Node, package manager, Watchman, platform SDKs (see matrix below).
3. Configure platform tooling — Xcode + CocoaPods (iOS) or Android Studio + SDK 34/35 (Android).
4. Install project dependencies — npm/yarn/pnpm/bun install, then pod install for iOS.
5. Run a smoke build — npm run ios / npm run android / npx expo start.
6. Validate — app launches, fast refresh works, Metro bundler runs without warnings.
7. On failure — apply the matching pattern from "Common setup issues" below.

Prerequisites (2025 baseline)

Node.js

• Node 20.x minimum (Node 18 EOL April 2025); Node 22 LTS recommended.
• node --version && npm --version.
• npm, yarn, pnpm, bun all supported. Corepack for yarn: corepack enable && corepack prepare yarn@stable --activate.

Xcode (macOS, iOS)

• Xcode 16.1+ minimum (RN 0.83), Xcode 26+ for Liquid Glass.
• xcode-select --install then sudo xcodebuild -license accept.
• iOS 15.1+ deployment target; iOS 18+/26 for latest features.

Android Studio

• Ladybug or later (2024.2.1+).
• SDK Platform 35 (API 35), Build-Tools 35.0.0, Platform-Tools, Emulator.
• NDK 27.1.12297006 + CMake 3.22.1+ for native modules / Turbo Modules.
• compileSdkVersion 35, targetSdkVersion 35, minSdkVersion 24.
• ANDROID_HOME exported; edge-to-edge display ready (Android 15+).

Watchman

• macOS: brew install watchman.
• Required for fast refresh on large codebases. Reset: watchman watch-del-all.

Platform setup

iOS

• CocoaPods 1.15+: sudo gem install cocoapods.
• New Architecture pods: RCT_NEW_ARCH_ENABLED=1 pod install.
• Provisioning profiles, certificates managed in Xcode or via EAS.
• Simulator management: xcrun simctl list devices. Liquid Glass requires iOS 26 simulator.

Android

• Gradle 8.10+ (bundled with Ladybug).
• AVD with API 35 image; verify edge-to-edge layout.
• New Architecture: newArchEnabled=true in gradle.properties.

Metro bundler

• Default port 8081. Cache reset: npx react-native start --reset-cache.
• Symlink support and custom resolvers needed for monorepos.

EAS Build (Expo)

• npm install -g eas-cli then eas login.
• eas build:configure to seed eas.json.
• Dev clients for custom native modules; EAS Update for OTA.

Common setup issues

"Command not found"

• PATH for Node, Android SDK, Xcode tools missing in ~/.zshrc or ~/.bash_profile.
• Symlink drift with nvm / fnm — re-run nvm use after shell reload.

SDK not found

• echo $ANDROID_HOME empty → re-export.
• Re-run SDK Manager; reinstall NDK if native modules fail.

Pod install failures

• CocoaPods < 1.15 incompatible with New Architecture — upgrade.
• Apple Silicon FFI compile errors → use system Ruby or rbenv-managed Ruby.
• Stuck pods: pod deintegrate && pod install.

Build failures

• Clean iOS: rm -rf ios/build ios/Pods ios/Podfile.lock then pod install --project-directory=ios.
• Clean Android: ./gradlew -p android clean.
• Clear Xcode derived data when stale build artefacts persist.

New Architecture issues

• Turbo Module not found → confirm codegen ran during build.
• Fabric component not rendering → verify native registration.
• Bridge incompatibility → use the interop layer.

Quick verification

node --version          # 20+ (22 LTS preferred)
npm --version
xcodebuild -version     # 16.1+
pod --version           # 1.15+
adb --version
emulator -version
watchman version
eas --version           # Expo only
echo $ANDROID_HOME      # non-empty

Quick commands

Create / run RN CLI project

npx @react-native-community/cli init MyProject
cd MyProject
RCT_NEW_ARCH_ENABLED=1 pod install --project-directory=ios
npm start                # Metro
npm run ios              # in a second terminal
npm run android          # in a third terminal

Create / run Expo project

npx create-expo-app@latest MyProject
cd MyProject
npx expo start
# Custom native code → dev client:
npx expo install expo-dev-client
eas build --profile development --platform ios
eas build --profile development --platform android

Simulator / emulator

xcrun simctl list devices
xcrun simctl boot "iPhone 16 Pro"
emulator -list-avds
emulator -avd Pixel_8_API_35

Reset everything

watchman watch-del-all
npx react-native start --reset-cache    # RN CLI
npx expo start --clear                  # Expo

Pro tips

1. Shell profile — add SDK paths once, reload once:

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

2. EAS minimum eas.json — development (dev client + internal), preview (internal), production (defaults).
3. Hermes — RN ≥ 0.70 ships Hermes by default; verify with global.HermesInternal !== undefined at runtime.
4. Health check — a single shell function running the verification block above catches 80 % of "it doesn't build" reports.

Version compatibility (2025)

Component	Minimum	Recommended	Notes
Node.js	20.x	22 LTS	Node 18 EOL April 2025
React Native	0.76	0.83	New Architecture default since 0.76
React	18.3	19.2	Activity, useEffectEvent
Expo SDK	52	54	Native tabs, Liquid Glass
Xcode	16.1	26	iOS 26 required for Liquid Glass
Android SDK	34	35	Edge-to-edge support
CocoaPods	1.14	1.15+	New Architecture compatibility
Gradle	8.6	8.10+	K2 compiler support

Output format

1. A short setup plan keyed off the target stack (RN CLI vs Expo, iOS vs Android vs both).
2. Concrete shell commands the user can paste — no placeholders unless flagged <…>.
3. A verification block confirming the toolchain is healthy before any feature work.

Auto-trigger keywords

• React Native, Expo, EAS Build
• Xcode, CocoaPods, pod install
• Android Studio, ANDROID_HOME, AVD, emulator
• Metro bundler, Watchman, fast refresh
• New Architecture, Fabric, Turbo Modules

Gotcha

• Don't set RCT_NEW_ARCH_ENABLED=1 selectively — once enabled, every pod install for that project must use it or cached artefacts diverge.
• Apple Silicon + system Ruby + FFI is the single biggest source of "pod install hangs" reports — switch to rbenv before retrying.
• Watchman left over from a previous project can pin Metro to a stale tree — watchman watch-del-all is cheap, run it before deeper debugging.
• iOS Simulator versions are tied to Xcode versions. Liquid Glass features need both Xcode 26 AND an iOS 26 simulator image installed.
• Android NDK version drift breaks Turbo Modules silently — pin 27.1.12297006 until the project explicitly upgrades.

Do NOT

• Do NOT mix npm, yarn, pnpm, and bun lockfiles in the same project — pick one, commit its lockfile, delete the others.
• Do NOT skip pod install after pulling iOS-side changes — the JS bundle will load but native modules will be stale.
• Do NOT enable New Architecture mid-feature — flag it on a clean branch, run a full clean build, validate both platforms.
• Do NOT hand-edit Podfile.lock or gradle.lock-style files — re-run the installers instead.
• Do NOT commit node_modules, ios/Pods, android/.gradle, or platform build/ directories.