1---
2name: upgrading-expo
3description: Guidelines for upgrading Expo SDK versions and fixing dependency issues
4version: 1.0.0
5license: MIT
6---
7 
8## References
9 
10- ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
11- ./references/new-architecture.md -- SDK +53: New Architecture migration guide
12- ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide
13- ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.\*)
14- ./references/expo-av-to-audio.md -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio
15- ./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video
16- ./references/react-navigation-to-expo-router.md -- SDK +56: Migrate `@react-navigation/*` imports to `expo-router` entry points (codemod + manual mapping)
17 
18## Beta/Preview Releases
19 
20Beta versions use `.preview` suffix (e.g., `55.0.0-preview.2`), published under `@next` tag.
21 
22Check if latest is beta: https://exp.host/--/api/v2/versions (look for `-preview` in `expoVersion`)
23 
24```bash
25npx expo install expo@next --fix  # install beta
26```
27 
28## Step-by-Step Upgrade Process
29 
301. Upgrade Expo and dependencies
31 
32```bash
33npx expo install expo@latest
34npx expo install --fix
35```
36 
372. Run diagnostics: `npx expo-doctor`
38 
393. Clear caches and reinstall
40 
41```bash
42npx expo export -p ios --clear
43rm -rf node_modules .expo
44watchman watch-del-all
45```
46 
47## Breaking Changes Checklist
48 
49- Check for removed APIs in release notes
50- Update import paths for moved modules
51- Review native module changes requiring prebuild
52- Test all camera, audio, and video features
53- Verify navigation still works correctly
54 
55## Prebuild for Native Changes
56 
57**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.
58 
59If upgrading requires native changes:
60 
61```bash
62npx expo prebuild --clean
63```
64 
65This regenerates the `ios` and `android` directories. Ensure the project is not a bare workflow app before running this command.
66 
67## Clear caches for bare workflow
68 
69These steps only apply when `ios/` and/or `android/` directories exist in the project:
70 
71- Clear the cocoapods cache for iOS: `cd ios && pod install --repo-update`
72- Clear derived data for Xcode: `npx expo run:ios --no-build-cache`
73- Clear the Gradle cache for Android: `cd android && ./gradlew clean`
74 
75## Housekeeping
76 
77- Review release notes for the target SDK version at https://expo.dev/changelog
78- If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.
79- Enable React Compiler in SDK 54+ by adding `"experiments": { "reactCompiler": true }` to app.json — it's stable and recommended
80- Delete sdkVersion from `app.json` to let Expo manage it automatically
81- Remove implicit packages from `package.json`: `@babel/core`, `babel-preset-expo`, `expo-constants`.
82- If the babel.config.js only contains 'babel-preset-expo', delete the file
83- If the metro.config.js only contains expo defaults, delete the file
84 
85## Deprecated Packages
86 
87| Old Package          | Replacement                                          |
88| -------------------- | ---------------------------------------------------- |
89| `expo-av`            | `expo-audio` and `expo-video`                        |
90| `expo-permissions`   | Individual package permission APIs                   |
91| `@expo/vector-icons` | `expo-symbols` (for SF Symbols)                      |
92| `AsyncStorage`       | `expo-sqlite/localStorage/install`                   |
93| `expo-app-loading`   | `expo-splash-screen`                                 |
94| expo-linear-gradient | experimental_backgroundImage + CSS gradients in View |
95 
96When migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.
97 
98## expo.install.exclude
99 
100Check if package.json has excluded packages:
101 
102```json
103{
104  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
105}
106```
107 
108Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.
109## Removing patches
110 
111Check if there are any outdated patches in the `patches/` directory. Remove them if they are no longer needed.
112 
113## Postcss
114 
115- `autoprefixer` isn't needed in SDK +53. Remove it from dependencies and check `postcss.config.js` or `postcss.config.mjs` to remove it from the plugins list.
116- Use `postcss.config.mjs` in SDK +53.
117 
118## Metro
119 
120Remove redundant metro config options:
121 
122- resolver.unstable_enablePackageExports is enabled by default in SDK +53.
123- `experimentalImportSupport` is enabled by default in SDK +54.
124- `EXPO_USE_FAST_RESOLVER=1` is removed in SDK +54.
125- cjs and mjs extensions are supported by default in SDK +50.
126- Expo webpack is deprecated, migrate to [Expo Router and Metro web](https://docs.expo.dev/router/migrate/from-expo-webpack/).
127 
128## Hermes engine v1
129 
130Since SDK 55, users can opt-in to use Hermes engine v1 for improved runtime performance. This requires setting `useHermesV1: true` in the `expo-build-properties` config plugin, and may require a specific version of the `hermes-compiler` npm package. Hermes v1 will become a default in some future SDK release.
131 
132## New Architecture
133 
134The new architecture is enabled by default, the app.json field `"newArchEnabled": true` is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.
135