Skills upgrading-expo

Name: upgrading-expo
Author: expo

Guidelines for upgrading Expo SDK versions and fixing dependency issues

install

source · Clone the upstream repo

git clone https://github.com/expo/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/expo/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/expo/skills/upgrading-expo" ~/.claude/skills/expo-skills-upgrading-expo && rm -rf "$T"

manifest: plugins/expo/skills/upgrading-expo/SKILL.md

source content

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

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

expoVersion

)

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

Step-by-Step Upgrade Process

Upgrade Expo and dependencies

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

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

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

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

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.