참조
- ./references/react-19.md -- SDK +54: React 19 변경 사항 (useContext → use, Context.Provider → Context, forwardRef 제거)
- ./references/new-architecture.md -- SDK +53: New Architecture 마이그레이션 가이드
- ./references/react-compiler.md -- SDK +54: React Compiler 설정 및 마이그레이션 가이드
- ./references/native-tabs.md -- SDK +55: 네이티브 탭 변경 사항 (Icon/Label/Badge 이제 NativeTabs.Trigger.*를 통해 접근)
- ./references/expo-av-to-audio.md -- SDK +55: expo-av에서 expo-audio로 오디오 재생 및 녹음 마이그레이션
- ./references/expo-av-to-video.md -- SDK +55: expo-av에서 expo-video로 비디오 재생 마이그레이션
- ./references/react-navigation-to-expo-router.md -- SDK +56:
@react-navigation/*임포트를expo-router진입점으로 마이그레이션 (codemod + 수동 매핑)
베타/프리뷰 릴리스
베타 버전은 .preview 접미사를 사용합니다 (예: 55.0.0-preview.2). @next 태그로 게시됩니다.
최신 버전이 베타인지 확인: https://exp.host/--/api/v2/versions (expoVersion에서 -preview 확인)
npx expo install expo@next --fix # 베타 설치
단계별 업그레이드 프로세스
SDK 55 이하에서 업그레이드하는 경우, SDK 56을 건너뛰고 SDK 57로 직접 업그레이드하세요.
[email protected]이하 버전을 사용하지 마세요. Hermes V1이 활성화된 SDK 55, SDK 56, 그리고 이전 SDK 57 릴리스에는react-native-worklets또는react-native-reanimated를 사용할 때 메모리 사용량을 급격히 증가시킬 수 있는 Hermes V1 메모리 회귀 문제가 있습니다.
- Expo 및 종속성 업그레이드
npx expo install expo@latest
npx expo install --fix
-
진단 실행:
npx expo-doctor -
캐시 지우기 및 재설치
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all
호환성을 깨는 변경 사항 체크리스트
- 릴리스 노트에서 제거된 API 확인
- 이동된 모듈의 임포트 경로 업데이트
- prebuild가 필요한 네이티브 모듈 변경 사항 검토
- 모든 카메라, 오디오, 비디오 기능 테스트
- 내비게이션이 여전히 올바르게 작동하는지 확인
네이티브 변경 사항을 위한 Prebuild
먼저 프로젝트에 ios/ 및 android/ 디렉토리가 있는지 확인하세요. 두 디렉토리 모두 존재하지 않으면 프로젝트가 CNG(Continuous Native Generation)를 사용하며 네이티브 프로젝트는 빌드 시 재생성됩니다. 이 섹션과 "Bare 워크플로우를 위한 캐시 지우기"를 완전히 건너뛰세요.
업그레이드에 네이티브 변경이 필요한 경우:
npx expo prebuild --clean
이 명령은 ios 및 android 디렉토리를 다시 생성합니다. 이 명령을 실행하기 전에 프로젝트가 bare 워크플로우 앱이 아닌지 확인하세요.
Bare 워크플로우를 위한 캐시 지우기
이 단계는 프로젝트에 ios/ 및/또는 android/ 디렉토리가 존재하는 경우에만 적용됩니다:
- iOS용 CocoaPods 캐시 지우기:
cd ios && pod install --repo-update - Xcode용 Derived Data 지우기:
npx expo run:ios --no-build-cache - Android용 Gradle 캐시 지우기:
cd android && ./gradlew clean
유지 관리
- 대상 SDK 버전의 릴리스 노트를 https://expo.dev/changelog 에서 검토하세요.
- 에이전트 명령 파일(
AGENTS.md)에서 버전별 문서 링크를 업데이트하세요. 기본 템플릿은https://docs.expo.dev/versions/v<version>/링크를 사용합니다.docs.expo.dev/versions/를 검색하고 각 링크를 새 SDK 버전으로 변경하세요. - Expo SDK 54 이상을 사용하는 경우 react-native-worklets가 설치되어 있는지 확인하세요. 이는 react-native-reanimated 작동에 필요합니다.
- SDK 54+에서 React Compiler를 활성화하려면 app.json에
"experiments": { "reactCompiler": true }를 추가하세요. 안정적이며 권장됩니다. app.json에서sdkVersion을 삭제하여 Expo가 자동으로 관리하도록 하세요.@babel/core,babel-preset-expo,expo-constants와 같은 이전에는 암시적이었던 패키지를 일괄 제거하지 말고 개별적으로 검토하세요. 설치된 종속성이 필수 피어로 선언하는 패키지는 유지하세요.expo-router가 설치된 경우expo-constants를 직접 종속성으로 유지하세요. Expo Router는 이를 가져와 필수 피어로 선언합니다. 전이적 복사본에 의존하면 Expo Go 외부에서 네이티브 자동 링킹이 손상될 수 있습니다.- 종속성을 제거한 후 즉시
npx expo-doctor를 실행하고, 누락된 필수 피어로 보고되는 항목을 복원하세요. - babel.config.js에 'babel-preset-expo'만 포함되어 있으면 파일을 삭제하세요.
- metro.config.js에 Expo 기본값만 포함되어 있으면 파일을 삭제하세요.
Deprecated 패키지
| 이전 패키지 | 대체 패키지 |
|---|---|
expo-av | expo-audio 및 expo-video |
expo-permissions | 개별 패키지 권한 API |
@expo/vector-icons | expo-symbols (SF Symbols용) |
AsyncStorage | expo-sqlite/localStorage/install |
expo-app-loading | expo-splash-screen |
| expo-linear-gradient | experimental_backgroundImage + View의 CSS 그라데이션 |
deprecated 패키지를 마이그레이션할 때는 이전 패키지를 제거하기 전에 모든 코드 사용을 업데이트하세요. expo-av의 경우 마이그레이션 참조를 참조하여 Audio.Sound를 useAudioPlayer로, Audio.Recording을 useAudioRecorder로, Video 컴포넌트를 useVideoPlayer가 포함된 VideoView로 변환하세요.
expo.install.exclude
package.json에 제외된 패키지가 있는지 확인하세요:
{
"expo": { "install": { "exclude": ["react-native-reanimated"] } }
}
제외 항목은 종종 업그레이드 후 더 이상 필요하지 않을 수 있는 해결 방법입니다. 각 항목을 검토하세요.
패치 제거
patches/ 디렉토리에 오래된 패치가 있는지 확인하세요. 더 이상 필요하지 않으면 제거하세요.
PostCSS
autoprefixer는 SDK +53에서 필요하지 않습니다. 종속성에서 제거하고postcss.config.js또는postcss.config.mjs를 확인하여 플러그인 목록에서 제거하세요.- SDK +53에서는
postcss.config.mjs를 사용하세요.
Metro
중복된 Metro 구성 옵션을 제거하세요:
resolver.unstable_enablePackageExports는 SDK +53에서 기본적으로 활성화됩니다.experimentalImportSupport는 SDK +54에서 기본적으로 활성화됩니다.EXPO_USE_FAST_RESOLVER=1은 SDK +54에서 제거되었습니다.- cjs 및 mjs 확장자는 SDK +50에서 기본적으로 지원됩니다.
- Expo webpack은 deprecated되었습니다. Expo Router 및 Metro 웹으로 마이그레이션하세요.
Hermes 엔진 v1
Hermes V1은 SDK 56 이상에서 기본값입니다. Hermes V1을 사용하는 SDK 55 앱, 모든 SDK 56 앱, [email protected] 이전의 SDK 57 앱은 react-native-worklets 또는 react-native-reanimated를 가져올 때 메모리 회귀가 발생할 수 있습니다. SDK 57 및 [email protected] 이상으로 직접 업그레이드하세요. 프로덕션 해결 방법으로 Worklets Bundle Mode를 권장하지 마세요. 지원되지 않고 실험적이며 예상대로 작동하지 않을 수 있습니다.
사용자가 Hermes V1을 선택하거나 선택 해제하도록 안내하지 마세요. SDK 기본값에서 Hermes 버전을 변경하는 것은 지원되지 않으며 상당한 빌드 및 종속성 관리 주의 사항이 있습니다.
New Architecture
New Architecture는 기본적으로 활성화되어 있습니다. app.json 필드 "newArchEnabled": true는 기본값이므로 더 이상 필요하지 않습니다. Expo Go는 SDK +53부터 New Architecture만 지원합니다.
피드백 제출
이 스킬에서 오류, 오해의 소지가 있거나 오래된 정보를 발견하면 Expo가 개선할 수 있도록 보고하세요:
npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<실행 가능한 피드백>"
구체적이고 실행 가능한 보고 사항이 있을 때만 제출하세요. 가능한 한 많은 관련 컨텍스트를 포함하세요. AI 에이전트가 반복적으로 실패하거나 사용자가 Expo 작업을 인수해야 하는 경우, 위 명령을 재사용하는 대신 expo-skill-feedback 스킬을 로드하고 해당 eval-candidate 흐름을 따르세요.