📱 RN + Expo 앱 구축 총체적 고려사항

Oct 1, 2025 updated Oct 1, 2025 architecture expo react-native typescript

0) 상위 의사결정 트리

주제	결정 포인트	권장안	리스크/대안
프로젝트 타입	Expo Managed vs Dev Client vs Bare	Managed로 시작 → 네이티브 요구 생기면 Dev Client	TLS Pinning/고급 BLE/백그라운드 업로드 강하면 Bare 고려
라우팅	React Navigation vs Expo Router	React Navigation (안정/확장)	파일 기반 원하면 Expo Router(+Navigation)
디자인 시스템	토큰/Variant/접근성 전략	Restyle + RN Aria (gluestack 일부 병행 가능)	풀킷(Paper/Elements) 의존 커지면 커스텀 난이도↑
상태전략	로컬/서버 상태 분리	Zustand(Local) + React Query(Server)	전역 남용 지양, 화면 단위 co-locate
배포전략	OTA/스토어 릴리스	EAS Update + EAS Build/Submit	네이티브 변경은 새 빌드 필요
환경분리	dev/stage/prod	app.config.ts + EAS Secrets	.env 직접 주입/유출 금지

1) 구조/아키텍처

폴더 구조(예: FSD or feature-first)
- app/(screens, navigation), entities/, features/, shared/(ui, lib, api), processes/(세션 등)
- shared/ui: Box/Text/Button 베이스 컴포넌트(토큰/Variant 반영)
경계 분리
- Server state(React Query) vs UI/Session state(Zustand) 명확 분리
- API 모듈: fetcher(axios) + 인터셉터(토큰/리프레시)
의존성 규칙
- 상위 → 하위 방향(순환 금지), public API만 import

2) 접근성(A11y) 정책

터치 타깃 44dp 이상, 콘트라스트 4.5:1 준수
모든 터치 요소에 accessibilityRole/Label/Hint 지정
포커스 관리: 모달/바텀시트 오픈 시 초점 이동/트랩
스크린리더(VoiceOver/TalkBack) 수동 테스트 플로우 문서화
제스처만으로 작동하지 않도록 대체 조작 제공
핵심 컴포넌트에 RN Aria 훅 우선 적용 (button, checkbox, slider 등)

3) 성능/UX 가이드

리스트는 기본 FlatList → 스케일되면 FlashList로 전환
이미지: WebP/AVIF 우선, 캐시(expo-file-system) + 프리로드 전략
애니메이션: Reanimated + Moti, FPS 드랍 구간(스크롤/시트) 우선 최적화
퍼포먼스 예산 정의(첫 렌더 < 1.5s, 메모리, JS bundle 크기)
인터랙션 레이턴시: 제스처-중심 화면(바텀시트/캐러셀)에서 16ms 타깃

4) 네트워킹/오프라인

Axios 인터셉터: 토큰 주입/401 리프레시/재시도(지수백오프)
React Query:
- 캐시 타임/스테일 타임 정책, 에러 경계 처리(토스트/다이얼로그)
- Persist: react-query-persist-client + AsyncStorage (오프라인 읽기)
오프라인 전략: 읽기 캐시 + 쓰기 큐(네트워크 복구 시 동기화)
데이터 보호: 민감정보는 SecureStore, 일반은 AsyncStorage

5) 알림/링크/딥링크

푸시 알림: expo-notifications
- Android 채널 사전 생성(중요도, 사운드), 카테고리(액션 버튼) 설계
- 토큰 수집/해지/토픽 구독 백엔드 스펙 명세
로컬 알림: 스케줄/반복, 권한 거부 UX 대비
딥링크: expo-linking으로 스킴/유니버설 링크 설정(검증 파일 포함)
- 외부 앱 미설치/실패 시 Web Fallback 준비
인앱 브라우저: expo-web-browser(세션 콜백/리디렉션 처리)

6) 보안/개인정보

토큰/세션: SecureStore 저장, 만료/갱신 로직 표준화
전송 암호화: HSTS/최신 TLS, (만약 필요한 경우) Pinning은 Bare/Dev Client에서 검토
로그/분석에 PII 금지. 마스킹/해시 규칙 문서화
권한 프롬프트 문구는 정확한 용도와 가치를 설명
스크린샷 차단(민감화면) 필요 시 Android 플래그/Bare 검토

7) 분석/모니터링/로그

