HomeGuidesReferenceLearn
ArchiveExpo SnackDiscord and ForumsNewsletter

Use EAS Update in an existing project

Learn how to use EAS Update in an existing React Native project.


EAS Update works with bare React Native projects created with react-native init. These projects have android and ios directories that you can modify native files directly.

The steps for configuring a bare React Native project are identical to the steps for configuring an Expo project. However, you may need to edit some of the code eas update:configure generates depending on how you build and run your project.

App config

The eas update:configure will add two values to your project's app config.

app.json
{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://u.expo.dev/..."
      %%placeholder-start%%... %%placeholder-end%%
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
}

The runtimeVersion property guarantees compatibility between a build's native code and an update. It's necessary to set this value manually whenever you make a change to any native code in your project. Read our doc on runtime versions and learn how to avoid publishing bad updates.

The updates.url property is the "https://u.expo.dev" domain followed by your project's ID on EAS servers. If you go to the URL directly, you'll see an error about missing a header. You can see a manifest by adding three query parameters to the URL: runtime-version, channel-name, and platform. If we published an update with a runtime version of 1.0.0, a channel of production, and a platform of android, the full URL you could visit would be similar to this:

https://u.expo.dev/your-project-id?runtime-version=1.0.0&channel-name=production&platform=android

EAS config and native files

To generate the eas.json file, run eas build:configure. This command will create the eas.json file and it will also modify the AndroidManifest.xml file inside the android directory and the Expo.plist file inside the ios directory.

Inside eas.json, you'll want to add channel properties to each build profile you'd like to send updates to. Assuming you're using the default eas.json configuration, we recommend adding channel properties to the preview and production build profiles.

eas.json
{
  "cli": {
    "version": ">= 2.1.0"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal",
      "channel": "preview"
    },
    "production": {
      "channel": "production"
    }
  },
  "submit": {
    "production": {}
  }
}

Inside android/app/src/main/AndroidManifest.xml, you'll see the following additions:

android/app/src/main/AndroidManifest.xml
<meta-data android:name="expo.modules.updates.EXPO_UPDATE_URL" android:value="https://u.expo.dev/your-project-id"/>
<meta-data android:name="expo.modules.updates.EXPO_RUNTIME_VERSION" android:value="@string/expo_runtime_version"/>

Inside android/app/src/main/res/values/strings.xml, you'll see the expo_runtime_version string entry in the resources object:

The EXPO_UPDATE_URL value should contain your project's ID.

Inside ios/project-name/Supporting/Expo.plist, you'll see the following additions:

ios/project-name/Supporting/Expo.plist
<key>EXUpdatesRuntimeVersion</key>
<string>1.0.0</string>
<key>EXUpdatesURL</key>
<string>https://u.expo.dev/your-project-id</string>

The EXUpdatesURL value should contain your project's ID.

Once you have built your project into a build, the expo-updates library will make requests for manifests with the native configuration defined above, along with the channel specified in eas.json.

Configuring the channel manually

If you create a build with EAS Build, the channel name from eas.json will automatically be added to our build's AndroidManifest.xml and Expo.plist at build time. If you're using EAS Build, the following steps are not necessary.

If your project is not using EAS Build or you are creating release builds with either npx expo run:ios --configuration Release or npx expo run:android --variant release, you'll need to set the channel configuration manually inside both AndroidManifest.xml and Expo.plist.

In AndroidManifest.xml, you'll need to add the following, replacing your-channel-name with the channel that matches your project:

android/app/src/main/AndroidManifest.xml
<meta-data android:name="expo.modules.updates.UPDATES_CONFIGURATION_REQUEST_HEADERS_KEY" android:value="{&quot;expo-channel-name&quot;:&quot;your-channel-name&quot;}"/>

In Expo.plist, you'll need to add the following, replacing your-channel-name with the channel that matches your project:

ios/project-name/Supporting/Expo.plist
<key>EXUpdatesRequestHeaders</key>
<dict>
  <key>expo-channel-name</key>
  <string>your-channel-name</string>
</dict>

This configuration is also generated by npx expo prebuild if you set the requestHeaders property in your app.json:

app.json
{
  "expo": {
    %%placeholder-start%%... your existing configuration %%placeholder-end%%
    "updates": {
      %%placeholder-start%%... %%placeholder-end%%
      "requestHeaders": {
        "expo-channel-name": "your-channel-name"
      }
      %%placeholder-start%%... %%placeholder-end%%
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
}

What's next

Once your project is set up with EAS Update, eventually you'll make native changes to your project. Whenever that happens, you'll need to update the runtimeVersion in your project's app config. Once that's done, you'll need to make new builds, after which, you'll be able to send updates with eas update. If your app is not updating as expected, validate your configuration.

Set your own updates service

Some projects have unique requirements that require a self-hosted updates service. Since the expo-updates library is open source and follows the Expo Updates protocol, you can set up a custom server to serve updates to your users.