mobile-react-native-setup

Starting a new React Native project for iOS development

React Native Setup

Scope: React Native project setup, Expo vs bare workflow, iOS development environment, tooling configuration Lines: ~320 Last Updated: 2025-10-18

When to Use This Skill

Activate this skill when:

Starting a new React Native project for iOS development
Choosing between Expo and bare workflow approaches
Setting up iOS development environment and dependencies
Configuring Metro bundler and build tools
Troubleshooting React Native setup and installation issues
Migrating from Expo to bare workflow
Configuring TypeScript and ESLint for React Native projects

Core Concepts

Expo vs Bare Workflow

Expo Managed:

Pre-configured development environment
OTA updates via Expo Go app
Limited access to native modules
Best for: MVPs, rapid prototyping, simple apps
No need for Xcode initially

Expo Bare:

Expo libraries + full native access
Custom native modules available
Build with EAS or locally
Best for: Apps needing custom native code
Requires Xcode and CocoaPods

React Native CLI (Bare):

Full control over native code
Direct access to iOS APIs
More complex setup
Best for: Complex apps, existing native code integration
Requires Xcode, CocoaPods, Ruby environment

Metro Bundler

Metro Role:

JavaScript bundler for React Native
Hot reloading and fast refresh
Module resolution and transformation
Source maps for debugging

Key Features:

Incremental bundling (fast rebuilds)
Tree shaking (remove unused code)
Asset resolution (images, fonts)
Platform-specific extensions (.ios.ts, .android.ts)

iOS Development Environment

Required Tools:

Xcode: Latest stable version (15.0+)
Command Line Tools: xcode-select --install
CocoaPods: sudo gem install cocoapods
Node.js: LTS version (18.x or 20.x)
Watchman: brew install watchman (file watching)

Optional Tools:

Ruby Version Manager: rbenv or rvm
iOS Simulator: Xcode includes multiple iOS versions
Physical Device: For hardware testing

Patterns

Pattern 1: Expo Managed Setup

# Create new Expo project
npx create-expo-app@latest MyApp --template blank-typescript
cd MyApp

# Install dependencies
npm install

# Start development server
npx expo start

# Run on iOS simulator
npx expo start --ios

# Install additional Expo packages
npx expo install expo-camera expo-location

When to use:

Building simple to moderate complexity apps
Need OTA updates
Don't require custom native modules
Rapid prototyping phase
Team without iOS development experience

Pattern 2: React Native CLI Setup

# Create new React Native project
npx react-native@latest init MyApp --template react-native-template-typescript
cd MyApp

# Install iOS dependencies
cd ios && pod install && cd ..

# Start Metro bundler
npm start

# Run on iOS simulator (separate terminal)
npm run ios

# Run on specific simulator
npm run ios -- --simulator="iPhone 15 Pro"

When to use:

Need custom native modules
Existing native iOS code to integrate
Full control over native build process
Complex native functionality requirements
Performance-critical applications

Pattern 3: Expo Bare Workflow Setup

# Create Expo bare workflow project
npx create-expo-app@latest MyApp --template bare-minimum
cd MyApp

# Install dependencies and pods
npm install
cd ios && pod install && cd ..

# Prebuild native projects
npx expo prebuild --clean

# Run on iOS
npx expo run:ios

# Install Expo modules
npx expo install expo-camera expo-notifications

Benefits:

Best of both worlds (Expo + native access)
Use Expo libraries with custom native code
EAS Build integration
Easier native module integration than pure RN CLI

Pattern 4: TypeScript Configuration

