Understanding Prebuild

Learn why prebuild is necessary, when to run it, and how it works with native modules in your React Native app.

What is Prebuild?

The expo prebuild command generates the native android/ and ios/ folders for your Expo project. This is essential when using libraries that contain native code.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  expo prebuild  │ ──▶ │  Generates      │ ──▶ │  expo run:ios   │
│                 │     │  android/ & ios/│     │  expo run:android
└─────────────────┘     └─────────────────┘     └─────────────────┘

Why Do We Need Prebuild?

PHL RN Boilerplate uses several libraries that require native code compilation:

Library	Why It Needs Native Code
react-native-mmkv	High-performance storage using native C++ library
react-native-reanimated	Native animations running on UI thread
react-native-gesture-handler	Native gesture recognition
react-native-screens	Optimized native navigation

These libraries don't work with Expo Go because they contain custom native code that needs to be compiled into your app.

Expo Go vs Development Build

Expo Go

✅ Ready-to-download app

✅ No build required

✅ Great for prototyping

❌ Limited to Expo SDK APIs

❌ No custom native modules

Development BuildUsed by this boilerplate

✅ Custom build for your app

✅ Any native library supported

✅ Production-ready

✅ Full flexibility

⚠️ Requires prebuild

When to Run Prebuild

You need to run expo prebuild in these situations:

First Time Setup

When you first clone or create the project.

Adding Native Modules

After installing a new library that requires native code.

Modifying app.json

After changing app name, bundle ID, icons, splash screen, etc.

Upgrading Expo SDK

After updating to a new Expo SDK version.

How to Run Prebuild

Basic Command

bash

npx expo prebuild

Clean Prebuild

If you encounter issues, clean and regenerate the native folders:

bash

npx expo prebuild --clean

--clean will delete existing android/ and ios/ folders and regenerate them. Any manual changes will be lost.

Platform-Specific Prebuild

Generate native code for a specific platform only:

bash

# Android only
npx expo prebuild --platform android

# iOS only
npx expo prebuild --platform ios

What Happens During Prebuild?

1. Reads app.json

Expo reads your app configuration (name, bundle ID, icons, permissions, etc.)

2. Generates Native Projects

Creates android/ and ios/ folders with all necessary native files

3. Links Native Modules

Automatically links all native libraries (MMKV, Reanimated, etc.)

4. Applies Configurations

Configures permissions, entitlements, and other native settings

Understanding the Output

After running prebuild, you'll see:

typescript

my-app/
├── android/              # ← Generated Android project
│   ├── app/
│   ├── build.gradle
│   └── ...
├── ios/                  # ← Generated iOS project
│   ├── MyApp/
│   ├── MyApp.xcodeproj
│   └── ...
└── src/                  # Your source code (unchanged)

The android/ and ios/ folders are typically added to .gitignore and regenerated as needed.

Common Issues

Issue: "Command not found: expo"

Solution: Install Expo CLI or use npx:

bash

npm install -g @expo/cli
# or use npx
npx expo prebuild

Issue: "Pod install failed"

Solution: Clean CocoaPods cache and reinstall:

bash

cd ios
rm -rf Pods Podfile.lock
pod install --repo-update
cd ..

Issue: "Android build failed"

Solution: Clean Gradle cache:

bash

cd android
./gradlew clean
cd ..
npx expo prebuild --clean

Best Practices

✅ Run prebuild after cloning

Always run npx expo prebuild when setting up the project on a new machine.

✅ Use --clean when in doubt

If you're having issues, --clean ensures a fresh start.

✅ Add to .gitignore

Native folders can be regenerated, so keep them out of version control.

❌ Don't manually edit native code

Prebuild will overwrite manual changes. Use config plugins instead.

Next Steps

Back to Getting Started →

Continue with the installation guide.