eas-update

216 notes in this subject, read out of this brain and free to use. This is page 3 of 4.

Build layers: native and update

Builds consist of two layers: a native layer that is built into the app's binary, and an update layer that is swappable with other compatible updates. This separation allows bug fixes to be shipped to builds as long as the update can run on the native layer inside the build.

Runtime version purpose

The runtime version describes the JS-native interface defined by the native code layer that runs the app's update layer. It is defined in a project's app config. Whenever changes are made to native code that change the app's JS-native interface, the runtime version must be updated.

Publishing updates with eas update --auto

To publish an update, run 'eas update --auto'. This command creates a local update bundle in the dist directory, then uploads that bundle to EAS servers in a database object named a branch. A branch contains a list of updates where the most recent update is the active update on the branch.

EAS Update policy for matching updates and builds

EAS' update policy requires three conditions to be met: (1) The platform of the build and the target platform of an update must match exactly. (2) The runtime version of the build and the target runtime version of an update must match exactly. (3) A channel can be linked to any branch. By default, a channel is linked to a branch of the same name.

Default channel-to-branch linking

By default, channels are auto-linked to branches of the same name. If you create builds with the channel named 'production', you can publish updates to a branch named 'production' and your builds will get updates from that branch automatically, without manual linking.

expo-updates library in builds

When an Expo project that includes expo-updates is built, the included native Android and iOS code is responsible for managing, fetching, parsing, and validating updates.

Default expo-updates checking behavior

By default, the expo-updates library checks for an update when the app is opened. If an update newer than the currently running update is found, it downloads and runs the newer update. If no newer update is found, it runs the newest downloaded update, falling back to the update embedded in the app at build time if none have been downloaded.

expo-updates two-phase download process

expo-updates downloads updates in two phases. First, it downloads the most recent update manifest, which contains information about the update including a list of assets (images, JavaScript bundles, font files, and so on) required to run the update. Second, the library downloads the assets specified in the manifest that it has not yet downloaded from prior updates.

fallbackToCacheTimeout behavior

If the library is able to download the manifest and all required assets before the fallbackToCacheTimeout setting, the new update runs immediately upon launch. If the library cannot fetch the manifest and assets within fallbackToCacheTimeout, it continues downloading in the background and runs the update upon the next launch.

expo-updates configuration

When and how the expo-updates library checks for updates and downloads them is configurable through the project's app config.

Keep updates small for performance

To help end-users get updates quickly and reliably, updates should be kept as small as possible.

Android EAS Update configuration in AndroidManifest.xml

When running 'eas update:configure' in a project without CNG, the android/app/src/main/AndroidManifest.xml file receives two meta-data entries: 'expo.modules.updates.EXPO_UPDATE_URL' with value 'https://u.expo.dev/your-project-id' and 'expo.modules.updates.EXPO_RUNTIME_VERSION' with value '@string/expo_runtime_version'.

Android EAS Update configuration in strings.xml

After running 'eas update:configure', the android/app/src/main/res/values/strings.xml file contains an 'expo_runtime_version' string entry in the resources object.

iOS EAS Update configuration in Expo.plist

When running 'eas update:configure' in a project without CNG, the ios/project-name/Supporting/Expo.plist file receives two entries: 'EXUpdatesRuntimeVersion' with value '1.0.0' (as a string) and 'EXUpdatesURL' with value 'https://u.expo.dev/your-project-id'.

EAS Update availability and pricing

EAS Update is available to anyone with an Expo account, regardless of whether you pay for EAS or use the Free plan. Paid subscribers can publish updates to more users and use more bandwidth and storage.

EAS Update can be used without EAS Build

EAS Update is available as a standalone service and does not require EAS Build. While it is recommended to follow the EAS Build setup guide before setting up EAS Update, you can use EAS Update without any other EAS services.

eas update command syntax

Publish an update using 'eas update --channel [channel-name] --message "[message]" --environment [environment-name]'. The --environment flag is required in SDK 55 and later to specify which EAS environment variables to use.

How eas update command works

The 'eas update' command generates a new update bundle and uploads it to EAS servers. The channel name locates the correct branch to publish from, similar to how Git commits work on branches. Behind the scenes, it runs 'npx expo export' to generate a dist directory and create a local update bundle, which is then uploaded to EAS Update servers.

Test published updates methods

After uploading an update to EAS Update, test it using one of these methods: the Extensions tab in a development build, Expo Orbit to install and launch in a development build, Updates API and app config to load updates programmatically, or manually by force closing and reopening a release build up to two times to download and apply the update.

EAS Update works with projects from different bootstrapping tools

EAS Update works well with projects created by npx create-react-native-app, npx react-native, ignite-cli, and other project bootstrapping tools, in addition to npx create-expo-app.

eas update:configure command purpose

