---
id: sm-upgrading-expo
name: "upgrading-expo"
url: https://skills.yangsir.net/skill/sm-upgrading-expo
author: expo
domain: ai-frontend-engineering
tags: ["expo-updates", "react-native-upgrades", "mobile-app-maintenance", "dependency-management", "version-control"]
install_count: 30000
rating: 4.60 (572 reviews)
github: https://github.com/expo/skills
---

# upgrading-expo

> 此技能集提供AI代理能力，专门用于协助Expo项目的升级过程，简化版本迁移和兼容性处理，确保移动应用平稳过渡到新版本。

**Stats**: 30,000 installs · 4.6/5 (572 reviews)

## Before / After 对比

### Expo 项目升级前后的兼容性和功能性

| Metric | Before | After | Change |
|---|---|---|---|
| - | - | - | - |
| - | - | - | - |
| - | - | - | - |
| - | - | - | - |

## Readme

# upgrading-expo

## 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](https://exp.host/--/api/v2/versions) (look for `-preview` in `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](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](https://docs.expo.dev/router/migrate/from-expo-webpack/).

## 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.
Weekly Installs12.5KRepository[expo/skills](https://github.com/expo/skills)GitHub Stars1.5KFirst SeenJan 19, 2026Security Audits[Gen Agent Trust HubPass](/expo/skills/upgrading-expo/security/agent-trust-hub)[SocketPass](/expo/skills/upgrading-expo/security/socket)[SnykPass](/expo/skills/upgrading-expo/security/snyk)Installed onopencode9.2Kgithub-copilot9.1Kcodex9.0Kgemini-cli8.7Kcursor8.7Kclaude-code7.3K

---
*Source: https://skills.yangsir.net/skill/sm-upgrading-expo*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-upgrading-expo/markdown*