An SDK upgrade changes more than one version in package.json. Expo, React Native, native modules, navigation entry points, and build configuration must remain compatible. Expo-upgrade organizes those checks into a migration based on the actual project.
Connect Expo knowledge to your agent
For Codex, run the official Expo plugin command below in a terminal or find Expo through /plugins. For Claude Code, use claude plugin install expo@claude-plugins-official instead. Both plugin installs include Expo Skills and MCP configuration. Other Agent Skills clients can run npx skills@latest add expo/skills --skill '*', choose their client, and refresh the session. Installing the plugin does not itself build or publish an app.
codex plugin add expo@openai-curated
Open the existing Expo project and explicitly request expo-upgrade, including the SDK version, target platforms, and relevant files.
Inventory before choosing a target
Adapt this first request to your project:
Use expo-upgrade to assess this project. Inventory its SDK, React Native version, native-directory ownership, patches, and dependency exclusions, then plan the migration from target-version release notes. Do not blindly clear native directories. Align dependencies, run doctor, and verify login, navigation, camera, and media.
Read dependencies, lockfiles, app configuration, and native directories. Identify generated files versus manually maintained native code. Record existing checks and important behavior, especially camera, audio, video, and navigation. Evaluate patches and dependency exclusions individually; their age alone does not establish that they can be removed.
Expo's general upgrade guide recommends incremental versions, while the current skill documents a specific exception for older SDKs affected by a Hermes V1 memory regression. It recommends skipping SDK 56 in that situation and using the specified fixed SDK 57 release or later. Do not reduce the process to a permanent rule of either one version at a time or always latest. Compare the applicable version conditions with the target release notes.
Align dependencies and address diagnostics
After choosing the target, update the Expo package for that version, then run npx expo install --fix and npx expo-doctor. If diagnostics identify a missing peer dependency, restore or add it as appropriate rather than assuming a formerly indirect package is unnecessary. Preserve the project's package manager and lockfile conventions.
Migrate actual API uses before removing old packages. An audio or video library migration may change components and hooks as well as package names. Navigation imports, Babel, and Metro configuration should also follow the target SDK rather than examples from another release.
Handle native projects deliberately
Generated native directories can follow the regeneration workflow. Manually maintained native projects need their local changes preserved and the corresponding native upgrade differences applied. Clearing caches and deleting directories should not replace diagnosis or code migration.
Rebuild the native runtime where required, then exercise login, navigation, media, and permission flows. Opening one screen in Expo Go does not establish that the application's native build has compatible dependencies. Useful deliverables include the version changes, deprecated APIs addressed, diagnostic results, and checks still requiring a device. Those concrete outcomes make the migration reviewable and give it a clear stopping point.
Manage the migration with a version matrix
Before changing packages, list Expo SDK, React Native, Expo Router, major native libraries, and build configuration, with a column showing whether each is still used. Compare that matrix with the target release notes and mark whether each item needs a package update, API change, native rebuild, or verification only. This avoids deleting an older dependency merely because it looks old, while preventing obsolete patches from hiding problems.
A clean doctor report is not the finish line. Run the project's tests and check login, deep links, camera, media, and notifications on a development build when the app uses them. Preserve and review changes in manually maintained ios or android directories; regeneration can erase them. Record any device behavior that remains unverified for the release checklist.
Leave a rollback boundary at each stage
Save the pre-upgrade state, then work through dependencies, configuration, API migration, and native builds in stages. Record changes and diagnostics at each step so a regression can be traced. The skill's exceptions for particular SDKs must be applied only after checking the project's starting version. For an app with existing users, test persisted data, permission requests, and notification links; a fresh installation may hide migration failures.
Split a difficult version jump into reviewable stages
One Expo user found a direct SDK 54→56 upgrade hard to untangle, then completed 54→55→56 with Claude Code and an upgrade agent recommended in Expo Skills to align dependencies. Their main delay was an iOS Swift 6/JSI issue rather than package edits. Keep diagnostics and native build results at each stage. This is one project’s experience, not a universal rule to upgrade every intermediate version; check target-release exceptions first.