The 'eas update:configure' command updates your app.json file with the 'runtimeVersion' and 'updates.url' properties, and adds the 'extra.eas.projectId' field if the project was not using any EAS services previously.

Brownfield app definition

A brownfield React Native app is an existing native app where React Native has been integrated alongside native code, as opposed to a greenfield app that is primarily built with React Native from the start.

App Store and Play Store guideline compliance for updates

Updates published via EAS Update must follow App Store and Play Store guidelines, including the content of updates and how they are used. Changes to app behavior typically need to be reviewed according to platform rules, just as they would if writing an app without Expo.

Custom update strategy implementation

By default, expo-updates checks for updates every time the app is loaded. A custom update strategy can be implemented using the Updates API and app config settings.

Monthly active users billing definition

One monthly active user equals one unique installation of an app that downloads at least one update during a billing cycle. An app install that downloads a new update each day of the billing cycle counts as 1 monthly active user. An app install that does not download any new updates counts as 0 monthly active users. Uninstalling and reinstalling an app (downloading updates in each) counts as 2 monthly active users. A single device with two apps from one Expo account, both using updates, counts as 2 monthly active users for that account.

EAS Update with existing React Native projects

EAS Update works with both projects using Continuous Native Generation (CNG) and existing React Native projects that have the expo-updates library installed.

Users do not need to reinstall apps for updates

Updates are downloaded inside the app and applied based on configuration. App users see the new version on their next app launch or reload without needing to reinstall the app.

Native code compatibility with runtime version policies

EAS Update uses runtime version policies to ensure updates are only sent to builds with compatible native code. If native code changes, a new runtime version must be created.

Classic Updates deprecation

The Classic Updates service was available before December 2021 and is now deprecated. New updates cannot be published via 'expo publish', but existing apps will continue to receive Classic Updates that have already been published and are actively used. Transition to EAS Update or use a self-hosted update service instead.

EAS Update purpose and capabilities

EAS Update is a cloud service from EAS (Expo Application Services) that serves updates for projects using the expo-updates library. It enables apps to update their non-native pieces such as JavaScript, styling, and images over-the-air without requiring app store submissions. All apps that include the expo-updates library have the ability to receive updates.

EAS Update in EAS Workflows configuration

EAS Update works with EAS Workflows. After creating a build for Android or iOS, an update job can be added to workflow configuration with type 'update' and parameters including message and channel.

Republish previous updates

If an update is not performing as expected, a previous stable version can be republished on top of the problematic one, similar to making a new commit in version control systems.

EAS Update quick start installation

To install EAS Update, run 'npx expo install expo-updates' (or yarn/pnpm/bun equivalent) followed by 'eas update:configure'. A new build for Android or iOS must be created to include the expo-updates library in your build. After that, you can push an update to the production channel using 'eas update --channel production --message "message text"'.

Updates JavaScript API useUpdates hook

The Updates JavaScript API includes a React hook called useUpdates() that provides detailed information about the currently running update and any new updates that are available or have been downloaded. It also displays any errors encountered during the update process. The API also provides methods such as checkForUpdateAsync() and fetchUpdateAsync() which allow control over when the app checks for and downloads updates.

When to use EAS Update vs EAS Build

Use EAS Update for: fixing bugs or crashes in JavaScript code, updating copy/translations/UI styling/screen layouts, rolling out changes to a percentage of users, publishing updates from CI/automated workflows, and testing updates with internal teams. Use EAS Build instead for: changing native code, changing app permissions, updating the Expo SDK version, or anything requiring a new app binary version.

Constants.manifest no longer available

Remove any code that references `Constants.manifest`. It will now always return `null`. Instead, use `Constants.expoConfig` from the `expo-constants` library to access the properties you need.

SDK 49 last version supporting Classic Updates

SDK 49 was the last version to support Classic Updates. To continue using the deprecated `expo publish` command, set `updates.useClassicUpdates` in your app config.

Publish update command

After making code changes locally, publish an update using the command: `eas update --channel [channel-name] --message [message]`. Example: `eas update --channel production --message "Fixes typo"`.

View published updates in EAS dashboard

After publishing an update with `eas update`, you can view the update in the EAS dashboard at https://expo.dev/accounts/[account]/projects/[project]/updates.

Replace expo publish with eas update in scripts

Replace all instances of `expo publish` with `eas update` in your build and deployment scripts. Use `eas update --help` to view all available options for publishing updates.

Replace Updates.releaseChannel with Updates.channel

If your code references `Updates.releaseChannel` from the `expo-updates` library, replace it with `Updates.channel`.

Asset proxy server requirements

The proxy server for update asset requests (JavaScript bundles, images, and so on) must forward requests to assets.eascdn.net (the EAS Update asset server), pass-through all URL contents (path, query parameters, and so on), and forward all request headers that start with 'expo-' or 'eas-', or are exactly 'authorization' or 'a-im'.

