리액트 네이티브 빌드 에러를 우회하고 5분 만에 앱 실행하기
TuBrief 편집팀
2026년 3월 16일
0
컴퓨터/소프트웨어원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
웹 개발에 익숙한 주니어 개발자가 모바일 앱 개발을 시작할 때 가장 먼저 겪는 어려움은 로컬 네이티브 툴체인 설정 과정에서 발생하는 복잡한 빌드 에러이다. 기존의 리액트 네이티브 방식은 안드로이드 스튜디오와 엑스코드, 그래들, 코코아팟 등의 툴체인을 수동으로 설치해야 하므로 버전 충돌로 인해 코드를 작성하기도 전에 수 시간에서 수일을 허비하게 된다. 이 문제를 해결하기 위해 엑스포 매니지드 워크플로우를 활용하면 네이티브 설정 없이 5분 만에 개발을 시작할 수 있다.
실제 모바일 기기에서 실시간 테스트 환경을 5분 만에 구성하려면 다음의 3가지 단계를 실행한다. 첫째, 터미널을 열고 명령어를 입력하여 최신 엑스포 템플릿 프로젝트를 생성한 후 해당 디렉토리로 이동하여 개발 서버를 실행한다. 터미널에 입력할 명령어는 다음과 같다.
npx create-expo-app@latest my-mobile-app --template default
cd my-mobile-app
npx expo start
둘째, 컴퓨터의 시스템 자원을 소모하는 에뮬레이터 대신 실제 스마트폰 기기에 엑스포 고 애플리케이션을 설치한다. 셋째, 터미널에 생성된 QR 코드를 iOS의 기본 카메라 앱이나 안드로이드의 엑스포 고 내장 스캐너로 스캔하면 수 초 내에 메인 번들이 컴파일되어 기기에서 즉시 실행된다. 이 방식을 통해 개발자는 로컬 빌드 스트레스 없이 핫 리로딩을 활용하며 개발 시간을 2시간 이상 단축할 수 있다.
소규모 웹 프로젝트의 관성대로 컴포넌트와 훅, 화면 유형별로 폴더를 무분별하게 나누는 방식은 모바일 앱의 규모가 커질수록 코드 응집도를 떨어뜨린다. 엑스포 루터는 파일 기반 라우팅을 지원하므로, 모든 소스 코드는 src 디렉토리로 격리하고 화면 라우팅 경로는 src/app/에만 한정해야 한다. 확장 가능한 모바일 앱 구조를 설계하려면 다음의 3가지 단계를 순서대로 수행한다. 첫째, 프로젝트 루트의 tsconfig.json 파일을 수정하여 상대 경로 참조를 방지하고 경로 별칭을 설정한다. 설정에 추가할 코드는 다음과 같다.
{
"extends": "expo/tsconfig.base",
"compilerOptions": {
"strict": true,
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
둘째, 최상위 루트 레이아웃 파일인 src/app/_layout.tsx를 생성하여 전체 네비게이션 스택을 정의하고 화면별 헤더 옵션을 설정한다. 셋째, 기능 단위의 비즈니스 모듈과 공통 UI 컴포넌트를 src/features/와 src/components/ 디렉토리에 분리하여 배치함으로써 라우팅과 비즈니스 로직을 분리한다. 이 구조를 도입하면 복잡한 상대 경로 참조 오류를 완전히 제거하고 기능 추가 시 발생하는 사이드 이펙트를 줄일 수 있다.
모바일 환경은 셀룰러 네트워크와 와이파이 간의 빈번한 전환으로 인해 비동기 통신 중 네트워크 단절 현상이 자주 발생하며, 기본 페치 API는 타임아웃이 없어 앱이 멈추는 프리징을 유발한다. 이 문제를 방지하기 위해 탠스택 쿼리와 로컬 저장소를 결합하여 오프라인 캐싱을 구현하고, 라우트 단위의 에러 바운더리를 적용해야 한다. 런타임 에러로 인한 앱 강제 종료를 막고 안정성을 확보하려면 다음의 3가지 단계를 수행한다. 첫째, AbortController와 타이머를 활용하여 네트워크 요청 시간이 초과될 경우 강제로 요청을 중단하는 페치 래퍼 유틸리티 함수를 작성한다. 둘째, 탠스택 쿼리 클라이언트 설정에서 24시간 동안 오프라인 캐시를 보존하도록 설정하고 비동기 영구 저장소 퍼시스터를 연결한다. 설정에 활용할 코드는 다음과 같다.
import AsyncStorage from '@react-native-async-storage/async-storage';
import { QueryClient } from '@tanstack/react-query';
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
const queryClient = new QueryClient({
defaultOptions: {
queries: {
gcTime: 1000 * 60 * 60 * 24,
staleTime: 1000 * 60 * 5,
retry: 2,
},
},
});
const asyncStoragePersister = createAsyncStoragePersister({
storage: AsyncStorage,
key: 'APP_OFFLINE_CACHE',
});
셋째, 엑스포 루터의 라우트 레벨에서 에러 바운더리와 서스펜스 휄백 컴포넌트를 직접 내보내어 렌더링 에러 발생 시 사용자에게 재시도 버튼과 명확한 피드백 UI를 제공한다. 이 다층 예외 처리 체계를 적용하면 네트워크 단절 시 앱이 흰 화면으로 멈추는 크래시 현상을 차단할 수 있다.