Aller au contenu

Index

References

  • ./references/new-architecture.md -- SDK +53: New Architecture migration guide
  • ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
  • ./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 -- Migrate audio playback and recording from expo-av to expo-audio
  • ./references/expo-av-to-video.md -- Migrate video playback from expo-av to expo-video
  • ./references/sdk-55-breaking-changes.md -- SDK 55: Breaking changes, removals, and renames
  • ./references/edge-to-edge.md -- SDK +54: Edge-to-edge mandatory on Android 16+, navigation bar deprecations

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)

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

Step-by-Step Upgrade Process

  1. Upgrade Expo and dependencies
npx expo install expo@latest
npx expo install --fix

  1. Run diagnostics: npx expo-doctor

  2. Clear caches and reinstall

npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all
  1. If using pnpm catalogs, update the react-native catalog versions in pnpm-workspace.yaml

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
  • Check eas update calls for required --environment flag (SDK +55)
  • Review edge-to-edge implications on Android (SDK +54)
  • SDK 56+: expo-calendar root export is the new OO API — legacy free functions (createEventAsync, requestCalendarPermissionsAsync, …) throw at runtime. Migrate to class methods (createCalendar, calendar.createEvent, event.openInCalendar, …); expo-calendar/legacy only as a short-lived bridge (migration guide)

New Package Versioning (SDK +55)

As of SDK 55, all Expo SDK packages use the same major version as the SDK. For example, expo-camera compatible with SDK 55 is ^55.0.0. This makes version compatibility obvious at a glance.

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:

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
  • 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
  • Remove implicit packages from package.json: @babel/core, babel-preset-expo, expo-constants.
  • 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
  • In SDK 55+, remove the newArchEnabled field from app.json entirely (Legacy Architecture no longer exists)
  • In SDK 54+, the statusBar field was removed from app.json — use expo-status-bar package instead
  • In SDK 55+, remove notification field from app.json — use expo-notifications config plugin (throws error in prebuild)
  • In SDK 55+, remove edgeToEdgeEnabled from app.json — edge-to-edge is mandatory on Android 16+
  • In SDK 55+, androidNavigationBar app.json config is deprecated — use expo-navigation-bar config plugin
  • In SDK 55+, androidStatusBar.backgroundColor and androidStatusBar.translucent are deprecated — use expo-status-bar config plugin
  • In SDK 55+, remove experiments.reactCanary flag from app.json (React 19 is the baseline)
  • Minimum iOS version stays 15.1 for SDK 55, but SDK 56 will bump to 16.4

Deprecated Packages

Old Package Replacement Removed In
expo-av expo-audio and expo-video SDK 55
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 (not officially deprecated, alternative only) —
expo-video-thumbnails generateThumbnailsAsync from expo-video SDK 56
expo-background-fetch expo-background-task —
expo-file-system (old) expo-file-system (new API, old at /legacy) SDK 55

When 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.

expo.install.exclude

Check if package.json has excluded packages:

{
  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
}

Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.

Removing patches

Check if there are any outdated patches in the patches/ directory. Remove them if they are no longer needed.

Postcss

  • 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.
  • Use postcss.config.mjs in SDK +53.

Metro

Remove redundant metro config options:

  • resolver.unstable_enablePackageExports is enabled by default in SDK +53.
  • experimentalImportSupport is enabled by default in SDK +54.
  • EXPO_USE_FAST_RESOLVER=1 is removed in SDK +54. In SDK +55 the fast resolver is the only implementation.
  • cjs and mjs extensions are supported by default in SDK +50.
  • Expo webpack is deprecated, migrate to Expo Router and Metro web.
  • expo.experiments.autolinkingModuleResolution is enabled by default in monorepos in SDK +55. If having dependency issues during upgrade, try enabling it explicitly.

Hermes engine v1

Since 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.

New Architecture

The 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.

In SDK 55, Legacy Architecture is fully dropped. The newArchEnabled config option is removed entirely — no opt-out is possible.

Edge-to-Edge (Android)

  • SDK 53: Edge-to-edge enabled by default for new Android projects.
  • SDK 54: Edge-to-edge always enabled (Android 16 / API 36). react-native-edge-to-edge no longer bundled in expo. If using its config plugin, make it a direct dependency.
  • SDK 55: edgeToEdgeEnabled removed from app.json. expo-navigation-bar most methods deprecated and no-op. expo-status-bar backgroundColor/translucent deprecated.

Use expo-navigation-bar and expo-status-bar config plugins instead of app.json fields.

Tool Version Requirements

SDK React Native React Xcode Min Node.js
53 0.79 19.0 16.0 20
54 0.81 19.1 16.1+ 20.19.4
55 0.83 19.2 26 20.19.4