Upgrade Expo SDK Safely

This skill walks through an Expo SDK upgrade end to end. It starts with the core upgrade commands (npx expo install expo@latest and npx expo install --fix), then runs npx expo-doctor for diagnostics, and clears caches by re-exporting, deleting node_modules/.expo, and running watchman watch-del-all. It covers checking for beta/preview releases (versions with a .preview suffix, published under the @next tag) via npx expo install expo@next --fix.

It also gives a breaking-changes checklist: check release notes for removed APIs, update import paths for moved modules, review native module changes, and test camera/audio/video features. For native changes it explains when npx expo prebuild --clean applies (only if ios//android/ directories already exist - projects using Continuous Native Generation skip this and the bare-workflow cache-clearing steps entirely), and lists bare-workflow cache clearing for CocoaPods, Xcode derived data, and Gradle.

Housekeeping guidance covers reviewing per-SDK release notes, installing react-native-worklets for SDK 54+ (required by react-native-reanimated), enabling React Compiler via the experiments.reactCompiler app.json flag, removing the sdkVersion field from app.json, and pruning now-implicit packages (@babel/core, babel-preset-expo, expo-constants) along with now-unnecessary babel.config.js/metro.config.js files. A deprecated-packages table maps expo-av to expo-audio/expo-video, expo-permissions to individual permission APIs, @expo/vector-icons to expo-symbols, AsyncStorage to expo-sqlite/localStorage/install, expo-app-loading to expo-splash-screen, and expo-linear-gradient to experimental_backgroundImage with CSS gradients. It also links per-version reference docs for React 19 changes, New Architecture migration, React Compiler setup, native tabs, expo-av migration, and a React Navigation to Expo Router migration.

Use it when bumping an Expo project to a newer SDK release, especially when the jump touches native modules, camera/audio/video code, or navigation. It is not a substitute for the target SDK's own release notes - the skill's own limitations note says to verify commands, API behavior, and deprecations against current official documentation before making changes, and not to treat its examples as a stand-in for environment-specific tests or approval on destructive changes.

Input is an existing Expo project on an older SDK version, plus its package.json, app.json, and (for bare-workflow apps) ios//android/ directories. Output is an upgraded dependency tree, expo-doctor-clean diagnostics, cleared build caches, and a completed breaking-changes checklist covering removed APIs, updated import paths, and tested native features.

npx expo install expo@latest
npx expo install --fix

Works through the Expo CLI (npx expo install, npx expo-doctor, npx expo export, npx expo prebuild, npx expo run:ios), Metro bundler config (resolver.unstable_enablePackageExports, experimentalImportSupport, removal of EXPO_USE_FAST_RESOLVER), PostCSS config (dropping autoprefixer on SDK 53+, preferring postcss.config.mjs), CocoaPods, Xcode, Gradle, and watchman. Covers opting into Hermes engine v1 via the expo-build-properties config plugin and a matching hermes-compiler package version, and the New Architecture, which is on by default (the newArchEnabled app.json field is no longer needed).

Expo and React Native developers maintaining a production app who need to move it to a new SDK release without breaking native modules, navigation, or media playback.