This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Learn how to install and configure expo-updates in your existing React Native project.

expo-updates is a library that enables your app to manage remote updates to your application code. It communicates with the configured remote update service to get information about available updates. This guide explains how to set up an existing React Native project for use with EAS Update, a hosted remote update service that includes tools to simplify installation and configuration of the expo-updates library.

Installation

To get started, install expo-updates:

Then, install pods for iOS:

Configuring expo-updates library

Apply the changes from the diffs from the following sections to configure expo-updates in your project.

JavaScript and JSON

Run eas update:configure to set the updates URL and projectId in app.json.

Modify the expo section of app.json. If you created your project using npx @react-native-community/cli@latest init, you will need to add the following changes including the updates URL.

The example updates URL and projectId shown below are used with EAS Update. The EAS CLI sets this URL correctly for the EAS Update service when running eas update:configure.

If you want to set up a custom expo-updates server instead, add your URL to updates.url in app.json.

Android

Modify android/app/build.gradle to check for the JS engine configuration (JSC or Hermes) in Expo files:

Modify android/app/src/main/AndroidManifest.xml to add the expo-updates configuration XML so that it matches the contents of app.json:

If using the updates server URL (a custom non-HTTPS update server running on the same machine), you will need to modify android/app/src/main/AndroidManifest.xml to add the update server URL and enable usesCleartextTraffic:

Add the Expo runtime version string key to android/app/src/main/res/values/strings.xml:

iOS

Add the file Podfile.properties.json to the ios directory:

{
  "expo.jsEngine": "hermes"
}

Modify ios/Podfile to check for the JS engine configuration (JSC or Hermes) in Expo files:

Using Xcode, add Expo.plist file to ios/your-project/Supporting with the following content to match the contents of app.json:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>EXUpdatesCheckOnLaunch</key>
    <string>ALWAYS</string>
    <key>EXUpdatesEnabled</key>
    <true/>
    <key>EXUpdatesLaunchWaitMs</key>
    <integer>0</integer>
    <key>EXUpdatesRuntimeVersion</key>
    <string>1.0.0</string>
    <key>EXUpdatesURL</key>
    <string>http://localhost:3000/api/manifest</string>
  </dict>
</plist>

Configuring the update channel at build time

The channel property on a build allows you to point updates at specific types of builds. For example, it allows you to publish updates to a preview build without impacting your production deployment.

This property is also ultimately set in the AndroidManifest.xml and Expo.plist files you modified above. It is usually set right before build, so you can switch between production and non-production builds. If you build your project with EAS Build, the channel is set in the eas.json build profile. EAS Build then applies it to these files right before the native build step.

When you build locally or with another service, you need to set the channel yourself in these files:

Android

In android/app/src/main/AndroidManifest.xml, add the request headers meta-data entry inside the <application> element:

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

iOS

In Expo.plist, add the EXUpdatesRequestHeaders dictionary inside the existing <dict> element:

<key>EXUpdatesRequestHeaders</key>
<dict>
  <key>expo-channel-name</key>
  <string>your-channel-name</string>
</dict>

If you later adopt CNG, you can configure the channel with updates.requestHeaders in app.json instead. Running npx expo prebuild in your pipeline then writes the channel into these files. See Configure update channels in app.json.

Next steps

• To start using EAS Update with EAS Build, see the EAS Update Get started.
• See expo-updates API reference for more information on how to use the library.
• See how to use EAS Update with a local build directly.
• It is also possible to use expo-updates with a custom server that implements the Expo Updates protocol. See custom-expo-updates-server README.