Building Your First iOS and Android App With React Native

Introduction

React Native lets you write a single JavaScript codebase and ship it to both iOS and Android, a real advantage for startups and lean teams that can't maintain two separate native codebases. Companies like Meta (Facebook Marketplace, Ads Manager), Shopify, and Microsoft (Xbox app, Power Apps) have all committed to it in production.

According to Statista's 2023 developer survey, React Native was used by 35% of cross-platform mobile developers worldwide — making it the most widely adopted solution in its category.

But React Native's reputation for being "easy to set up" is misleading. The first build usually fails — not because of bad code, but because of a misconfigured environment, the wrong tool choice, or a misunderstanding of how iOS and Android handle things differently.

This guide is built around fixing that. It covers environment setup, the step-by-step build process, the CLI vs Expo decision, and the architectural choices that determine app quality long-term — so your first build doesn't have to be your most frustrating one.

TL;DR

React Native uses JavaScript and React to build native iOS and Android apps from one codebase, saving significant development time
You need Node.js (22.11.0+), Watchman, Xcode, Android Studio, and JDK 17 (macOS required for full iOS/Android builds)
Choose React Native CLI for production apps needing custom native modules; choose Expo for prototyping or simpler apps
Run npx react-native doctor before anything else — it catches setup problems before they become cryptic build errors
After your first app runs, prioritize navigation, state management, and permissions as your next learning steps

What You Need Before Building Your First React Native App

Incomplete environment setup is the single biggest reason first-time React Native projects fail before a single line of app code is written. Get this right first.

Hardware and OS Requirements

You need a macOS machine to build and run the iOS version. Xcode is macOS-only — no workaround exists for local iOS builds on Windows or Linux.

macOS users: Full iOS and Android development is possible
Windows/Linux users: Android development only, or use Expo Go for cross-platform device testing without a Mac
Expo EAS Build: Offers cloud-based iOS builds for teams without Macs, though Apple Developer credentials are still required

Software and Tools Required

Install and verify each tool before writing any app code:

Tool	Version	Purpose
Node.js	22.11.0+ (LTS recommended)	Runs JavaScript tooling
Watchman	Latest	File-change detection, faster rebuilds
Xcode	Required (macOS only)	iOS compilation and simulator
Android Studio	Latest stable	Android SDK management and emulator
JDK	17 (JDK 18+ may cause Gradle compatibility issues)	Android native code compilation
VS Code	Any	Code editor

React Native development environment tools versions and purposes comparison table

Prior Knowledge That Helps

You don't need Swift, Kotlin, or Objective-C to get started. What you do need:

Working knowledge of JavaScript and JSX syntax
Basic React concepts: components, props, state, and hooks
React Native's component hierarchy follows the same model — just with View and Text instead of div and p

With your environment confirmed and prerequisites in place, you're ready to scaffold your first project.

How to Build Your First iOS and Android App With React Native

This guide uses the React Native CLI for full platform control. All steps assume macOS with Xcode and Android Studio already installed.

Step 1: Install Node, Watchman, and Core Dependencies

Install Homebrew first if it's not already present, then run:

brew install node watchman

Verify both installed correctly:

node -v
watchman --version

Watchman watches your project files for changes and triggers Metro rebuilds automatically. Without it, reloads are slower and some file-watch edge cases cause builds to stall.

Step 2: Configure the iOS Environment

Install Xcode Command Line Tools:
```
xcode-select --install
```
Open Xcode → Settings → Locations and confirm the Command Line Tools version is set
In your project, open the .xcworkspace file (not .xcodeproj)
Navigate to Signing & Capabilities and set the Team and Bundle Identifier for both the app target and test target

That last step is required to run on a physical device. Skip it and you'll get signing errors that feel unrelated to your actual code.

Step 3: Configure the Android Environment

Install JDK 17 via Homebrew:

brew install --cask zulu17

Then in Android Studio, open SDK Manager and install:

Android SDK Platform 35
Android SDK Build-Tools 36.0.0
Android SDK Command-line Tools (latest)

Next, add ANDROID_HOME to your .zshrc:

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

Skipping the ANDROID_HOME variable is a common cause of build failures when running Android commands from the terminal. The build tools can't find the SDK.

Step 4: Create and Open a New React Native Project

npx @react-native-community/cli@latest init YourAppName

The generated structure:

/ios — iOS-specific native files
/android — Android-specific native files
App.tsx — root component (TypeScript by default)
index.js — entry point that registers the root component with AppRegistry

Step 5: Write Your First Screen Component

Open App.tsx and replace the boilerplate. React Native's core building blocks replace standard HTML:

React Native	HTML Equivalent
`View`	`div`
`Text`	`p`, `span`
`SafeAreaView`	Wrapper for notched devices
`StyleSheet`	CSS-like styles object

A minimal working component looks like this:

import React from 'react';
import { View, Text, StyleSheet, SafeAreaView } from 'react-native';

export default function App() {
  return (
    <SafeAreaView style={styles.container}>
      <View>
        <Text>Hello, React Native</Text>
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
});

Step 6: Run the App on iOS and Android

iOS:

npx react-native run-ios

Or open the .xcworkspace file in Xcode and click Run.

Android: First, start an Android Virtual Device (AVD) from Android Studio's Virtual Device Manager, then:

npx react-native run-android

Metro bundler starts automatically when you run either command. It serves the JavaScript bundle to the device. Keep it running — if Metro is not active, the app will show a blank screen or connection error, not a meaningful error message.

