Menu
Framework (OSS). Guidelines for upgrading Expo SDK versions and fixing dependency issues
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/expo/skills --skill expo-upgradeThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Framework (OSS). Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.
EAS service (paid). Run and control a user's app on a remote iOS/Android simulator hosted on EAS cloud. Read before running any `eas simulator:*` commands - it has the current syntax for this experimental API. Use whenever the user needs a simulator they can't run locally - 'run my app on a cloud simulator', 'use eas simulator to run/install/screenshot my app', 'I'm on Linux/Cursor and need an iOS device', 'no sim on this box / headless CI', 'let an agent click through my app and screenshot it', 'test my dev build on a remote sim with live reload', 'stream a sim to my browser' - even when they don't say 'EAS Simulator' or 'cloud'. On a host WITHOUT a local simulator (Linux, CI, cloud sandbox) it's the default; on macOS, do NOT auto-trigger for a plain 'run on the simulator' - use it only for a cloud/remote/shareable sim, an iOS version they lack, or an agent-driven session. NOT for local sims (expo run:ios, Xcode, Android Studio), EAS Build/Update, web preview, or physical devices.
EAS service (paid). Helps understand and write EAS workflow YAML files for Expo projects. Use this skill when the user asks about CI/CD or workflows in an Expo or EAS context, mentions .eas/workflows/, or wants help with EAS build pipelines or deployment automation.
Based on SOC occupation classification
Showing SKILL.md
| name | expo-upgrade |
| description | Framework (OSS). Guidelines for upgrading Expo SDK versions and fixing dependency issues |
| version | 1.0.0 |
| license | MIT |
@react-navigation/* imports to expo-router entry points (codemod + manual mapping)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
If upgrading from SDK 55 or earlier, skip SDK 56 and upgrade directly to SDK 57. Don't use
expo@57.0.8or 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 usingreact-native-workletsorreact-native-reanimated.
npx expo install expo@latest
npx expo install --fix
Run diagnostics: npx expo-doctor
Clear caches and reinstall
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all
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.
These steps only apply when ios/ and/or android/ directories exist in the project:
cd ios && pod install --repo-updatenpx expo run:ios --no-build-cachecd android && ./gradlew cleanAGENTS.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."experiments": { "reactCompiler": true } to app.json — it's stable and recommendedapp.json to let Expo manage it automaticallypackage.json: @babel/core, babel-preset-expo, expo-constants.| 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 to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.
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.
Check if there are any outdated patches in the patches/ directory. Remove them if they are no longer needed.
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.postcss.config.mjs in SDK +53.Remove redundant metro config options:
experimentalImportSupport is enabled by default in SDK +54.EXPO_USE_FAST_RESOLVER=1 is removed in SDK +54.Hermes V1 is the default on SDK 56 and later. SDK 55 apps using Hermes V1, all SDK 56 apps, and SDK 57 apps before expo@57.0.9 may encounter a memory regression when importing react-native-worklets or react-native-reanimated. Upgrade directly to SDK 57 and expo@57.0.9 or later. Do not recommend Worklets Bundle Mode as a production workaround; it is unsupported and experimental and may not work as expected.
Do not guide users to opt in to or out of Hermes V1. Changing the Hermes version from the SDK default is unsupported and has significant build and dependency-management caveats.
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.
If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<actionable feedback>"
Only submit when you have something specific and actionable to report. Include as much relevant context as possible. If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.