Expo Go로 안 되는 네이티브 라이브러리, development build로 붙이기

😀 개요

안녕하세요 😀

지난 Expo vs React Native CLI 글에서, 새 프로젝트는 대부분 Expo로 시작하면 되고 네이티브가 필요하면 development build로 붙이면 된다고 정리했습니다. 이번 글은 그 "붙이는 과정"을 처음부터 따라가 보는 편입니다.

Expo로 개발하다 보면 이런 순간을 만납니다.

• 카메라나 블루투스 라이브러리를 넣었는데 앱에서 "이 라이브러리는 Expo Go에서 지원되지 않습니다" 같은 메시지가 뜬다.
• 분명 설치는 됐는데, Expo Go에서 실행하면 그 기능만 동작하지 않는다.
• 검색해 보면 "development build를 만들어라"는데, 그게 뭔지, 어디서부터 손대야 할지 막막하다.

결론부터 말하면, 이건 막힌 게 아니라 Expo Go의 범위를 벗어난 것뿐입니다. development build 하나만 만들면 그 라이브러리는 그대로 동작합니다.

🎯 오늘 끝내는 목표

이 글을 다 읽으면 아래를 할 수 있습니다.

• 왜 어떤 라이브러리는 Expo Go에서 안 되는지 한 문장으로 설명할 수 있습니다.
• 내 Expo 프로젝트에 서드파티 네이티브 라이브러리를 넣고 development build로 실행하는 순서를 압니다.
• 로컬에서 빌드할지, Mac이 없어 EAS 클라우드로 빌드할지 고를 수 있습니다.

설치 한 번으로 끝나는 게 아니라, 네이티브 코드가 든 라이브러리를 실제 앱에 태우는 전체 흐름을 손에 익히는 것이 이 글의 목적입니다.

🧭 근거부터 짚고 갑니다

미리 말씀드리면, 여기 나오는 명령과 설정은 제가 실제 앱에 붙여 운영해 본 결과가 아니라 Expo와 각 라이브러리의 공식 문서에서 확인해 정리한 것입니다.

아래 명령과 설정은 문서 기준으로 그대로 따라 할 수 있게 적었지만, Expo SDK·라이브러리 버전에 따라 세부가 달라질 수 있습니다. 특히 개별 라이브러리는 메이저 버전이 바뀌면 설치·설정이 통째로 달라지기도 합니다(뒤에서 실제 사례를 봅니다). 버전과 명령은 확인일(2026년 7월 17일, Expo SDK 57 기준) 이며, 정확한 값은 본인 프로젝트의 SDK와 그 라이브러리의 현재 문서로 확인하시는 편이 안전합니다.

🚧 왜 어떤 라이브러리는 Expo Go에서 안 될까

먼저 Expo Go의 정체부터 정리하겠습니다.

Expo Go는 쉽게 말하면 앱스토어에서 받는 미리 만들어진 고정 앱입니다. 그 안에는 Expo SDK에 포함된 네이티브 기능만 들어 있습니다. 그래서 공식 문서 표현대로, Expo Go에서는 "Expo SDK에 포함된 네이티브 라이브러리, 또는 네이티브 코드가 없는 라이브러리"만 쓸 수 있습니다.

문제는 카메라·블루투스·결제 같은 서드파티 라이브러리입니다. 이들은 자기만의 네이티브 코드를 가지고 있어서, 미리 만들어진 Expo Go 안에는 그 코드가 없습니다. 그래서 실행하면 그 부분만 동작하지 않는 것입니다.

내가 쓰려는 라이브러리가 Expo Go에서 되는지 확인하는 방법은 두 가지입니다.

• React Native Directory(reactnative.directory)에서 그 라이브러리에 "✔️ Expo Go" 태그가 있는지 봅니다.
• 아래 네 가지 중 하나라도 해당하면 development build가 필요합니다(공식 문서 기준).

- 라이브러리에 android 또는 ios 디렉터리가 들어 있다. - README에 linking 이야기가 나온다. - AndroidManifest.xml, Podfile, Info.plist를 고치라고 한다. - config plugin을 제공한다.

그림 1. Expo Go는 Expo SDK 기능만 담긴 고정 앱이라 서드파티 네이티브 코드를 못 싣습니다. 위 네 가지 중 하나라도 걸리면 development build로 넘어갑니다.

