Creating Development Builds

Development builds can be created either locally on your machine or in the cloud using EAS Build. Both methods produce the same result - a debug build with expo-dev-client installed.

Prerequisites

Install expo-dev-client

npx expo install expo-dev-client

This package provides the dev client UI and enhanced debugging tools.

Configure your app

Ensure your app.json has the required fields:

app.json

{
  "expo": {
    "name": "My App",
    "slug": "my-app",
    "version": "1.0.0",
    "ios": {
      "bundleIdentifier": "com.mycompany.myapp"
    },
    "android": {
      "package": "com.mycompany.myapp"
    }
  }
}

Local Builds

Local builds are created on your development machine using native build tools.

iOS Local Builds

Requires macOS with Xcode installed

# Generate native iOS project and build
npx expo run:ios

# Build for specific simulator
npx expo run:ios --simulator="iPhone 15 Pro"

# Build for physical device
npx expo run:ios --device

# Specify configuration
npx expo run:ios --configuration Release

Device Selection

The CLI will prompt you to select a device:

› Select a simulator or device
❯ iPhone 15 Pro (simulator)
  iPhone 14 (simulator)
  My iPhone (device) - connected via USB

Automatic Signing

For physical devices, ensure you have a development team configured:

# Set your Apple Team ID
export APPLE_TEAM_ID=YOUR_TEAM_ID

# Or create a .env.local file
echo "APPLE_TEAM_ID=YOUR_TEAM_ID" > .env.local

Android Local Builds

Requires Android Studio and Android SDK

# Generate native Android project and build
npx expo run:android

# Build for specific device/emulator
npx expo run:android --device

# Build specific variant
npx expo run:android --variant debug
npx expo run:android --variant release

Device Selection

› Select a device/emulator
❯ Pixel_7_Pro_API_36 (emulator)
  sdk_gphone64_arm64 (emulator) - running
  SM-G998U (device) - connected via USB

Gradle Configuration

Customize the build in android/gradle.properties:

android/gradle.properties

org.gradle.jvmargs=-Xmx4096m
android.useAndroidX=true
android.enableJetifier=true

Local Build Process

When you run npx expo run:ios or npx expo run:android:

Prebuild (if needed)

If native directories don’t exist, runs npx expo prebuild:

› Compiling app
› Generating native code for ios
› Installing dependencies

Install dependencies

Installs native dependencies:

iOS: Runs pod install
Android: Syncs Gradle dependencies

Build native project

Invokes native build tools:

iOS: xcodebuild with your scheme
Android: ./gradlew with specified variant

Install and launch

Installs the app on the selected device and launches it.

Cloud Builds with EAS Build

EAS Build creates your app in the cloud - no Xcode or Android Studio required.

Setup

Install EAS CLI

npm install -g eas-cli
eas login

Configure EAS Build

eas build:configure

This creates eas.json:

eas.json

{
  "cli": {
    "version": ">= 0.52.0"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": {
        "resourceClass": "m-medium"
      },
      "android": {
        "buildType": "apk",
        "gradleCommand": ":app:assembleDebug"
      }
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {
      "ios": {
        "resourceClass": "m-medium"
      }
    }
  }
}

Building

# Build for both platforms
eas build --profile development

# Build for specific platform
eas build --profile development --platform ios
eas build --profile development --platform android

# Build for local installation
eas build --profile development --platform ios --local

Build Profiles

Customize builds for different scenarios:

{
  "development": {
    "developmentClient": true,
    "distribution": "internal",
    "ios": {
      "simulator": true,
      "buildConfiguration": "Debug"
    }
  }
}

Resource Classes

Choose the right machine size:

eas.json

{
  "build": {
    "development": {
      "ios": {
        "resourceClass": "m-medium"  // or "m-large" for faster builds
      },
      "android": {
        "resourceClass": "large"     // or "medium"
      }
    }
  }
}

Class	CPU	RAM	Build Time
medium	4 cores	8 GB	~10-15 min
large	8 cores	16 GB	~5-8 min

Environment Variables

Pass secrets to builds:

eas.json

{
  "build": {
    "development": {
      "env": {
        "API_URL": "https://dev-api.example.com",
        "SENTRY_DSN": "$SENTRY_DSN"
      }
    }
  }
}

Set secrets:

eas secret:create --name SENTRY_DSN --value "your-dsn-here"

Configuration

Build Properties

Customize native build settings with expo-build-properties:

