The Bulletproof Guide to Setting Up Expo EAS & OTA Updates (Without the Tears)

Setting up Expo Application Services (EAS) and Over-The-Air (OTA) updates for the first time feels like unlocking a developer superpower. The promise is incredible: ship bug fixes directly to your users' phones instantly, completely bypassing the App Store review process.

But if you set it up incorrectly, that superpower quickly turns into a nightmare of instant crashes, poisoned update channels, and the dreaded White Screen of Death (WSOD).

I recently navigated this minefield while building a production React Native app using Supabase and RevenueCat. I learned the hard way that the gap between local development and cloud builds is filled with hidden traps.

If you are setting up EAS and expo-updates from scratch, this step-by-step guide will ensure you get it right on the very first try.

Step 1: Master Your Environment Variables

This is where 90% of developers fail on their first EAS build. In local development, your app magically reads your .env file. In the cloud, your .env file is ignored (thanks to .gitignore), leaving your API keys blank and crashing your app on launch.

The Golden Rules of Expo Environments:

1. The Prefix: Any API key that your frontend React Native code needs to read (like your Supabase URL or RevenueCat Public Key) must start with EXPO_PUBLIC_. If it doesn't, the Metro bundler will actively strip it out of your production build for security.
2. The Local File: Keep a single .env.local file on your machine for development.

Your .env.local should look like this:

EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
EXPO_PUBLIC_REVENUECAT_IOS_API_KEY=appl_your_key

Upload to the Cloud:
Before you ever trigger a build, you must upload these exact variables to the EAS servers so they can be injected into your production app. Run these commands in your terminal:

eas env:create --name EXPO_PUBLIC_SUPABASE_URL --value "https://your-project.supabase.co" --environment production --visibility plaintext
eas env:create --name EXPO_PUBLIC_SUPABASE_ANON_KEY --value "your-anon-key" --environment production --visibility plaintext

Check your work by running eas env:list --environment production.

Step 2: Bulletproof Your app.json

EAS runs strict validation checks on your project manifest. If you have sloppy configuration, your OTA updates will be rejected at the 99% mark.

1. Keep it DRY (Don't Repeat Yourself): Scroll through your app.json. Ensure you do not have duplicate entries in your iOS UIBackgroundModes, Android permissions, or intentFilters.
2. Lock in the Runtime Version: OTA updates need to know which native binary they belong to. Add a strict runtime version to your app.json:

{
  "expo": {
    "name": "MyApp",
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://u.expo.dev/YOUR-PROJECT-ID"
    }
  }
}

Step 3: Configure eas.json Correctly

When you initialize EAS (via eas init), it generates an eas.json file. You need to explicitly tell your production profile to pull down the cloud environment variables you set up in Step 1, and map the build to an update channel.

Edit your eas.json to look like this:

{
  "build": {
    "production": {
      "channel": "production",
      "environment": "production"
    }
  }
}

Note: The "environment": "production" line is the magic link that pulls your eas env keys into the build.

Step 4: The Local Safety Check

Do not skip this step. Waiting 30 minutes in the EAS cloud queue just to discover your app crashes on launch is a brutal loop.

Because you are likely using custom native code, you can compile and test the true production release right on your local machine.

Run this command:

npx expo run:ios --configuration Release

(Or run:android --variant Release)

If the app boots up on your simulator, connects to your database, and doesn't white-screen, your JavaScript and native configurations are rock solid.

Step 5: The First Cloud Build

Now you are ready for the cloud. Trigger your first production build for TestFlight or the Google Play Console:

eas build --profile production --platform all

A Warning About Local Builds: If you try to save queue time by running eas build --local, the EAS CLI will ignore your local .env and will not reach out to the cloud to get your eas env variables. It will build a blank app. Always use the cloud build for your first clean run, or run eas env:pull before attempting a local EAS build.

Step 6: Pushing Your First OTA Update Safely

Once your app is live on TestFlight or the App Store, you will eventually want to push a bug fix over the air.

Unlike eas build (which happens in the cloud), eas update bundles your JavaScript locally on your computer before uploading it. This means it relies entirely on your local terminal's environment variables.

If your Metro bundler has stale cache, it might bundle your app without your EXPO_PUBLIC_ keys, resulting in a "poisoned" update that instantly crashes your users' apps.

The Golden Command for OTA Updates:
Always force Metro to clear its cache when pushing to production so it strictly reads your .env.local file:

eas update --branch production --clear-cache

Provide an update message when prompted, and within seconds, your users will download the fresh, bug-free JavaScript bundle the next time they open the app.

Summary

By moving your client keys to eas env, cleaning up your app.json, and respecting the Metro cache during eas update, you completely eliminate the friction of modern app deployment. You can now build, iterate, and ship OTA updates with total confidence.

[ignore keywords:
"How to set up Expo EAS from scratch"

"Expo OTA updates complete beginner guide"

"How to use environment variables in EAS build"

"Expo runtime version best practices"

"EAS build local vs cloud environment variables"

"How to trigger safe expo updates"

"React Native build production ipa and aab"

"Preventing poisoned OTA updates in Expo"
]