🧱 development build가 정확히 뭔가요

development build는 쉽게 말하면 내 프로젝트를 직접 빌드한, 개발용 앱입니다. 공식 문서는 이를 "내 전용 Expo Go"라고 표현합니다. Expo Go와 달리 이 앱에는 내가 넣은 네이티브 라이브러리가 함께 컴파일돼 들어가므로, 어떤 서드파티 네이티브 코드도 쓸 수 있습니다.

이걸 가능하게 하는 것이 expo-dev-client 라는 패키지입니다. 이 패키지는 앱에 개발용 런처(dev launcher) 화면을 붙여 줍니다. 어느 개발 서버에 붙을지 고르고, 개발자 메뉴를 열고, 네트워크 요청을 들여다보는 도구가 여기에 들어 있습니다.

그림 2. Expo 공식 "Development builds" 문서. development build를 "내가 원하는 네이티브 라이브러리를 쓰고 네이티브 설정을 바꿀 수 있는, 내 전용 Expo Go"로 설명합니다. 출처: docs.expo.dev/develop/development-builds/introduction, 확인일 2026-07-17.

정리하면 흐름은 이렇습니다. expo-dev-client를 넣고 → 라이브러리를 설치·설정하고 → 네이티브 프로젝트를 만들어 → 한 번 빌드하면, 그 앱이 곧 "내 라이브러리가 들어간 Expo Go"가 됩니다.

🛠️ 붙이는 순서: 설치부터 실행까지

이제 실제 순서입니다. 큰 흐름을 먼저 보겠습니다.

그림 3. 설치 → 앱 설정(권한·config plugin) → prebuild로 네이티브 생성 → 빌드(로컬 run 또는 EAS 클라우드) → dev client로 실행. 네이티브 라이브러리를 새로 추가하면 이 빌드를 다시 해야 합니다.

1단계 — dev client 넣고 라이브러리 설치하기

먼저 개발용 클라이언트를 넣습니다.

npx expo install expo-dev-client

그다음 쓰려는 라이브러리를 설치합니다. Expo 프로젝트에서는 npm install보다 npx expo install 을 권장합니다. 지금 SDK와 호환되는 버전을 골라 주고, 알려진 충돌을 미리 경고해 주기 때문입니다.

# 예시 형식 (라이브러리 이름은 상황에 맞게)
npx expo install <라이브러리-이름>

2단계 — 앱 설정: 권한과 config plugin

네이티브 라이브러리는 권한이나 네이티브 설정을 요구하는 경우가 많습니다. 여기서 중요한 원칙이 있습니다. android·ios 폴더를 직접 손으로 고치지 마세요. Expo(CNG)에서는 이 폴더가 다시 생성될 때 손댄 내용이 사라집니다.

대신 두 가지 방법을 씁니다.

첫째, 많은 라이브러리는 config plugin을 제공합니다. app.json(또는 app.config.js)의 plugins 배열에 등록하면, 네이티브 설정이 빌드 때 자동으로 반영됩니다. 옵션이 없으면 이름만, 옵션이 있으면 [이름, 옵션] 형태로 씁니다.

{
  "expo": {
    "plugins": [
      "some-native-library",
      ["another-library", { "someOption": "value" }]
    ]
  }
}

둘째, 권한처럼 간단한 것은 app.json의 필드로 직접 넣습니다. 예를 들어 iOS 권한 문구는 ios.infoPlist, Android 권한은 android.permissions에 적습니다.

3단계 — 네이티브 프로젝트 만들기 (prebuild)

설정을 마쳤으면 네이티브 프로젝트를 생성합니다.

npx expo prebuild

이 명령이 app.json 설정과 설치한 라이브러리를 바탕으로 android·ios 폴더를 만들어 줍니다. 뒤 단계의 로컬 빌드 명령(npx expo run:*)은 이 prebuild를 자동으로 실행하므로, 보통은 따로 부르지 않아도 됩니다.

4단계 — 빌드하기: 로컬 또는 EAS 클라우드

이제 실제로 앱을 빌드합니다. 두 갈래가 있습니다.

(a) 로컬 빌드 — Android Studio(안드로이드)나 Xcode(iOS)가 설치돼 있다면, 내 컴퓨터에서 바로 빌드합니다.