Manifest proxy server requirements

The proxy server for update manifest requests must forward requests to u.expo.dev (the EAS Update server), pass-through all URL contents (path, query parameters, and so on), and pass-through all headers prefixed with 'expo-' or 'eas-'.

eas update:configure command for proxying

After adding updateAssetHostOverride and updateManifestHostOverride fields to eas.json, run the command 'eas update:configure' to apply the changes.

Testing request proxying setup

To test request proxying, publish an update using 'eas update' command. Then verify by navigating to the update group on the EAS Update dashboard at https://expo.dev/accounts/[account]/projects/[project]/updates and clicking 'View Metadata' for one of the platforms. The manifest.json should show the overridden manifestHostOverride, and other assets should show the overridden assetHostOverride.

EAS Update request proxying overview

EAS Update supports request proxying, which allows you to proxy requests to the EAS Update server through your own server. This is useful for adding custom headers, logging requests, implementing additional security measures, or implementing request IP anonymization.

EAS Update works independently of EAS Build

EAS Update is designed to function as a standalone service and can be used independently of EAS Build and other EAS services. It is used in production by large organizations that do not use other EAS services.

Downsides of EAS Update without other EAS services

When using EAS Update independently, bookkeeping and insights features that depend on knowledge of builds or other aspects of your app are not available. However, many organizations already have heavy investment in their own CI/CD infrastructure or other reasons for using alternative build pipelines.

Deployments section requires EAS Build integration

When using EAS Build, builds that share the same channel and runtime version are grouped into a Deployments section on expo.dev. This bookkeeping and insights feature is not available if you use EAS Update independently of other EAS services.

Manual channel configuration when not using EAS Build

When using EAS Update without EAS Build, the update channel must be configured manually by setting the request header in the app config, followed by manually creating the channel on the server using the eas channel:create command. When using EAS Build, the channel from eas.json is automatically added to AndroidManifest.xml and Expo.plist at build time.

Create EAS Update channel via CLI

Use the command 'eas channel:create production' to create a channel named 'production' that points to the production EAS Update branch by default. Channel names may vary depending on your release process.

Builds have two layers: native and update

Builds can be thought of as two layers: a native layer that is built into the app's binary and cannot be changed, and an update layer that is swappable with other compatible updates. The runtimeVersion property allows guaranteeing that an update is compatible with a specific build's native code.

Runtime version guarantees build-update compatibility

Runtime versions are a property that guarantees compatibility between a build's native code and an update. When a project is made into a build, the build contains native code that cannot be changed with an update. Therefore, an update must be compatible with a build's native code to run on it.

Gradual rollout strategy for uncertain updates

If unsure about the impact of a new update, roll it out to a small group of users first using rollouts. Publish the update to a small percentage of users and monitor the error rate on the EAS dashboard. If high error rates are noticed, cancel the rollout. If it was already rolled out fully, use rollbacks to revert it.

Test updates on preview builds before production

When deploying to production, create a preview build that uses the same runtime version but points to a different channel. Test updates on those builds before promoting them to production. Alternatively, opt in certain users of the app to receive the update with channel surfing to test updates with a smaller group before full production release.

Must create new build when native code changes before publishing update

Since updates must be compatible with a build's native code, any time native code is updated, a new build must be made before publishing an update. The timing of when to update native code varies by developer: some only update when upgrading to a new Expo SDK, while others upgrade between builds or at other intervals.

Runtime version policies automate version derivation

To manage the runtimeVersion property between builds and updates, policies are available that derive the runtime version from other information already present in a project. These policies are documented in the expo-updates library documentation. If these policies do not match a project's development flow, there is an option to set runtimeVersion manually.

Custom runtime version in app config

You can set a custom runtime version manually in the app config. Example: { "expo": { "runtimeVersion": "1.0.0" } }. This option is good for developers who want to manage the runtime version manually, separately from any other version numbers in the project's app config, giving complete control over which updates are compatible with which builds.

Platform-specific runtime version configuration

Runtime version can be set per-platform. Example for Android: { "expo": { "android": { "runtimeVersion": "1.0.0" } } } or { "expo": { "android": { "runtimeVersion": { "policy": "appVersion" } } } }. When both a top-level runtime version and a platform-specific runtime version are set, the platform-specific one takes precedence.

Risk of incompatible updates with unchanged runtime version

If native code is updated (such as installing a new native library like expo-camera) but the runtimeVersion property is not updated, builds with the old runtime version will incorrectly think an incoming update is compatible. This causes the update to load and attempt calls to code that does not exist in the build. The expo-updates library may detect this error and roll back to the previously working update.

Give your agent this brain