upgrading-expo

upgrading-expo 스킬 개요

upgrading-expo 스킬이 하는 일

upgrading-expo 스킬은 일반적인 “Expo 어떻게 업그레이드하죠?” 같은 질문보다 훨씬 적은 사각지대로 Expo SDK 업그레이드를 계획하고 실행할 수 있게 도와줍니다. 핵심은 실제 업그레이드 작업에 맞춰져 있습니다. 즉, 코어 패키지 업데이트, 의존성 버전 어긋남 해결, 오래된 캐시 정리, 그리고 React, New Architecture, Native Tabs, expo-av 마이그레이션 주변의 자주 발생하는 브레이킹 체인지까지 함께 점검합니다.

upgrading-expo 스킬이 잘 맞는 사용자

이 upgrading-expo skill은 기존 Expo 앱을 유지보수하는 프런트엔드 개발자, React Native 팀, AI 에이전트에 특히 잘 맞습니다. 릴리스 노트 요약이 아니라, 이미 있는 프로젝트를 실제로 업그레이드해야 할 때 가장 유용합니다.

잘 맞는 상황:

• 최근 Expo SDK 버전 사이를 업그레이드할 때
• expo install --fix 이후 설치 또는 런타임 오류를 잡아야 할 때
• expo-av처럼 변경되었거나 분리된 패키지에서 마이그레이션해야 할 때
• React 19나 Native Tabs 같은 SDK별 변경이 현재 코드베이스에 영향을 주는지 확인할 때

실제로 해결하려는 일

upgrading-expo for Frontend Development를 검토하는 사용자는 보통 아래 세 가지를 빨리 알고 싶어 합니다.

1. 먼저 어떤 명령 순서로 실행해야 하는가?
2. 내 앱에서 어떤 브레이킹 체인지가 가장 먼저 터질 가능성이 큰가?
3. 디버깅에 시간 낭비하기 전에 어떤 파일이나 패턴을 먼저 봐야 하는가?

이 스킬의 가치는 이런 판단을 한곳에 묶고, 구체적인 마이그레이션 참고 자료까지 연결해 준다는 데 있습니다.

일반적인 업그레이드 프롬프트와 다른 점

보통의 프롬프트는 “Expo를 올리고 doctor를 돌리세요” 정도를 제안할 수 있습니다. 하지만 upgrading-expo 스킬은 저장소에 정리된 버전 연동 마이그레이션 주제를 더 구체적으로 끌어옵니다. 예를 들면:

• SDK 53+의 New Architecture 기본값
• SDK 54의 React 19 변경사항
• SDK 54+의 React Compiler 설정
• SDK 55의 Native Tabs API 변경
• 오디오/비디오 기준의 expo-av 대체 경로

그래서 광범위한 React Native 트러블슈팅 프롬프트보다, 업그레이드 타깃이 분명한 작업에 더 적합합니다.

설치 전에 알아둘 점

이 스킬은 자동화 중심이라기보다 가이드 중심입니다. 저장소를 자동으로 검사해 주는 스크립트가 들어 있지는 않습니다. 가치의 핵심은 선별된 업그레이드 워크플로와, 이를 자신의 코드베이스에 적용할 수 있게 해 주는 참고 문서에 있습니다. 버튼 한 번으로 끝나는 마이그레이터를 원한다면 이 스킬은 맞지 않습니다. 반대로 신호 대비 잡음이 적은 업그레이드 체크리스트와 구체적인 마이그레이션 예시가 필요하다면 매우 잘 맞습니다.

upgrading-expo 스킬 사용 방법

upgrading-expo 설치 맥락

AI 환경이 Skills를 지원한다면 Expo skills 저장소를 설치한 뒤 그 안에서 upgrading-expo를 호출하면 됩니다. 일반적으로는 다음과 같은 패턴을 사용합니다.

npx skills add https://github.com/expo/skills --skill upgrading-expo

도구 체인이 다른 skill loader를 쓴다면 저장소 경로를 직접 가리키세요:
plugins/expo/skills/upgrading-expo

먼저 봐야 할 저장소 파일 순서

실무적인 upgrading-expo usage를 위해서는 아래 순서대로 읽는 것이 좋습니다.

