expo-upgrade
Framework (OSS). Guidelines for upgrading Expo SDK versions and fixing dependency issues
- License 许可
- MIT
- 最近更新
- 2026-09-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- expo-upgrade
- license
- MIT
- version
- 1.0.0
- description
- Framework (OSS). Guidelines for upgrading Expo SDK versions and fixing dependency issues
02 资源文件 8
- 参考文档agents/openai.yaml373 B
- 参考文档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
- 参考文档references/react-navigation-to-expo-router.md4.1 KB
03 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
- 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
- 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 - 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.
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.
Submitting Feedback
If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<actionable feedback>"
Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
04 同仓库更多 Skills
widget-custom-fonts
Bundle custom fonts into iOS widget extensions (expo-widgets) — expo-font only covers the main app target, not the widget extension
troubleshoot
Known bugs, quirks, and their fixes discovered during development
set-app-identity
Sweep every file that carries app identity (name, bundle id, scheme, URLs, emails, entitlement IDs, DB filename, EAS project, theme colors) and update them in one consistent pass when renaming/rebranding an expo-starter project. Use when the user says 'rename the app', 'rebrand', 'change app identity', 'update bundle id', 'set up identity for a new project', 'customize the template', or otherwise needs to replace the placeholder identity shipped with expo-starter. Covers app.config.ts BASE_* constants, package.json name, constants/index WEB_URL, lib/mail SUPPORT_EMAIL, constants/revenuecat ENTITLEMENT_ID, db/app/index DB filename, maestro appId, paywall plan names, tailwind theme colors, and EAS project config.
react-native-best-practices
Software Mansion's best practices for production React Native and Expo apps on the New Architecture. MUST USE before writing, reviewing, or debugging ANY code in a React Native or Expo project. If the working directory contains a package.json with react-native, expo, or expo-router as a dependency, this skill applies. Trigger on: any code task in a React Native/Expo project, 'React Native', 'Expo', 'New Architecture', 'Reanimated', 'Gesture Handler', 'react-native-svg', 'ExecuTorch', 'react-native-audio-api', 'react-native-enriched', 'Worklet', 'Fabric', 'TurboModule', 'WebGPU', 'react-native-wgpu', 'TypeGPU', 'GPU shader', 'WGSL', 'svg', 'animation', 'gesture', 'audio', 'rich text', 'AI model', 'multithreading', 'chart', 'vector', 'image filter', 'shared value', 'useSharedValue', 'runOnJS', 'scheduleOnRN', 'thread', 'worklet', 'Bundle Mode', or any question involving UI, graphics, native modules, or React Native threading and animation behavior. Also use when a more specific sub-skill matches.
motion-design
Applies motion design principles to create emotionally-driven, technically sound animations and transitions. Provides timing, easing, choreography, and Disney animation principles adapted for UI. Use when creating animations, transitions, micro-interactions, loading states, page transitions, scroll-triggered effects, or any motion work. Works with CSS, Framer Motion, GSAP, Lottie, Spring, or any animation system.
expo-web-to-native
Framework (OSS). Migrate an existing web React app to a native iOS/Android app with Expo. Use when the user wants to turn a website into a mobile app, port a Next.js/Vite/CRA React codebase to React Native, reuse web code on native incrementally, or asks how web idioms (the DOM, CSS, React Router, localStorage, window) map to native. This is the end-to-end migration guide; use the `expo-dom` skill for the DOM-component mechanism itself.