Expo Upgrade

## References

- ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal) - ./references/new-architecture.md -- SDK +53: New Architecture migration guide - ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide - ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.\*) - ./references/expo-av-to-audio.md -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio - ./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video - ./references/react-navigation-to-expo-router.md -- SDK +56: Migrate `@react-navigation/*` imports to `expo-router` entry points (codemod + manual mapping)

## Beta/Preview Releases

Beta versions use `.preview` suffix (e.g., `55.0.0-preview.2`), published under `@next` tag.

Check if latest is beta: https://exp.host/--/api/v2/versions (look for `-preview` in `expoVersion`)

```bash npx expo install expo@next --fix # install beta ```

## Step-by-Step Upgrade Process

> If upgrading from SDK 55 or earlier, skip SDK 56 and upgrade directly to SDK 57. Don't use `expo@57.0.8` or below. SDK 55 with Hermes V1 enabled, SDK 56, and older SDK 57 releases contain a Hermes V1 memory regression that can drastically increase memory usage when using `react-native-worklets` or `react-native-reanimated`.

1. Upgrade Expo and dependencies

```bash npx expo install expo@latest npx expo install --fix ```

2. Run diagnostics: `npx expo-doctor`

3. Clear caches and reinstall

```bash npx expo export -p ios --clear rm -rf node_modules .expo watchman watch-del-all ```

## Breaking Changes Checklist

- Check for removed APIs in release notes - Update import paths for moved modules - Review native module changes requiring prebuild - Test all camera, audio, and video features - Verify navigation still works correctly

## Prebuild for Native Changes

**First check if `ios/` and `android/` directories exist in the project.** If neither directory exists, the project uses Continuous Native Generation (CNG) and native projects are regenerated at build time — skip this section and "Clear caches for bare workflow" entirely.

If upgrading requires native changes:

```bash npx expo prebuild --clean ```

This regenerates the `ios` and `android` directories. Ensure the project is not a bare workflow app before running this command.

## Clear caches for bare workflow

These steps only apply when `ios/` and/or `android/` directories exist in the project:

- Clear the cocoapods cache for iOS: `cd ios && pod install --repo-update` - Clear derived data for Xcode: `npx expo run:ios --no-build-cache` - Clear the Gradle cache for Android: `cd android && ./gradlew clean`

## Housekeeping

- Review release notes for the target SDK version at https://expo.dev/changelog - Update versioned docs links in agent instruction files (`AGENTS.md`). The default template links to `https://docs.expo.dev/versions/v<version>/`. Search for `docs.expo.dev/versions/` and bump each link to the new SDK version. - If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work. - Enable React Compiler in SDK 54+ by adding `"experiments": { "reactCompiler": true }` to app.json — it's stable and recommended - Delete sdkVersion from `app.json` to let Expo manage it automatically - Review formerly implicit packages such as `@babel/core`, `babel-preset-expo`, and `expo-constants` individually instead of removing them wholesale. Keep any package that an installed dependency declares as a required peer. - Keep `expo-constants` as a direct dependency whenever `expo-router` is installed. Expo Router imports it and declares it as a required peer; relying on a transitive copy can break native autolinking outside Expo Go. - After removing any dependency, immediately run `npx expo-doctor` and restore anything it reports as a missing required peer. - If the babel.config.js only contains 'babel-preset-expo', delete the file - If the metro.config.js only contains expo defaults, delete the file

## Deprecated Packages

| Old Package | Replacement | | -------------------- | ---------------------------------------------------- | | `expo-av` | `expo-audio` and `expo-video` | | `expo-permissions` | Individual package permission APIs | | `@expo/vector-icons` | `expo-symbols` (for SF Symbols) | | `AsyncStorage` | `expo-sqlite/localStorage/install` | | `expo-app-loading` | `expo-splash-screen` | | expo-linear-gradient | experimental_backgroundImage + CSS gradients in View |

When migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound