Expo SDK upgrade
Upgrades an Expo app to a newer SDK: expo install --fix, expo-doctor, prebuild and cache steps only where native folders exist, deprecated package swaps and per-SDK migration notes. Use when bumping the Expo SDK or fixing dependency conflicts after one.
expo-upgrade- Author
- Expo
- Source
- expo/skills/plugins/expo/skills/expo-upgrade @ 88d9bd7
- License
- MIT · Copyright (c) 2025-present 650 Industries, Inc. (aka Expo)
About this skill
What it does
The skill is Expo's runbook for moving an app to a newer SDK. The core steps are npx expo install expo@latest, npx expo install --fix, npx expo-doctor, then clearing caches. The agent first checks for ios/ and android/: without them the project uses Continuous Native Generation and the prebuild and native cache steps are skipped; with them it may run npx expo prebuild --clean (not on a bare workflow app) and clear CocoaPods, Xcode and Gradle caches. Preview releases come from the @next tag.
The skill carries one version warning: an app on SDK 55 or earlier should skip SDK 56 and go straight to SDK 57 at [email protected] or later, because of a Hermes V1 memory regression with Reanimated and Worklets. The agent must not suggest switching Hermes versions as a workaround.
Housekeeping: remove sdkVersion, enable React Compiler on SDK 54+, keep expo-constants next to Expo Router, rerun expo-doctor after each removed dependency, delete default-only Babel and Metro configs, review install exclusions and old patches, bump versioned docs links in AGENTS.md. A table maps deprecated packages to replacements, for example expo-av to expo-audio and expo-video; code is migrated before the old package is removed.
References, each tied to an SDK: react-19.md (54), new-architecture.md (53), react-compiler.md (54), native-tabs.md (55), expo-av-to-audio.md and expo-av-to-video.md (55), and react-navigation-to-expo-router.md (56), with the expo-codemod command and a manual import map.
When to use it, and when not
Use it for an SDK bump, dependency conflicts after one, or moving off deprecated Expo packages. Expo and EAS overview sends any SDK change here instead of bumping versions by hand. It is not meant for React Native projects without Expo. It has no branch or rollback step, so commit before starting.
How to run it
The install command below puts the whole folder in place. The agent picks the skill up by its description; to call it yourself:
- Claude Code:
/expo-upgrade, or ask for the skill by name. - Codex:
$expo-upgrade. - Cursor: type
/in the Agent chat and pickexpo-upgrade.
Example: /expo-upgrade Move this app from SDK 54 to the latest stable SDK and replace expo-av.
How it differs from similar skills
Deprecation and migration from Addy Osmani is about retiring your own systems and APIs and moving their users; it has nothing on Expo. Upgrade Prisma ORM to v7 is the same kind of version-specific runbook for another tool. No other skill in the catalog, React Native best practices included, covers Expo or React Native upgrades.
Install
Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.
curl -fsSL --create-dirs -o ~/.claude/skills/expo-upgrade/SKILL.md https://anymodel.org/en/skills/expo/expo-upgrade/SKILL.md -o ~/.claude/skills/expo-upgrade/LICENSE https://anymodel.org/en/skills/expo/expo-upgrade/LICENSE -o ~/.claude/skills/expo-upgrade/agents/openai.yaml https://anymodel.org/en/skills/expo/expo-upgrade/agents/openai.yaml -o ~/.claude/skills/expo-upgrade/references/expo-av-to-audio.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-audio.md -o ~/.claude/skills/expo-upgrade/references/expo-av-to-video.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-video.md -o ~/.claude/skills/expo-upgrade/references/native-tabs.md https://anymodel.org/en/skills/expo/expo-upgrade/references/native-tabs.md -o ~/.claude/skills/expo-upgrade/references/new-architecture.md https://anymodel.org/en/skills/expo/expo-upgrade/references/new-architecture.md -o ~/.claude/skills/expo-upgrade/references/react-19.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-19.md -o ~/.claude/skills/expo-upgrade/references/react-compiler.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-compiler.md -o ~/.claude/skills/expo-upgrade/references/react-navigation-to-expo-router.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-navigation-to-expo-router.md
curl -fsSL --create-dirs -o ~/.agents/skills/expo-upgrade/SKILL.md https://anymodel.org/en/skills/expo/expo-upgrade/SKILL.md -o ~/.agents/skills/expo-upgrade/LICENSE https://anymodel.org/en/skills/expo/expo-upgrade/LICENSE -o ~/.agents/skills/expo-upgrade/agents/openai.yaml https://anymodel.org/en/skills/expo/expo-upgrade/agents/openai.yaml -o ~/.agents/skills/expo-upgrade/references/expo-av-to-audio.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-audio.md -o ~/.agents/skills/expo-upgrade/references/expo-av-to-video.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-video.md -o ~/.agents/skills/expo-upgrade/references/native-tabs.md https://anymodel.org/en/skills/expo/expo-upgrade/references/native-tabs.md -o ~/.agents/skills/expo-upgrade/references/new-architecture.md https://anymodel.org/en/skills/expo/expo-upgrade/references/new-architecture.md -o ~/.agents/skills/expo-upgrade/references/react-19.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-19.md -o ~/.agents/skills/expo-upgrade/references/react-compiler.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-compiler.md -o ~/.agents/skills/expo-upgrade/references/react-navigation-to-expo-router.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-navigation-to-expo-router.md
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','references/expo-av-to-audio.md','references/expo-av-to-video.md','references/native-tabs.md','references/new-architecture.md','references/react-19.md','references/react-compiler.md','references/react-navigation-to-expo-router.md') { $p = Join-Path "$HOME\.claude\skills\expo-upgrade" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/expo/expo-upgrade/$f" -UseBasicParsing -OutFile $p }foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','references/expo-av-to-audio.md','references/expo-av-to-video.md','references/native-tabs.md','references/new-architecture.md','references/react-19.md','references/react-compiler.md','references/react-navigation-to-expo-router.md') { $p = Join-Path "$HOME\.agents\skills\expo-upgrade" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/expo/expo-upgrade/$f" -UseBasicParsing -OutFile $p }Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/expo/expo-upgrade/SKILL.md
SKILL.md
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 toexpo-routerentry 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)
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
[email protected]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 usingreact-native-workletsorreact-native-reanimated.
- Upgrade Expo and dependencies
npx expo install expo@latest
npx expo install --fix
Run diagnostics:
npx expo-doctorClear caches and reinstall
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:
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 tohttps://docs.expo.dev/versions/v<version>/. Search fordocs.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.jsonto let Expo manage it automatically - Review formerly implicit packages such as
@babel/core,babel-preset-expo, andexpo-constantsindividually instead of removing them wholesale. Keep any package that an installed dependency declares as a required peer. - Keep
expo-constantsas a direct dependency wheneverexpo-routeris 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-doctorand 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 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
autoprefixerisn't needed in SDK +53. Remove it from dependencies and checkpostcss.config.jsorpostcss.config.mjsto remove it from the plugins list.- Use
postcss.config.mjsin SDK +53.
Metro
Remove redundant metro config options:
- resolver.unstable_enablePackageExports is enabled by default in SDK +53.
experimentalImportSupportis enabled by default in SDK +54.EXPO_USE_FAST_RESOLVER=1is removed in SDK +54.- cjs and mjs extensions are supported by default in SDK +50.
- Expo webpack is deprecated, migrate to Expo Router and Metro web.
Hermes engine v1
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 [email protected] may encounter a memory regression when importing react-native-worklets or react-native-reanimated. Upgrade directly to SDK 57 and [email protected] 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.
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.
Submitting Feedback
You can voluntarily report errors, misleading or outdated information in this skill, so Expo can improve it:
npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-upgrade" --message "<actionable feedback>"
Use --category agent-cli for a problem with the agent CLI, and --category evals when an agent repeatedly fails at an Expo task. Run feedback --help for subjects and the data that the command sends.
Each report goes to Expo with project and environment details. Show the user the message, and send it only if the user agrees. If you cannot ask the user, do not send it. Do not include secrets or personal data.
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel