Guides
Plan-enterprise-icon
Expo Application Services
API Reference

Updates

The expo-updates library allows you to programmatically control and respond to new updates made available to your app.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb
Status-success-iconStatus-success-iconStatus-success-iconStatus-success-iconStatus-failed-icon

Installation

Terminal
→ npx expo install expo-updates

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

Most of the methods and constants in this module can only be used or tested in release mode. In debug builds, the default behavior is to always load the latest JavaScript from a development server. It is possible to build a debug version of your app with the same updates behavior as a release build. Such an app will not open the latest JavaScript from your development server — it will load published updates just as a release build does. This may be useful for debugging the behavior of your app when it is not connected to a development server.
To test manual updates in the Expo Go app, run eas update and then open the published version of your app with Expo Go.
To test manual updates with standalone apps, you can create a simulator build or APK, or make a release build locally with npx expo run:ios --configuration Release and npx expo run:android --variant release (you don't need to submit this build to the store to test).

Using expo-updates with a custom server

Every custom updates server must implement the Expo Updates protocol.
You can find an example implementation of a custom server and an app using that server in the custom-expo-updates-server repository.

Configuration options

There are build-time configuration options that control the behavior of expo-updates.
On Android, these options are set as meta-data tags adjacent to the tags added during installation in the AndroidManifest.xml file. You can also define these options at runtime by passing a Map as the second parameter of UpdatesController.initialize(), and the provided values will override any value specified in AndroidManifest.xml.
On iOS, these properties are set as keys in Expo.plist file. You can also set them at runtime by calling [UpdatesController.sharedInstance setConfiguration:] at any point before calling start or startAndShowLaunchScreen, and the values in this dictionary will override any values specified in Expo.plist.
iOS plist/dictionary keyAndroid Map keyAndroid meta-data nameDefaultRequired?
EXUpdatesEnabledenabledexpo.modules.updates.ENABLEDtrueStatus-failed-icon
EXUpdatesURLupdateUrlexpo.modules.updates.EXPO_UPDATE_URL(none)Status-success-icon
EXUpdatesRequestHeadersrequestHeadersexpo.modules.updates.UPDATES_CONFIGURATION_REQUEST_HEADERS_KEY(none)Status-failed-icon
EXUpdatesSDKVersionsdkVersionexpo.modules.updates.EXPO_SDK_VERSION(none)(exactly one of sdkVersion or runtimeVersion is required, Required for apps hosted on Expo's server)
EXUpdatesRuntimeVersionruntimeVersionexpo.modules.updates.EXPO_RUNTIME_VERSION(none)(exactly one of sdkVersion or runtimeVersion is required)
EXUpdatesReleaseChannelreleaseChannelexpo.modules.updates.EXPO_RELEASE_CHANNELdefaultStatus-failed-icon
EXUpdatesCheckOnLaunchcheckOnLaunchexpo.modules.updates.EXPO_UPDATES_CHECK_ON_LAUNCHALWAYS (ALWAYS, NEVER, WIFI_ONLY, ERROR_RECOVERY_ONLY)Status-failed-icon
EXUpdatesLaunchWaitMslaunchWaitMsexpo.modules.updates.EXPO_UPDATES_LAUNCH_WAIT_MS0Status-failed-icon
EXUpdatesCodeSigningCertificatecodeSigningCertificateexpo.modules.updates.CODE_SIGNING_CERTIFICATE(none)Status-failed-icon
EXUpdatesCodeSigningMetadatacodeSigningMetadataexpo.modules.updates.CODE_SIGNING_METADATA(none)Status-failed-icon
EXUpdatesCodeSigningIncludeManifestResponseCertificateChaincodeSigningIncludeManifestResponseCertificateChainexpo.modules.updates.CODE_SIGNING_INCLUDE_MANIFEST_RESPONSE_CERTIFICATE_CHAINfalseStatus-failed-icon
EXUpdatesConfigCodeSigningAllowUnsignedManifestscodeSigningAllowUnsignedManifestsexpo.modules.updates.CODE_SIGNING_ALLOW_UNSIGNED_MANIFESTSfalseStatus-failed-icon
For a detailed explanation, see the expo-updates repository.

API

import * as Updates from 'expo-updates';

Constants

Updates.channel

Type: string | null

The channel name of the current build, if configured for use with EAS Update. Null otherwise.

Updates.createdAt

Type: Date | null

If expo-updates is enabled, this is a Date object representing the creation time of the update that's currently running (whether it was embedded or downloaded at runtime).

In development mode, or any other environment in which expo-updates is disabled, this value is null.

Updates.isEmbeddedLaunch

Type: boolean

This will be true if the currently running update is the one embedded in the build, and not one downloaded from the updates server.

Updates.isEmergencyLaunch

Type: boolean

expo-updates does its very best to always launch monotonically newer versions of your app so you don't need to worry about backwards compatibility when you put out an update. In very rare cases, it's possible that expo-updates may need to fall back to the update that's embedded in the app binary, even after newer updates have been downloaded and run (an "emergency launch"). This boolean will be true if the app is launching under this fallback mechanism and false otherwise. If you are concerned about backwards compatibility of future updates to your app, you can use this constant to provide special behavior for this rare case.

Updates.manifest

Type: Partial<Manifest>

If expo-updates is enabled, this is the manifest object for the update that's currently running.

In development mode, or any other environment in which expo-updates is disabled, this object is empty.

Updates.releaseChannel

Type: string

The name of the release channel currently configured in this standalone or bare app when using classic updates. When using Expo Updates, the value of this field is always "default".

Updates.runtimeVersion

Type: string | null

The runtime version of the current build.

Updates.updateId

Type: string | null

The UUID that uniquely identifies the currently running update if expo-updates is enabled. The UUID is represented in its canonical string form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) and will always use lowercase letters. In development mode, or any other environment in which expo-updates is disabled, this value is null.

Methods

Updates.checkForUpdateAsync()

Checks the server to see if a newly deployed update to your project is available. Does not actually download the update. This method cannot be used in development mode, and the returned promise will be rejected if you try to do so.

Checking for an update uses a device's bandwidth and battery life like any network call. Additionally, updates served by Expo may be rate limited. A good rule of thumb to check for updates judiciously is to check when the user launches or foregrounds the app. Avoid polling for updates in a frequent loop.

Returns

  • Undo-iconPromise<UpdateCheckResult>

A promise that fulfills with an UpdateCheckResult object.

The promise rejects if the app is in development mode, or if there is an unexpected error or timeout communicating with the server.

Updates.clearLogEntriesAsync()

Clears existing expo-updates log entries.

Info-icon

For now, this operation does nothing on the client. Once log persistence has been implemented, this operation will actually remove existing logs.

A promise that fulfills if the clear operation was successful.

The promise rejects if there is an unexpected error in clearing the logs.

Updates.fetchUpdateAsync()

Downloads the most recently deployed update to your project from server to the device's local storage. This method cannot be used in development mode, and the returned promise will be rejected if you try to do so.

A promise that fulfills with an UpdateFetchResult object.

The promise rejects if the app is in development mode, or if there is an unexpected error or timeout communicating with the server.

Updates.readLogEntriesAsync(maxAge)

NameTypeDescription
maxAge
(optional)
number

Sets the max age of retrieved log entries in milliseconds. Default to 3600000 ms (1 hour).

Default: 3600000

Retrieves the most recent expo-updates log entries.

A promise that fulfills with an array of UpdatesLogEntry objects;

The promise rejects if there is an unexpected error in retrieving the logs.

Updates.reloadAsync()

Instructs the app to reload using the most recently downloaded version. This is useful for triggering a newly downloaded update to launch without the user needing to manually restart the app.

It is not recommended to place any meaningful logic after a call to await Updates.reloadAsync(). This is because the promise is resolved after verifying that the app can be reloaded, and immediately before posting an asynchronous task to the main thread to actually reload the app. It is unsafe to make any assumptions about whether any more JS code will be executed after the Updates.reloadAsync method call resolves, since that depends on the OS and the state of the native module and main threads.

This method cannot be used in development mode, and the returned promise will be rejected if you try to do so.

A promise that fulfills right before the reload instruction is sent to the JS runtime, or rejects if it cannot find a reference to the JS runtime. If the promise is rejected in production mode, it most likely means you have installed the module incorrectly. Double check you've followed the installation instructions. In particular, on iOS ensure that you set the bridge property on EXUpdatesAppController with a pointer to the RCTBridge you want to reload, and on Android ensure you either call UpdatesController.initialize with the instance of ReactApplication you want to reload, or call UpdatesController.setReactNativeHost with the proper instance of ReactNativeHost.

Event Subscriptions

Updates.addListener(listener)

NameTypeDescription
listener(event: UpdateEvent) => void

A function that will be invoked with an UpdateEvent instance and should not return any value.

Adds a callback to be invoked when updates-related events occur (such as upon the initial app load) due to auto-update settings chosen at build-time.

  • Undo-iconEventSubscription

An EventSubscription object on which you can call remove() to unsubscribe the listener.

Types

UpdateCheckResult

The result of checking for a new update.

Acceptable values are: UpdateCheckResultSuccess, UpdateCheckResultFailure.

UpdateEvent

An object that is passed into each event listener when an auto-update check occurs.

NameTypeDescription
manifest
(optional)
ManifestIf type is Updates.UpdateEventType.UPDATE_AVAILABLE, the manifest of the newly downloaded update, and undefined otherwise.
message
(optional)
stringIf type is Updates.UpdateEventType.ERROR, the error message, and undefined otherwise.
typeUpdateEventTypeType of the event.

UpdateFetchResult

The result of fetching a new update.

Acceptable values are: UpdateFetchResultSuccess, UpdateFetchResultFailure.

UpdatesLogEntry

An object representing a single log entry from expo-updates logging on the client.

NameTypeDescription
assetId
(optional)
stringIf present, the unique ID or hash of an asset associated with this log entry.
codeUpdatesLogEntryCodeOne of the defined code values for expo-updates log entries.
levelUpdatesLogEntryLevelOne of the defined log level or severity values.
messagestringThe log entry message.
stacktrace
(optional)
string[]If present, an iOS or Android native stack trace associated with this log entry.
timestampnumberThe time the log was written, in milliseconds since Jan 1 1970 UTC.
updateId
(optional)
stringIf present, the unique ID of an update associated with this log entry.

Enums

UpdateEventType

The types of update-related events.

UpdateEventType.ERROR = "error"

An error occurred trying to fetch the latest update.

UpdateEventType.NO_UPDATE_AVAILABLE = "noUpdateAvailable"

No updates are available, and the most up-to-date update is already running.

UpdateEventType.UPDATE_AVAILABLE = "updateAvailable"

A new update has finished downloading to local storage. If you would like to start using this update at any point before the user closes and restarts the app on their own, you can call Updates.reloadAsync() to launch this new update.

UpdatesLogEntryCode

The possible code values for expo-updates log entries

UpdatesLogEntryCode.ASSETS_FAILED_TO_LOAD = "AssetsFailedToLoad"
UpdatesLogEntryCode.JS_RUNTIME_ERROR = "JSRuntimeError"
UpdatesLogEntryCode.NONE = "None"
UpdatesLogEntryCode.NO_UPDATES_AVAILABLE = "NoUpdatesAvailable"
UpdatesLogEntryCode.UNKNOWN = "Unknown"
UpdatesLogEntryCode.UPDATE_ASSETS_NOT_AVAILABLE = "UpdateAssetsNotAvailable"
UpdatesLogEntryCode.UPDATE_CODE_SIGNING_ERROR = "UpdateCodeSigningError"
UpdatesLogEntryCode.UPDATE_FAILED_TO_LOAD = "UpdateFailedToLoad"
UpdatesLogEntryCode.UPDATE_HAS_INVALID_SIGNATURE = "UpdateHasInvalidSignature"
UpdatesLogEntryCode.UPDATE_SERVER_UNREACHABLE = "UpdateServerUnreachable"

UpdatesLogEntryLevel

The possible log levels for expo-updates log entries

UpdatesLogEntryLevel.DEBUG = "debug"
UpdatesLogEntryLevel.ERROR = "error"
UpdatesLogEntryLevel.FATAL = "fatal"
UpdatesLogEntryLevel.INFO = "info"
UpdatesLogEntryLevel.TRACE = "trace"
UpdatesLogEntryLevel.WARN = "warn"

Error Codes

CodeDescription
ERR_UPDATES_DISABLEDA method call was attempted when the Updates module was disabled, or the application was running in development mode
ERR_UPDATES_RELOADAn error occurred when trying to reload the application and it could not be reloaded. For bare workflow apps, double check the setup steps for this module to ensure it has been installed correctly and the proper native initialization methods are called.
ERR_UPDATES_CHECKAn unexpected error occurred when trying to check for new updates. Check the error message for more information.
ERR_UPDATES_FETCHAn unexpected error occurred when trying to fetch a new update. Check the error message for more information.
ERR_UPDATES_READ_LOGSAn unexpected error occurred when trying to read log entries. Check the error message for more information.
  • Message-iconAsk a question on the forums about Updates
  • Github-iconView open bug reports for Updates
  • Code-iconView source code for Updates
  • Build-iconView package in npm Registry
  • Edit-iconEdit this page

Was this doc helpful?