1. SKILL.md
2. references/new-architecture.md
3. references/react-19.md
4. references/react-compiler.md
5. references/native-tabs.md
6. references/expo-av-to-audio.md
7. references/expo-av-to-video.md

이 순서는 실제 업그레이드에서 가장 자주 막히는 지점을 반영합니다. 먼저 아키텍처와 React 변화, 그다음 기능 단위 마이그레이션입니다.

핵심 업그레이드 순서를 먼저 실행하세요

이 스킬의 기본 업그레이드 흐름은 짧지만, 깊게 디버깅하기 전에 먼저 따라볼 가치가 있습니다.

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

왜 중요하냐면:

• expo@latest가 SDK 기준을 맞춰 주고
• --fix가 Expo 관리 패키지들의 버전을 정렬하며
• expo-doctor가 호환성 문제를 초기에 잡아내고
• 캐시 정리는 업그레이드 버그처럼 보일 수 있는 오래된 Metro/native 상태를 제거해 주기 때문입니다

Linux를 쓰거나 Watchman을 사용하지 않는다면 정리 단계는 환경에 맞게 바꾸면 됩니다.

preview 릴리스를 써야 하는 시점 파악하기

이 스킬은 @next 아래의 .preview 버전을 통한 Expo 베타 빌드도 다룹니다. 아직 stable에 들어오지 않은 수정 사항을 검증하거나, 다가오는 SDK를 미리 테스트할 때 유용합니다.

npx expo install expo@next --fix

다만 이건 의도적으로 할 때만 쓰는 게 좋습니다. preview 업그레이드는 사전 릴리스를 시험하는 상황이 아니라면 프로덕션 앱의 기본 선택지로 적합하지 않습니다.

스킬이 실제로 필요로 하는 입력을 제공하세요

좋은 upgrading-expo guide 프롬프트에는 현재 상태와 목표 상태가 함께 들어 있습니다. 다음 정보를 주면 좋습니다.

• 현재 Expo SDK 버전
• 패키지 매니저
• Expo Go를 쓰는지 development build를 쓰는지
• prebuild를 사용하는지
• 핵심 패키지: expo-router, expo-av, react-native-reanimated, custom native modules
• 설치, 빌드, 런타임에서 현재 발생하는 오류
• iOS, Android, web 중 플랫폼별 실패 여부

이 맥락이 없으면 결과는 쉽게 일반론에 머무릅니다.

막연한 요청을 강한 프롬프트로 바꾸기

약한 프롬프트:

Upgrade my Expo app.

더 나은 프롬프트:

Use the upgrading-expo skill to move my app from Expo SDK 53 to 54. We use expo-router, expo-av, Reanimated, and development builds. After npx expo install --fix, expo-doctor reports dependency mismatches and our app fails on startup with video playback errors. Tell me the likely breaking changes, the commands to run in order, and the code areas I should inspect first.

왜 이 방식이 잘 작동하냐면:

• 출발 SDK와 목표 SDK를 명확히 말하고
• 위험도가 높은 패키지를 함께 적어 주며
• 일반 조언이 아니라 우선순위 있는 출력을 요구하기 때문입니다

앱을 reference 가이드에 정확히 매핑하세요

저장소의 reference 문서는 의존성 표면과 의도적으로 맞춰 볼 때 가장 큰 효과를 냅니다.

• 사운드나 녹음에 expo-av를 쓰고 있다면 references/expo-av-to-audio.md
• 비디오에 expo-av를 쓰고 있다면 references/expo-av-to-video.md
• SDK 55로 올리면서 expo-router/unstable-native-tabs를 쓰고 있다면 references/native-tabs.md
• native modules가 있는 상태에서 SDK 53+ 또는 54+로 가는 중이라면 references/new-architecture.md
• SDK 54라면 references/react-19.md와 references/react-compiler.md를 둘 다 확인

바로 이 지점이, 단순히 저장소를 훑는 것보다 이 스킬이 실질적인 정보 이득을 주는 부분입니다.

가장 위험한 업그레이드 구간을 주시하세요

실제로는 아래 항목들이 이 스킬이 자주 드러내는 대표적인 파손 지점입니다.