React Native CLI vs Expo: Which Should You Choose?

This is the most consequential decision before starting a project. The wrong choice creates friction once you've already built features — rework costs time you won't get back.

Choose React Native CLI when:

Your app needs custom native modules (camera beyond standard APIs, Bluetooth, video calling, real-time features)
You need full control over the iOS and Android build process
At least one developer on the team is comfortable with Xcode and Android Studio configuration
You're building a production app with specific native requirements

Choose Expo when:

You're prototyping or building an app that doesn't require custom native code
Your team works across Windows, Linux, and macOS
You're learning React Native and want to skip environment setup complexity
You need cloud-based iOS builds — Expo's EAS Build service creates ready-to-submit binaries without local Xcode compilation

Before committing to Expo, note one practical constraint: Expo Go is limited to libraries included in the Expo SDK. If you later need custom native code, you'll need a development build or prebuild path, which adds meaningful setup complexity. Recent SDK releases have reduced this friction, but teams with known native requirements are still better served starting with React Native CLI.

React Native CLI versus Expo side-by-side decision comparison infographic

Key Factors That Affect Your React Native App Quality

Once the app runs, quality and maintainability depend on a few architectural decisions made early.

Navigation Library

React Native has no built-in navigation API. You must choose a library:

React Navigation (JavaScript-based) — the community standard, handles most use cases including deep linking and tab-based navigation
Wix React Native Navigation — a native-based alternative that provides 100% native platform navigation on both iOS and Android; adds setup complexity but suits apps with complex animated transitions

Pick one before building screens. Swapping navigation libraries mid-project means refactoring every screen.

State Management

useState + useContext — sufficient for simple apps and small component trees
Zustand — lightweight, fast, minimal boilerplate; a strong choice for medium-complexity apps
Redux Toolkit — the official Redux standard; better for large teams or apps with complex shared state across many features

The key decision point: if your app has authenticated user state, cart data, or real-time sync requirements, evaluate Zustand or Redux Toolkit before you build — not when refactoring gets expensive.

Platform-Specific Code

Architectural choices only go so far — at some point, iOS and Android diverge at the platform level. The two platforms have different UI conventions, gesture handling, and API behaviours. Ignoring this produces broken experiences on one platform.

Handle differences using:

Platform.OS check for conditional logic
Platform-specific file extensions (.ios.js / .android.js) for component-level differences

Common areas requiring platform-specific handling: date pickers, navigation header styling, permission prompts, and bottom sheet behaviour.

Permissions

This is where many apps fail at submission. Permissions must be declared in two separate places:

iOS: Add purpose strings (usage description keys) to Info.plist — Apple requires this for all protected resources
Android: Add <uses-permission> elements to AndroidManifest.xml — Google Play can block publishing for noncompliant permission use

Missing permission declarations cause silent runtime failures or outright app store rejections. Define them at project start — for complex native features like video calling or real-time sync, a third-party SDK often saves significant integration time.

Common Mistakes When Building Your First React Native App

Most first-time React Native projects hit the same wall — not because the framework is flawed, but because a handful of predictable mistakes derail the build early. Avoiding these will save you hours of debugging.

Run npx react-native doctor before starting any project. It catches Node version issues, missing CocoaPods, and Android SDK misconfigurations in one pass.
Don't ignore Metro's terminal output. It surfaces JavaScript errors, module resolution failures, and dependency mismatches that beginners often miss while blaming the simulator instead.
Test on both platforms from your very first screen. A layout that works on iOS can break on Android due to different flex defaults, shadow handling, or font rendering.
Build incrementally — one working screen first, then navigation, then API calls, then authentication. Verify on both platforms after each addition, not all at once at the end.
Check compatibility before installing any native library. React Native's ecosystem moves fast; use npx react-native info to confirm your environment versions before adding dependencies.

Five common React Native first build mistakes checklist with fix actions

Frequently Asked Questions

Do I need a Mac to build React Native apps for iOS and Android?

A Mac is required for local iOS builds — Xcode is macOS-only. Android development works on Windows and Linux. During early development, Expo Go lets you test on iOS devices without a Mac, though local iOS compilation still requires macOS.

What is the difference between React Native CLI and Expo?

React Native CLI gives full control over native code and the build process but requires manual environment setup. Expo is a managed framework that abstracts setup complexity, making it faster to start — but Expo Go can't run custom native modules without a development build.

Can I build React Native apps without knowing Swift or Kotlin?

Yes. JavaScript and basic React knowledge are sufficient for most apps. Swift or Kotlin knowledge only becomes necessary when writing custom native modules that bridge JavaScript to platform-specific APIs.

Is React Native suitable for production mobile apps?

Yes — and at scale. Shopify reports sub-500 ms screen loads and 99.9%+ crash-free sessions across its mobile apps. Meta uses it for Facebook Marketplace and Ads Manager; Microsoft ships it in the Xbox app and Power Apps.

Does React Native support TypeScript?

Yes, out of the box. New projects generated with the CLI default to TypeScript — the entry file is App.tsx, not App.js. TypeScript provides better code safety and IDE autocompletion, which matters more as the codebase grows.

How long does it take to build a first React Native app?

Environment setup takes 1–3 hours on a clean machine. A basic working app with a few screens takes a day if you know React. Production-ready apps with navigation, API integration, and authentication typically take several weeks to months depending on scope.