크래시/성능: @sentry/react-native(소스맵 업로드 자동화)
이벤트 분석: Segment/Amplitude/Firebase Analytics 중 하나
- 이벤트 명세서(이름/파라미터/샘플링/PII 규칙) 작성
사용자 피드백: 인앱 피드백/로그 수집(동의/옵트아웃 제공)
원격 플래그: 기능 토글(LaunchDarkly/ConfigCat/자체)로 안전한 롤아웃

8) 국제화(i18n)/현지화

react-i18next + expo-localization
문자열 키컨벤션/플레이스홀더 규약, 번역 워크플로우(Figma/Sheet ↔ JSON)
날짜/통화 포맷, 우/좌 정렬, 플러럴 규칙 반영

9) 빌드/배포/릴리스

EAS Build/Submit 파이프라인(GitHub Actions)
- 스토어 서명/프로비저닝 자동 관리, 빌드 번호/버전 증가 자동화
EAS Update(OTA): 마이너 수정은 OTA, 네이티브 바뀌면 새 빌드
릴리스 트랙: 내부 → 테스트 → 프로덕션 단계적 롤아웃
릴리스 노트 템플릿/체크리스트(Screenshots, 프라이버시, 심사 대응 Q&A)

10) 품질/테스트 전략

유닛/컴포넌트: Jest + Testing Library(RN)
통합/E2E: Maestro(Expo 친화), 필요 시 Detox(Dev/Bare)
접근성 테스트: 스크린리더 시나리오 문서 + 수동 테스트
디바이스 매트릭스: iOS(최소/최신) × Android(중저가 포함) 실제기기
성능 회귀: 스크롤/바텀시트/리스트 FPS 측정 체크

11) 설정/권한/앱 구성

app.config.ts에서 env별 번들ID/스킴/아이콘/스플래시 분리
iOS infoPlist/Android permissions 권한 선언 + 사유 문구
딥링크 스킴 명명 규칙(중복 방지), 유니버설 링크 도메인 소유 검증

12) 스토어 컴플라이언스/정책

개인정보 처리방침/이용약관 앱 내 링크 제공
Sign in with Apple(iOS, 타 소셜 로그인 있을 때)
위치/백그라운드/녹음 등 민감권한 필요성 명확화(기능 없으면 제거)
푸시 이용 목적 설명/옵트인/옵트아웃 UX 제공

13) 팀 운영/레포/CI

모노레포(Turborepo + pnpm) 고려: web/rn 공통 패키지(ui, config, api)
코드 규칙: TypeScript strict, Biome(포맷/린트), commitlint + conventional commits
PR 템플릿(테스트 범위/스크린샷/접근성 체크 포함)
변경 로그 자동화(Changesets)

14) 데이터 동기화/오프라인 심화(선택)

충돌 해결 정책: Last-Write-Wins vs Merge vs 서버 권한
큐 저장: 오프라인 변경분 로컬 큐 → 온라인 시 재생
부분 동기화: 뷰 단위 prefetch(React Query) + TTL

15) 위험요인(Risk Register) 예시

리스크	영향	대응
권한 거부로 핵심 기능 불가	기능 미사용/이탈	최초 진입 온보딩에서 가치 설명 → 설정화면 이동 버튼 제공
안드로이드 기기 편차	크래시/UX 불일치	중저가 실제기기 테스트, 채널/파일/스토리지 정책 사전 검증
알림 미도착/토큰 만료	핵심 이벤트 누락	토큰 재발급 로직/서버 보정, 알림 상태 self-check 화면
번들 크기 증가	설치/업데이트 이탈	아이콘/이미지 최적화, 죽은 의존성 제거, 코드 스플릿 고려
API 변경/속도 이슈	장애/타임아웃	버전된 API 계약, 리트라이/백오프/서킷브레이커

빠른 실행 체크리스트(DoD)

디자인 토큰/Variant 초안 확정(색/간격/폰트/라운드/상태)
RN Aria + Restyle 기반 Button/Input/Card/Modal/Sheet 베이스 구축
React Navigation + 딥링크/초기 루트 세팅
권한 프롬프트 문구/흐름 확정(카메라/앨범/위치/알림)
알림 채널(Android) 및 Expo Push 토큰 발급/서버 연동
React Query 캐시/에러 경계/로깅(Sentry) 적용
EAS Build/Submit 파이프라인 + OTA(Update) 구성
i18n 세팅 + 기본 번역 파일
테스트: Jest/RTL + Maestro 스모크 플로우
스토어 제출 체크리스트/개인정보 문서 준비