upgrading-expo
Guidelines for upgrading Expo SDK versions and fixing dependency issues
- License 许可
- MIT
- 最近更新
- 2026-09-02
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- upgrading-expo
- license
- MIT
- version
- 1.0.0
- description
- Guidelines for upgrading Expo SDK versions and fixing dependency issues
02 资源文件 25
- 参考文档references/expo-av-to-audio.md3.6 KB
- 参考文档references/expo-av-to-video.md4.2 KB
- 参考文档references/native-tabs.md3.4 KB
- 参考文档references/new-architecture.md2.1 KB
- 参考文档references/react-19.md1.8 KB
- 参考文档references/react-compiler.md1.6 KB
- 脚本tools/_shared/test-helpers.ts1.6 KB
- 脚本tools/decay-warnings-list/handler.test.ts2.4 KB
- 脚本tools/decay-warnings-list/handler.ts2.6 KB
- 参考文档tools/decay-warnings-list/tool.json1.5 KB
- 脚本tools/delete-relationship/handler.test.ts5.6 KB
- 脚本tools/delete-relationship/handler.ts4.7 KB
- 参考文档tools/delete-relationship/tool.json1.2 KB
- 脚本tools/memory-confirm/handler.test.ts3.1 KB
- 脚本tools/memory-confirm/handler.ts2.9 KB
- 参考文档tools/memory-confirm/tool.json729 B
- 脚本tools/memory-query/handler.test.ts16.2 KB
- 脚本tools/memory-query/handler.ts6.6 KB
- 参考文档tools/memory-query/tool.json1.5 KB
- 脚本tools/memory-store/handler.test.ts48.1 KB
- 脚本tools/memory-store/handler.ts21.3 KB
- 参考文档tools/memory-store/tool.json5.3 KB
- 脚本tools/query-relationships/handler.test.ts7.8 KB
- 脚本tools/query-relationships/handler.ts3.3 KB
- 参考文档tools/query-relationships/tool.json1.1 KB
03 SKILL.md 正文
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 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
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
- 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.jsonto 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
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.
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.
04 同仓库更多 Skills
validate-skills
Validates skills in this repo against agentskills.io spec and Claude Code best practices. Use via /validate-skills command.
use-dom
Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally.
upgrading-react-native
React Native upgrade workflow covering updated templates, dependencies, and common pitfalls. Use when migrating a React Native app to a newer release.
react-native-best-practices
Provides React Native performance optimization guidelines for FPS, TTI, bundle size, memory leaks, re-renders, and animations. Applies to tasks involving Hermes optimization, JS thread blocking, bridge overhead, FlashList, native modules, or debugging jank and frame drops.
native-data-fetching
Use when implementing or debugging ANY network request, API call, or data fetching. Covers fetch API, axios, React Query, SWR, error handling, caching strategies, offline support.
github
GitHub patterns using gh CLI for pull requests, stacked PRs, code review, branching strategies, and repository automation. Use when working with GitHub PRs, merging strategies, or repository management tasks.