npx expo run:android
# 또는
npx expo run:ios

(b) EAS 클라우드 빌드 — 로컬에 네이티브 빌드 도구가 없거나, Mac 없이 iOS 빌드가 필요하면 Expo의 클라우드 빌드(EAS)를 씁니다.

# eas-cli 준비
npm install --global eas-cli
eas login
eas build:configure

그리고 eas.json의 development 프로필에 developmentClient: true를 두고(개발용 빌드라는 뜻), 빌드를 겁니다.

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    }
  }
}

eas build --platform android --profile development
# iOS는 --platform ios, 둘 다면 --platform all

로컬이든 EAS든 결과물은 같은 development build입니다. EAS는 필수가 아니라, 로컬 빌드 환경을 갖추기 어려울 때의 선택지입니다.

다만 한 가지 오해는 없어야 합니다. EAS로 iOS를 빌드하더라도 Apple Developer 계정과 기기 등록(내부 배포용)은 여전히 필요합니다. "Mac이 없어도 된다"는 뜻이지 "Apple 계정 없이 된다"는 뜻은 아닙니다.

5단계 — 실행하기 (dev client)

EAS로 빌드했다면 빌드가 끝난 뒤 나오는 QR 코드나 설치 링크로 기기에 앱을 설치합니다. 로컬 빌드(npx expo run:*)는 빌드하면서 바로 기기·에뮬레이터에 설치됩니다. 앱이 설치됐으면 개발 서버를 켜서 붙입니다.

npx expo start --dev-client

앱을 열면 dev launcher가 뜨고, 같은 네트워크의 개발 서버에 연결하거나 QR로 붙습니다. 이후 JavaScript만 고칠 때는 다시 빌드할 필요 없이 서버만 켜면 됩니다. 개발자 메뉴는 기기를 흔들거나 Cmd+D(맥)·Ctrl+D(윈도우/리눅스)로 엽니다.

📷 실제 예: 카메라 라이브러리 붙여보기

감이 잡히게 널리 쓰는 카메라 라이브러리 react-native-vision-camera로 예를 들겠습니다. 이 라이브러리는 자체 네이티브 코드가 있어 Expo Go에서는 동작하지 않고 development build가 필요합니다.

여기서 이 글에서 가장 강조하고 싶은 부분이 나옵니다. 이 라이브러리는 버전이 올라가면서 설정 방식이 바뀌었습니다. 예전 V4에서는 plugins 배열에 config plugin으로 등록하고 cameraPermissionText 같은 옵션을 줬는데, 현재 V5(확인일 기준)에서는 그 config plugin이 사라졌습니다. 지금은 권한을 app.json에 직접 넣습니다.

확인일 기준 V5 설치·설정은 이렇습니다(정확한 최신 값은 반드시 vision-camera 공식 문서로 확인하세요).

# V5는 Nitro 기반이라 함께 설치해야 하는 패키지가 있습니다
npm install react-native-vision-camera react-native-nitro-modules react-native-nitro-image

앞에서 npx expo install을 권장했는데 여기서는 npm install을 씁니다. vision-camera는 함께 쓸 Nitro 패키지 버전을 라이브러리 쪽에서 지정하기 때문에, 공식 문서가 안내하는 설치법을 그대로 따르는 것입니다. 이처럼 라이브러리 설치는 그 라이브러리의 문서를 우선하시면 됩니다.

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSCameraUsageDescription": "사진·영상 촬영을 위해 카메라 접근이 필요합니다.",
        "NSMicrophoneUsageDescription": "영상 녹화를 위해 마이크 접근이 필요합니다."
      }
    },
    "android": {
      "permissions": ["android.permission.CAMERA", "android.permission.RECORD_AUDIO"]
    }
  }
}

# 네이티브 반영 후 development build 생성·실행
npx expo prebuild
npx expo run:ios      # 또는 npx expo run:android

그림 4. react-native-vision-camera 공식 "Getting Started" 문서. Nitro Modules 기반이라 npm install로 본체와 Nitro 의존성을 함께 설치하고, 권한은 "Add permissions"의 Expo 탭에서 app.json의 ios.infoPlist·android.permissions로 넣습니다(별도 config plugin 항목 없음). 출처: react-native-vision-camera.com/docs/guides, 확인일 2026-07-17.

