react-native-setup

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: cd ios && rm -rf build Pods Podfile.lock && pod install && cd ...
• Clean Android: cd android && ./gradlew clean && cd ...
• 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
cd ios && RCT_NEW_ARCH_ENABLED=1 pod install && cd ..
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)

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.