expo-dev-client

Name: expo-dev-client
Author: Expo Team

ExpoDev ClientEAS BuildNative ModulesMobile DevelopmentReact NativeTestingTestFlight

⭐ 2.1k📄 MIT🕒 2026-06-16Source ↗

Install this skill

npx skills add expo/skills

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

The expo-dev-client library transforms standard Expo projects into custom native applications, providing the necessary infrastructure to manage unique native code. Unlike the standard Expo Go app, which is a pre-compiled binary with a fixed set of native modules, a development client allows developers to bundle their own native dependencies, custom app icons, and specialized Apple targets like widgets or App Clips. It acts as a specialized container for your application code while maintaining the rapid feedback loop of the Metro bundler. By integrating with EAS Build, it provides a mechanism to generate installation binaries for physical testing or store submission, ensuring your app behaves exactly as it will in production while still allowing you to iterate on JavaScript and TypeScript changes instantly via the development server.

When to Use This Skill

•Developing applications that require custom Swift, Kotlin, or C++ code
•Testing native library dependencies not available in the standard Expo Go environment
•Implementing App Clips or Home Screen widgets for iOS
•Testing production-equivalent binary behavior before public release

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“how to use custom native code in expo
“create development client for ios
“why is my native module not working in expo go
“build custom expo app for testing on device
“configure eas for development clients

Pro Tips

💡Always start with `npx expo start` in Expo Go; only create a dev client if native features explicitly fail or are required.
💡Utilize `eas build --profile development --platform ios` (or `android`) to ensure your `eas.json` configuration is correctly applied and the development client is built with the right settings.
💡Integrate dev client builds into your CI/CD pipeline to automate testing of native changes across different environments, ensuring consistent quality.

What this skill does

•Bundles custom native modules directly into the application binary
•Supports integration of Apple targets such as widgets and App Clips
•Enables debugging of projects requiring native third-party libraries
•Provides a local interface for switching between multiple development servers
•Allows cloud-based compilation of binaries via EAS Build for iOS and Android

When not to use it

✕Simple projects that rely entirely on the standard Expo SDK
✕Early prototyping phases where native code is not yet required

Example workflow

Add a custom native dependency to your project
Update eas.json to include a development profile with developmentClient set to true
Trigger a cloud build using eas build --profile development
Download the generated binary to your physical testing device
Start your local Metro bundler with npx expo start --dev-client
Connect the installed app to your machine via QR code or URL

Prerequisites

–EAS CLI installed and authenticated
–An Expo project using SDK 41 or higher
–A physical device for testing
–Developer account access for iOS/Android signing

Pitfalls & limitations

!Requires rebuilds of the native binary whenever native dependencies change
!More complex setup than standard Expo Go due to code signing and credentials
!Longer wait times for build completion compared to standard web or JS-only development

FAQ

Do I need a dev client for every project?

No, only use it if you have custom native modules or specific requirements like App Clips that aren't supported in Expo Go.

Can I build these clients on my own computer?

Yes, you can run local builds using the --local flag if you have the necessary native build tools like Xcode and Android Studio configured.

How does the dev client connect to my code?

It connects to your local Metro bundler via a network URL or QR code, similar to how standard development works in the Expo Go app.

What happens if I forget to add the development profile to eas.json?

The EAS build will likely default to a production configuration, which excludes the native dev client bridge and prevents connecting to your local bundler.

How it compares

While manual native builds require deep knowledge of Xcode or Gradle workflows, this skill abstracts those processes into a standardized configuration, ensuring consistent results across team members.

Source & trust

⭐ 2.1k stars📄 MIT🕒 Updated 2026-06-16

View original skill on GitHub →

📄 Full skill instructions — original source: expo/skills

Use 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.

## Important: When Development Clients Are Needed

**Only create development clients when your app requires custom native code.** Most apps work fine in Expo Go.

You need a dev client ONLY when using:
- Local Expo modules (custom native code)
- Apple targets (widgets, app clips, extensions)
- Third-party native modules not in Expo Go

**Try Expo Go first** with npx expo start. If everything works, you don't need a dev client.

## EAS Configuration

Ensure eas.json has a development profile:

{
  "cli": {
    "version": ">= 16.0.1",
    "appVersionSource": "remote"
  },
  "build": {
    "production": {
      "autoIncrement": true
    },
    "development": {
      "autoIncrement": true,
      "developmentClient": true
    }
  },
  "submit": {
    "production": {},
    "development": {}
  }
}

Key settings:
- developmentClient: true - Bundles expo-dev-client for development builds
- autoIncrement: true - Automatically increments build numbers
- appVersionSource: "remote" - Uses EAS as the source of truth for version numbers

## Building for TestFlight

Build iOS dev client and submit to TestFlight in one command:

eas build -p ios --profile development --submit

This will:
1. Build the development client in the cloud
2. Automatically submit to App Store Connect
3. Send you an email when the build is ready in TestFlight

After receiving the TestFlight email:
1. Download the build from TestFlight on your device
2. Launch the app to see the expo-dev-client UI
3. Connect to your local Metro bundler or scan a QR code

## Building Locally

Build a development client on your machine:

# iOS (requires Xcode)
eas build -p ios --profile development --local

# Android
eas build -p android --profile development --local

Local builds output:
- iOS: .ipa file
- Android: .apk or .aab file

## Installing Local Builds

Install iOS build on simulator:

# Find the .app in the .tar.gz output
tar -xzf build-*.tar.gz
xcrun simctl install booted ./path/to/App.app

Install iOS build on device (requires signing):

# Use Xcode Devices window or ideviceinstaller
ideviceinstaller -i build.ipa

Install Android build:

adb install build.apk

## Building for Specific Platform

# iOS only
eas build -p ios --profile development

# Android only
eas build -p android --profile development

# Both platforms
eas build --profile development

## Checking Build Status

# List recent builds
eas build:list

# View build details
eas build:view

## Using the Dev Client

Once installed, the dev client provides:
- **Development server connection** - Enter your Metro bundler URL or scan QR
- **Build information** - View native build details
- **Launcher UI** - Switch between development servers

Connect to local development:

# Start Metro bundler
npx expo start --dev-client

# Scan QR code with dev client or enter URL manually

## Troubleshooting

**Build fails with signing errors:**

eas credentials

**Clear build cache:**

eas build -p ios --profile development --clear-cache

**Check EAS CLI version:**

eas --version
eas update

By Expo Team

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/expo-dev-client/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/expo/skills/expo-dev-client/SKILL.md
Cursor: ~/.cursor/skills/expo/skills/expo-dev-client/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/expo/skills/expo-dev-client/SKILL.md