여기서 교훈은 하나입니다. 오래된 블로그의 설치법을 그대로 믿지 말고, 그 라이브러리의 현재 문서를 보세요. V4 설정을 그대로 복사하면 V5에서는 동작하지 않습니다. 앞서 EAS든 config plugin이든 "형식"을 익혔다면, 구체적인 값은 늘 라이브러리 현재 문서에서 가져오는 게 안전합니다.

⚠️ 여기서 자주 막힙니다

공식 문서에서 반복적으로 짚는 막힘 지점을 모았습니다.

• 네이티브 라이브러리를 추가했으면 다시 빌드해야 합니다. JavaScript 새로고침(Fast Refresh)으로는 네이티브 코드가 앱에 들어가지 않습니다. 설치만 하고 "왜 안 되지?" 하는 경우 대부분 여기입니다.
• android·ios 폴더를 손으로 고치지 마세요. npx expo prebuild --clean을 실행하면 그 폴더를 지우고 다시 만들어서 수정이 사라집니다. 네이티브 변경은 config plugin이나 app.json 필드로 하세요.
• dev build의 네이티브와 JS가 어긋나면 실행 시 문제가 납니다. 네이티브 의존성이나 설정을 바꿨으면 새 development build를 만들어야 합니다.
• 모든 라이브러리에 config plugin이 있는 건 아닙니다. 없으면 Expo의 out-of-tree config plugin 목록을 찾아보거나, 라이브러리의 수동 설정 안내를 따르거나, 직접 plugin을 작성합니다.
• 권한은 매니페스트를 직접 고치지 말고 app.json(또는 config plugin)으로 선언하세요. CNG가 다음 prebuild에서 덮어씁니다.

✅ 붙이기 전 체크리스트

붙이기 전에 이 순서대로만 짚어도 대부분의 삽질을 줄일 수 있습니다. 필요하면 복사해서 쓰세요.

[확인]
- [ ] 이 라이브러리가 Expo Go에서 되는지 확인 (reactnative.directory / npx expo-doctor)
- [ ] android·ios 디렉터리, linking, 매니페스트 수정, config plugin 여부 체크 → 하나라도 있으면 dev build

[설치·설정]
- [ ] npx expo install expo-dev-client
- [ ] 라이브러리 설치 (그 라이브러리의 현재 문서 기준 — 버전마다 다름)
- [ ] 권한/네이티브 설정: config plugin 또는 app.json 필드로 (네이티브 폴더 직접 수정 금지)

[빌드·실행]
- [ ] 로컬: npx expo run:ios / npx expo run:android
- [ ] 클라우드: eas build --profile development (developmentClient: true)
- [ ] npx expo start --dev-client 로 실행

[유지]
- [ ] 네이티브 라이브러리 추가·변경할 때마다 development build 다시 생성

🫡 마무리

정리하면, "Expo Go에서 안 된다"는 대부분 막힘이 아니라 범위를 벗어난 신호입니다. development build를 한 번 만들면 그 뒤로는 어떤 네이티브 라이브러리든 붙일 수 있고, JavaScript 수정은 예전처럼 빠르게 반영됩니다.

핵심은 두 가지입니다. 네이티브를 바꾸면 다시 빌드한다는 것, 그리고 라이브러리 설정은 오래된 글이 아니라 그 라이브러리의 현재 문서에서 가져온다는 것입니다.

이 글은 Expo vs React Native CLI에서 "Expo로 시작해도 네이티브는 development build로 붙이면 된다"고 한 부분의 실전편이었습니다. 아직 Expo와 순정 CLI 사이에서 고민 중이라면 그 글을 먼저 보셔도 좋습니다.

다음 글에서는 config plugin이 없는 라이브러리를 만났을 때, 아주 작은 config plugin을 직접 하나 만들어 보는 과정을 다뤄 보겠습니다.

읽어 주셔서 감사합니다 🙇

---

참고 자료

• Expo 공식 문서: Introduction to development builds
• Expo 공식 문서: Create a development build
• Expo 공식 문서: Use a development build
• Expo 공식 문서: Config plugins
• Expo 공식 문서: Continuous Native Generation (CNG)
• Expo 공식 문서: Using libraries (Expo Go 호환 판단)
• Expo 공식 문서: eas.json 빌드 프로필
• react-native-vision-camera 공식 문서