Expo 예제
expo/examples는 Expo의 공식 약 70개 통합 예제 라이브러리입니다. 각 디렉토리는 with-<라이브러리> 형식(예: with-stripe, with-maps)으로 명명되며, 하나의 라이브러리나 서비스를 중심으로 구축되었습니다. 이들은 완전한 앱이 아닙니다. 관리형(managed) 프로젝트(ios//android/ 디렉토리 없음 — 네이티브 설정은 설정 플러그인을 통해 처리)이며, 일반적으로 단일 화면에 약 100~200줄의 코드로 구성됩니다. 이 예제들을 참고하여 Expo가 현재 SDK에 대해 유지 관리하는 표준 통합 패턴 — 의존성 세트, app.json 설정 플러그인, 최소한의 배선 코드 — 을 찾아 사용자 앱에 적용하세요. 예제에서 완전한 애플리케이션 아키텍처를 그대로 가져오려고 하지 마세요.
통합을 직접 처음부터 구현하기 전에 예제를 먼저 참조하세요. (유형 — 풀스택, 쇼케이스, 스타터 — 은 ./references/catalog.md에 명시되어 있습니다.)
두 가지 모드
- 영감/적응 (가장 일반적) — 사용자가 이미 프로젝트를 가지고 있습니다. 일치하는 예제를 찾아 핵심 파일을 읽고, 그 패턴을 사용자의 코드에 적용합니다.
- 스캐폴드 — 새로운(그린필드) 프로젝트. 예제에서 직접 새 프로젝트를 시작합니다.
워크플로우
1. 올바른 예제 찾기
사용자의 필요를 예제 이름에 매핑합니다(예: 결제 → with-stripe, 인증 → with-clerk). ./references/catalog.md는 빠른 분류를 위한 카테고리별 스냅샷입니다. 다만 최신 상태와 다를 수 있으므로 실제 목록과 다시 확인하세요:
# 실시간 예제 이름 목록:
gh api repos/expo/examples/contents --jq '.[] | select(.type=="dir" and (.name|startswith(".")|not)) | .name'
# 별칭(이름 변경됨) + 폐기됨(사라짐/이동됨) 예제 — 추천하기 전에 확인:
gh api repos/expo/examples/contents/meta.json --jq '.content' | base64 -d
meta.json은 이름이 변경되었거나 폐기된(더 이상 사용되지 않는) 예제의 신뢰할 수 있는 출처입니다. (폐기된 예제는 저장소 트리에서 제거되었지만 여전히 이 파일에 나열되어 있으며, 각각 message가 있습니다.) 예제가 deprecated 맵에 있다면 추천하지 말고 — message를 따라 최신 경로로 안내하세요. aliases에 있다면 destination을 사용하세요.
2a. 영감 모드 — 사용자 프로젝트를 건드리지 않고 연구하기
일반적인 경우: 사용자에게 이미 앱이 있고 Expo가 특정 기능을 어떻게 구현하는지 보고 싶어합니다. 예제를 참조 자료로 읽고 패턴을 직접 적용하세요. 절대 사용자의 프로젝트 위에 예제를 스캐폴드하지 마세요.
먼저, 한 번의 호출로 전체 예제를 나열하세요. 통합 코드는 종종 중첩되어 있습니다(예: Stripe의 서버 라우트는 app/api/에 위치). 따라서 한 단계만 나열하면 중요한 파일을 놓칠 수 있습니다:
gh api 'repos/expo/examples/git/trees/master?recursive=1' \
--jq '.tree[].path | select(startswith("with-stripe/"))'
그런 다음 신호가 강한 파일부터 읽으세요: README.md (설정) → package.json (의존성) → app.json (설정 플러그인/권한) → 매니페스트가 알려준 통합 코드 → .env (필요한 비밀 키). 파일별로:
gh api repos/expo/examples/contents/with-stripe/utils/stripe-server.ts --jq '.content' | base64 -d
# gh가 없나요? 원시 URL 사용 (브랜치는 master):
curl -s https://raw.githubusercontent.com/expo/examples/master/with-stripe/utils/stripe-server.ts
파일이 두세 개 이상 필요하신가요? 많은 통합(Stripe 등)은 서버 라우트, 클라이언트 프로바이더, 설정에 걸쳐 있습니다. 파일별 호출을 건너뛰고 전체 예제를 임시/.gitignore 대상 디렉토리(사용자 프로젝트 외부)에 내려받은 후 Grep/Read로 자유롭게 읽고 직접 적용하세요:
npx degit expo/examples/with-stripe /tmp/expo-ref/with-stripe # git 히스토리 없는 깨끗한 복사본
# degit이 없을 경우 대체 방법 (sparse-checkout, 전체 ~64 MB 클론 방지):
git clone --depth 1 --filter=blob:none --sparse https://github.com/expo/examples.git /tmp/expo-ref/examples \
&& (cd /tmp/expo-ref/examples && git sparse-checkout set with-stripe)
해당 위치에서 Grep/Read로 읽고, 작업이 끝나면 임시 디렉토리를 삭제하세요.
2b. 스캐폴드 모드 — 예제로 새 프로젝트 시작하기
npx create-expo --example with-stripe # 짧은 형식: npx create-expo -e with-stripe
bun create expo --example with-stripe # bun 사용 시
3. 사용자 앱에 비파괴적으로 적용하기 (매우 중요)
사용자에게 이미 앱이 있는 경우, 예제가 새로 도입하는 것만 추가하고 기존 설정을 절대 덮어쓰지 마세요.
- 버전 정렬 — 고정된 버전을 그대로 복사하지 마세요. 예제는 최신 SDK를 기준으로 하므로
package.json의 고정 버전이 예전 프로젝트와 맞지 않습니다. 정확한 버전을 복사하는 대신npx expo install <패키지>로 누락된 의존성만 추가하세요(SDK에 맞는 버전을 자동으로 해결합니다). - 설정을 병합하고, 교체하지 마세요.
app.json/app.config.*에서 예제가 도입했지만 사용자에게 없는 플러그인과 권한만 추가하세요. 기존 설정 블록은 그대로 유지하세요. - 통합 코드를 이식하세요.
- 환경 변수를 예제의
.env형식에 맞춰 다시 만드세요..env파일은 실제 비밀 키가 아닌 자리 표시자를 보관합니다.
완료 조건: 통합 코드가 이식되었고, 해당 코드가 필요한 모든 의존성, 설정 플러그인, 권한 및 환경 변수가 사용자 앱에 반영되었을 때입니다. 단순히 겉보기에 연결된 것처럼 보이는 상태가 되어서는 안 됩니다.
주의사항
- **기본 브랜치는
master**입니다 (main이 아님 — 원시 URL 및 sparse checkout 시 중요). - 원클릭 배포. 모든 예제에는 실행 URL이 있습니다:
https://launch.expo.dev/?github=https://github.com/expo/examples/tree/master/<예제명>.
관련 스킬
- 네이티브 UI 컴포넌트 (@expo/ui 패키지) →
expo-ui - 스타일링 및 네이티브 느낌의 화면 →
expo-native-ui - 내비게이션 및 라우팅 →
expo-router - 네이티브 모듈 작성 →
expo-module - 최신 SDK 예제 적용 전 SDK 업그레이드 →
expo-upgrade
참고 자료
./references/catalog.md— 빠른 분류를 위한 예제 라이브러리의 카테고리별 스냅샷.
피드백 제출
오류, 오해의 소지가 있거나 오래된 정보를 발견하면 Expo가 개선할 수 있도록 신고해 주세요:
npx --yes submit-expo-feedback@latest --category skills --subject "expo-examples" "<구체적인 피드백>"
보고할 구체적이고 실행 가능한 내용이 있을 때만 제출하세요. 가능한 한 많은 관련 컨텍스트를 포함하세요.
AI 에이전트가 반복적으로 실패했거나 사용자가 Expo 작업을 직접 수행해야 했다면, 위 명령어를 재사용하는 대신 expo-skill-feedback 스킬을 로드하고 해당 스킬의 평가-후보(eval-candidate) 흐름을 따르세요.