• SDK를 올린 뒤 패키지 버전 정렬이 어긋나는 문제
• 오래된 native modules의 New Architecture 비호환
• SDK 54+의 react-native-worklets를 포함한 Reanimated 설정 변경
• 앱 코드나 라이브러리 코드에서의 React 19 API 변화
• expo-av에서 expo-audio, expo-video로의 마이그레이션
• Native Tabs의 라우터 수준 UI 변경

앱이 이 중 하나라도 사용하고 있다면, 일반 업그레이드 요약보다 타깃형 마이그레이션 체크리스트를 요청하는 편이 낫습니다.

두 번에 나눠 진행하는 워크플로를 쓰세요

좋은 upgrading-expo usage 패턴은 다음과 같습니다.

1. 현재 버전과 의존성을 기준으로 업그레이드 계획을 요청
2. 명령을 실행
3. 정확한 오류를 다시 제공하고 범위를 좁힌 수정 계획을 요청

이 스킬은 expo-doctor, TypeScript, Metro, native build의 실제 출력이 돌아왔을 때 구조적인 트리아지에 더 강합니다.

스킬이 암시하는 릴리스 노트성 이슈도 점검하세요

이 스킬의 브레이킹 체인지 체크리스트는 실제 검토 포인트를 가리킵니다.

• 제거된 API
• 변경된 import 경로
• prebuild가 필요한 native module 변경
• camera, audio, video 회귀
• navigation 회귀

즉, 코드 리뷰는 package.json에서 멈추면 안 됩니다. 앱을 실행하기 전에 영향받는 import와 컴포넌트를 코드베이스 전체에서 검색해 두는 편이 낫습니다.

prebuild와 네이티브 코드가 있으면 더 신중하게 사용하세요

앱에 custom native modules나 config plugins가 있다면 upgrading-expo skill은 여전히 유용하지만, markdown reference 바깥에서 해야 할 작업이 늘어날 가능성이 큽니다. 이런 프로젝트에서는 스킬에 다음을 분리해서 정리해 달라고 요청하세요.

• JS-only 마이그레이션 작업
• prebuild 재생성 작업
• native dependency 호환성 점검

이렇게 나누면 업그레이드 과정에서 혼선이 줄어듭니다.

upgrading-expo 스킬 FAQ

upgrading-expo는 입문자에게도 괜찮나요?

네, 이미 Expo 프로젝트가 있고 기본적인 프로젝트 정보를 제공할 수 있다면 괜찮습니다. 다만 이건 Expo 전체를 처음부터 가르치는 튜토리얼은 아닙니다. 업그레이드 중심 가이드이기 때문에, 현재 SDK 버전, 오류, 주요 의존성을 함께 줄 때 입문자도 가장 좋은 결과를 얻습니다.

upgrading-expo 스킬의 범위는 어디까지인가요?

이 스킬은 업그레이드 계획, 명령 실행 순서, 알려진 마이그레이션 핫스폿 파악에 도움을 줍니다. 하지만 저장소 전체를 자동으로 검사해 주지는 않으며, 모든 서드파티 네이티브 라이브러리의 호환성을 보장하지도 않습니다. 네이티브 영역에서 깊은 수준의 파손이 있다면, 결국 패키지별 문서와 GitHub issues를 함께 봐야 할 수 있습니다.

Expo 업그레이드를 그냥 LLM에 물어보는 것과 upgrading-expo는 무엇이 다른가요?

가장 큰 차이는 큐레이션입니다. upgrading-expo skill은 일반 프롬프트가 놓치기 쉬운 Expo 전용 마이그레이션 reference로 모델의 시선을 정확히 유도합니다. 특히 expo-av, React 19, React Compiler, Native Tabs, New Architecture 동작 변화 주변에서 차이가 큽니다.

언제 upgrading-expo를 쓰지 않는 편이 좋나요?

다음 경우에는 건너뛰는 편이 낫습니다.

• 기존 앱 업그레이드가 아니라 완전히 새 Expo 앱을 시작하는 경우
• 문제가 SDK 업그레이드와 무관한 경우
• 자동 codemod나 CLI 마이그레이션 도구가 필요한 경우
• 가장 큰 장애물이 고유한 마이그레이션 절차를 가진 단일 서드파티 네이티브 라이브러리인 경우