// tsconfig.json
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "lib": ["ES2022"],
    "jsx": "react-native",
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@screens/*": ["src/screens/*"],
      "@utils/*": ["src/utils/*"],
      "@types/*": ["src/types/*"]
    }
  },
  "include": ["**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules", "ios", "android"]
}

Benefits:

Type safety for React Native APIs
Better IDE support and autocomplete
Catch errors at compile time
Path aliases for cleaner imports

Pattern 5: Metro Configuration

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

// Add custom asset extensions
config.resolver.assetExts.push('db', 'json', 'txt');

// Add custom source extensions
config.resolver.sourceExts.push('jsx', 'js', 'ts', 'tsx', 'cjs', 'mjs');

// Platform-specific extensions order
config.resolver.platforms = ['ios', 'android', 'native'];

// Watchman configuration
config.watchFolders = [__dirname];

// Transformer configuration for SVG
config.transformer.babelTransformerPath = require.resolve('react-native-svg-transformer');
config.resolver.assetExts = config.resolver.assetExts.filter((ext) => ext !== 'svg');
config.resolver.sourceExts.push('svg');

module.exports = config;

When to use:

Custom asset types (SVG, fonts, etc.)
Monorepo setup with multiple packages
Custom module resolution
Performance optimization (caching)

Pattern 6: Package.json Scripts

{
  "name": "MyApp",
  "version": "1.0.0",
  "scripts": {
    "start": "expo start",
    "ios": "expo start --ios",
    "android": "expo start --android",
    "web": "expo start --web",
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
    "type-check": "tsc --noEmit",
    "test": "jest",
    "test:watch": "jest --watch",
    "clean": "rm -rf node_modules ios/Pods ios/build android/build",  # Cleans build artifacts only - safe to run
    "clean:metro": "rm -rf $TMPDIR/metro-* $TMPDIR/haste-*",  # Cleans Metro bundler cache - safe to run
    "pod-install": "cd ios && pod install && cd ..",
    "prebuild": "expo prebuild --clean",
    "build:ios": "eas build --platform ios"
  },
  "dependencies": {
    "expo": "~50.0.0",
    "react": "18.2.0",
    "react-native": "0.73.0"
  },
  "devDependencies": {
    "@babel/core": "^7.23.0",
    "@types/react": "~18.2.0",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@typescript-eslint/parser": "^6.0.0",
    "eslint": "^8.50.0",
    "eslint-config-expo": "^7.0.0",
    "typescript": "^5.2.0"
  }
}

Benefits:

Standardized commands across team
Easy cleanup and rebuilding
Integrated linting and type checking
iOS-specific build shortcuts

Pattern 7: Environment Setup Verification

#!/bin/bash
# check-setup.sh - Verify React Native environment

echo "Checking React Native iOS setup..."

# Node.js version
echo -n "Node.js: "
node --version

# npm version
echo -n "npm: "
npm --version

# Watchman
echo -n "Watchman: "
watchman --version 2>/dev/null || echo "Not installed"

# CocoaPods
echo -n "CocoaPods: "
pod --version 2>/dev/null || echo "Not installed"

# Xcode
echo -n "Xcode: "
xcodebuild -version | head -n1

# Command Line Tools
echo -n "Command Line Tools: "
xcode-select -p

# iOS Simulators
echo "Available iOS Simulators:"
xcrun simctl list devices available | grep iPhone

# Ruby version
echo -n "Ruby: "
ruby --version

echo "Setup check complete!"

When to use:

Onboarding new developers
Troubleshooting setup issues
CI/CD environment validation
Before major version upgrades

Quick Reference

Common Commands

Command                              | Purpose                        | When to Use
-------------------------------------|--------------------------------|------------------
npx create-expo-app MyApp            | Create Expo project            | New Expo app
npx react-native init MyApp          | Create RN CLI project          | New bare workflow
cd ios && pod install                | Install iOS dependencies       | After adding packages
npx expo start --ios                 | Run Expo on iOS                | Development
npm run ios                          | Run RN CLI on iOS              | Development
npm run clean:metro                  | Clear Metro cache              | Bundler issues
npx expo prebuild --clean            | Regenerate native folders      | Config changes
xcodebuild clean                     | Clean Xcode build              | Build issues
xcrun simctl list devices            | List iOS simulators            | Check available devices

Troubleshooting Guide

✅ DO: Keep Node.js on LTS version (18.x or 20.x)
✅ DO: Run pod install after every package addition
✅ DO: Clear Metro cache when seeing stale code
✅ DO: Use Watchman to improve file watching performance
✅ DO: Keep Xcode and Command Line Tools updated

❌ DON'T: Mix package managers (npm/yarn/pnpm)
❌ DON'T: Skip pod install after dependency changes
❌ DON'T: Use outdated Node.js versions
❌ DON'T: Ignore Xcode update prompts
❌ DON'T: Commit ios/Pods directory to git

Node Version Requirements

React Native Version | Node.js Version    | Notes
---------------------|--------------------|-----------------------
0.73.x               | 18.x LTS           | Latest stable
0.72.x               | 16.x - 18.x        | Expo SDK 49
0.71.x               | 16.x - 18.x        | Expo SDK 48
0.70.x               | 14.x - 18.x        | Legacy support

Anti-Patterns

❌ Using wrong Node.js version: Breaks native modules and build tools ✅ Use nvm or fnm to manage Node versions, stick to LTS releases

❌ Skipping pod install: Leads to missing native dependencies and runtime crashes ✅ Run cd ios && pod install after every package addition or removal

❌ Committing Pods directory: Bloats repository with thousands of files ✅ Add ios/Pods/ to .gitignore, commit Podfile.lock instead

❌ Mixing Expo and bare workflow randomly: Confusion and broken builds ✅ Choose workflow upfront, migrate deliberately with expo prebuild

❌ Ignoring Metro cache issues: Stale bundler state causes mysterious bugs ✅ Clear cache with npm run clean:metro or rm -rf $TMPDIR/metro-* (safe - cleans Metro cache)

❌ Not using Watchman on macOS: Slow file watching and reload issues ✅ Install Watchman with Homebrew: brew install watchman

❌ Running npm install in ios/ folder: Breaks CocoaPods dependency resolution ✅ Only run npm install at project root, use pod install for iOS dependencies

❌ Using deprecated react-native-cli globally: Old CLI causes compatibility issues ✅ Use npx with latest version: npx react-native@latest init MyApp

Related Skills

react-native-navigation.md - Multi-screen navigation and routing
react-native-native-modules.md - Bridging to native iOS code
react-native-performance.md - Optimization and profiling
swiftui-architecture.md - Understanding iOS app structure
swift-concurrency.md - Native async patterns for bridging
ios-testing.md - Testing React Native apps on iOS

Last Updated: 2025-10-18 Format Version: 1.0 (Atomic)