1---
2name: expo-dev-client
3description: Build and distribute Expo development clients locally or via TestFlight
4version: 1.0.0
5license: MIT
6---
7 
8Use EAS Build to create development clients for testing native code changes on physical devices. Use this for creating custom Expo Go clients for testing branches of your app.
9 
10## Important: When Development Clients Are Needed
11 
12**Only create development clients when your app requires custom native code.** Most apps work fine in Expo Go.
13 
14You need a dev client ONLY when using:
15- Local Expo modules (custom native code)
16- Apple targets (widgets, app clips, extensions)
17- Third-party native modules not in Expo Go
18 
19**Try Expo Go first** with `npx expo start`. If everything works, you don't need a dev client.
20 
21## EAS Configuration
22 
23Ensure `eas.json` has a development profile:
24 
25```json
26{
27  "cli": {
28    "version": ">= 16.0.1",
29    "appVersionSource": "remote"
30  },
31  "build": {
32    "production": {
33      "autoIncrement": true
34    },
35    "development": {
36      "autoIncrement": true,
37      "developmentClient": true
38    }
39  },
40  "submit": {
41    "production": {},
42    "development": {}
43  }
44}
45```
46 
47Key settings:
48- `developmentClient: true` - Bundles expo-dev-client for development builds
49- `autoIncrement: true` - Automatically increments build numbers
50- `appVersionSource: "remote"` - Uses EAS as the source of truth for version numbers
51 
52## Building for TestFlight
53 
54Build iOS dev client and submit to TestFlight in one command:
55 
56```bash
57eas build -p ios --profile development --submit
58```
59 
60This will:
611. Build the development client in the cloud
622. Automatically submit to App Store Connect
633. Send you an email when the build is ready in TestFlight
64 
65After receiving the TestFlight email:
661. Download the build from TestFlight on your device
672. Launch the app to see the expo-dev-client UI
683. Connect to your local Metro bundler or scan a QR code
69 
70## Building Locally
71 
72Build a development client on your machine:
73 
74```bash
75# iOS (requires Xcode)
76eas build -p ios --profile development --local
77 
78# Android
79eas build -p android --profile development --local
80```
81 
82Local builds output:
83- iOS: `.ipa` file
84- Android: `.apk` or `.aab` file
85 
86## Installing Local Builds
87 
88Install iOS build on simulator:
89 
90```bash
91# Find the .app in the .tar.gz output
92tar -xzf build-*.tar.gz
93xcrun simctl install booted ./path/to/App.app
94```
95 
96Install iOS build on device (requires signing):
97 
98```bash
99# Use Xcode Devices window or ideviceinstaller
100ideviceinstaller -i build.ipa
101```
102 
103Install Android build:
104 
105```bash
106adb install build.apk
107```
108 
109## Building for Specific Platform
110 
111```bash
112# iOS only
113eas build -p ios --profile development
114 
115# Android only
116eas build -p android --profile development
117 
118# Both platforms
119eas build --profile development
120```
121 
122## Checking Build Status
123 
124```bash
125# List recent builds
126eas build:list
127 
128# View build details
129eas build:view
130```
131 
132## Using the Dev Client
133 
134Once installed, the dev client provides:
135- **Development server connection** - Enter your Metro bundler URL or scan QR
136- **Build information** - View native build details
137- **Launcher UI** - Switch between development servers
138 
139Connect to local development:
140 
141```bash
142# Start Metro bundler
143npx expo start --dev-client
144 
145# Scan QR code with dev client or enter URL manually
146```
147 
148## Troubleshooting
149 
150**Build fails with signing errors:**
151```bash
152eas credentials
153```
154 
155**Clear build cache:**
156```bash
157eas build -p ios --profile development --clear-cache
158```
159 
160**Check EAS CLI version:**
161```bash
162eas --version
163eas update
164```
165