upgrading-expo는 preview SDK도 다루나요?

네. 이 스킬은 베타 릴리스가 .preview 접미사를 쓰고 @next에서 설치된다는 점을 짚어 줍니다. 다가오는 변경사항을 테스트할 때는 도움이 되지만, 안정적인 업그레이드라면 여전히 stable이 더 안전한 기본값입니다.

upgrading-expo는 managed workflow 앱에만 해당하나요?

아니요. managed와 prebuild 기반 Expo 앱 모두에 유용합니다. 다만 prebuild와 custom native code가 들어가면 추가적인 수동 호환성 점검이 필요할 가능성이 더 높습니다.

upgrading-expo 스킬을 더 잘 활용하는 방법

정확한 버전 차이를 알려 주세요

가장 효과가 큰 개선은 간단합니다. 그냥 “upgrade Expo”라고 하지 말고 “SDK X에서 SDK Y로”라고 명시하세요. 마이그레이션 조언은 SDK 53, 54, 55 중 어느 경계를 넘는지에 따라 실제로 크게 달라집니다.

답을 바꾸는 패키지 표면을 함께 적으세요

더 나은 upgrading-expo 결과를 원한다면 reference 문서를 트리거하는 패키지를 포함하세요.

• expo-av
• expo-router
• react-native-reanimated
• custom native modules
• expo-doctor에서 실패하는 모든 패키지

이렇게 해야 일반 체크리스트에서 끝나지 않고, 실제 영향 가능성이 높은 가이드로 넘어갈 수 있습니다.

요약이 아니라 실제 진단 출력을 붙이세요

나쁨:

build failed after upgrade

더 좋음:

npx expo-doctor says package versions are invalid, Metro reports unresolved import from expo-av, and iOS dev build fails after enabling New Architecture.

정확한 로그가 있어야 이 스킬이 단순 의존성 어긋남인지, API 마이그레이션 문제인지 구분할 수 있습니다.

우선순위 있는 출력을 요청하세요

강한 요청 형식은 보통 다음과 같습니다.

1. 지금 바로 실행할 명령
2. 가능성 순으로 정렬한 주요 파손 지점
3. 검색해야 할 파일/import
4. 수정 후 검증 단계

이 구조를 쓰면 시간 압박 속에서도 upgrading-expo guide를 훨씬 실행하기 쉬워집니다.

설치 실패와 코드 마이그레이션을 분리하세요

흔한 실패 패턴 중 하나는 패키지 설치 문제와 소스 레벨 API 변경을 한 덩어리로 섞는 것입니다. 스킬에는 아래 순서대로 처리해 달라고 요청하세요.

• dependency alignment
• doctor output
• cache reset
• source migrations
• runtime verification

이렇게 하면 원인을 맴도는 식의 순환 디버깅을 줄일 수 있습니다.

코드베이스 전용 검색 패턴을 요청하세요

upgrading-expo skill 출력을 개선하는 가장 좋은 방법 중 하나는 grep 스타일 검색 대상을 요청하는 것입니다. 예:

Using the upgrading-expo skill, list the import paths, component names, and hooks I should search for to migrate from expo-av and to verify Native Tabs changes in SDK 55.

이렇게 하면 넓은 설명이 실제 코드 리뷰 작업으로 바로 바뀝니다.

첫 번째 시도 후 위험 경로를 꼭 검증하세요

첫 업그레이드 시도 후에는 특히 아래를 테스트하세요.

• audio playback and recording
• video playback
• tab navigation
• Expo Go와 dev build에서의 startup
• 무거운 애니메이션이나 native modules를 사용하는 화면

이 영역들이야말로 SDK 전환 과정에서 이 스킬이 다루는 문제를 가장 잘 드러내는 구간입니다.

후속 프롬프트는 더 좁게 쪼개세요

업그레이드 전체를 계속 한 번에 해결해 달라고 하지 마세요. 두 번째 프롬프트부터는 범위를 줄이는 편이 좋습니다.

• “내 shared UI package에서 React 19 변경만 집중해 줘”
• “expo-av video migration만 집중해 줘”
• “New Architecture 비호환성만 집중해 줘”

범위가 작을수록 더 선명하고 정확한 수정 단계가 나오는 경우가 많습니다.