npx expo install expo-build-properties

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 34,
            "targetSdkVersion": 34,
            "minSdkVersion": 24,
            "buildToolsVersion": "34.0.0",
            "kotlinVersion": "1.9.0",
            "enableProguardInReleaseBuilds": true,
            "enableShrinkResourcesInReleaseBuilds": true
          },
          "ios": {
            "deploymentTarget": "13.4",
            "useFrameworks": "static"
          }
        }
      ]
    ]
  }
}

Custom Plugins

Modify native projects with config plugins:

app.json

{
  "expo": {
    "plugins": [
      "expo-camera",
      ["expo-image-picker", {
        "photosPermission": "Allow $(PRODUCT_NAME) to access your photos"
      }],
      "./plugins/withCustomPlugin.js"
    ]
  }
}

Managing Builds

Build Cache

Speed up builds by caching dependencies:

eas.json

{
  "build": {
    "development": {
      "cache": {
        "paths": [
          "node_modules",
          "ios/Pods",
          "android/.gradle"
        ]
      }
    }
  }
}

Clean Builds

Force a clean build when needed:

# EAS Build
eas build --profile development --clear-cache

# Local builds
npx expo run:ios --clean
npx expo run:android --clean

Viewing Builds

# List all builds
eas build:list

# Filter by profile
eas build:list --profile development

# View build details
eas build:view <build-id>

Troubleshooting

iOS Build Fails: Signing Issues

error: No signing certificate "iOS Development" found

Solution: Ensure you’re logged into the correct Apple account:

eas device:create

Android Build Fails: Out of Memory

Error: OutOfMemoryError: Java heap space

Solution: Increase Gradle memory:

eas.json

{
  "build": {
    "development": {
      "android": {
        "gradleCommand": ":app:assembleDebug",
        "env": {
          "GRADLE_OPTS": "-Xmx4096m"
        }
      }
    }
  }
}

Local Build: Command Not Found

Command not found: xcodebuild

Solution: Install Xcode command line tools:

xcode-select --install

Slow Builds

Improve build times:

Use larger resource class (EAS Build)
Enable caching
Minimize dependencies
Use Hermes engine:

app.json

{
  "expo": {
    "jsEngine": "hermes"
  }
}

Next Steps

Install on Devices

Install your development build on physical devices

Start Developing

Learn how to debug your app

Build Properties

Customize native build settings

Prebuild

Understand the prebuild workflow

Development Builds

Debugging

Testing

Native Development

Creating Development Builds

Prerequisites

Local Builds

iOS Local Builds

Device Selection

Automatic Signing

Android Local Builds

Device Selection

Gradle Configuration

Local Build Process

Cloud Builds with EAS Build

Setup

Building

Build Profiles

Resource Classes

Environment Variables

Configuration

Build Properties

Custom Plugins

Managing Builds

Build Cache

Clean Builds

Viewing Builds

Troubleshooting

iOS Build Fails: Signing Issues

Android Build Fails: Out of Memory

Local Build: Command Not Found

Slow Builds

Next Steps

Install on Devices

Start Developing

Build Properties

Prebuild

Development Builds

Debugging

Testing

Native Development

​Prerequisites

​Local Builds

​iOS Local Builds

​Device Selection

​Automatic Signing

​Android Local Builds

​Device Selection

​Gradle Configuration

​Local Build Process

​Cloud Builds with EAS Build

​Setup

​Building

​Build Profiles

​Resource Classes

​Environment Variables

​Configuration

​Build Properties

​Custom Plugins

​Managing Builds

​Build Cache

​Clean Builds

​Viewing Builds

​Troubleshooting

​iOS Build Fails: Signing Issues

​Android Build Fails: Out of Memory

​Local Build: Command Not Found

​Slow Builds

​Next Steps

Install on Devices

Start Developing

Build Properties

Prebuild

Prerequisites

Local Builds

iOS Local Builds

Device Selection

Automatic Signing

Android Local Builds

Device Selection

Gradle Configuration

Local Build Process

Cloud Builds with EAS Build

Setup

Building

Build Profiles

Resource Classes

Environment Variables

Configuration

Build Properties

Custom Plugins

Managing Builds

Build Cache

Clean Builds

Viewing Builds

Troubleshooting

iOS Build Fails: Signing Issues

Android Build Fails: Out of Memory

Local Build: Command Not Found

Slow Builds

Next Steps