2026 HarmonyOS NEXT: React Native 서드파티 라이브러리를 바로 재사용할 수 있나요?

기존 앱의 라이브러리는 빌드되는데 핵심 기능이 하모니OS 넥스트 기기에서 동작하지 않습니다.
가장 빠른 판단은 안드로이드·아이오에스용 선언이나 자바스크립트 코드의 재사용을 호환성으로 간주하지 않고, RNOH 적응 패키지·버전·필요한 시스템 기능·기기 검증을 의존성마다 확인하는 것입니다.
이 글은 기존 리액트 네이티브 앱을 옮기는 기업 모바일 아키텍트, 고급 개발자, 테스트·배포 책임자를 위한 내용입니다.
라이브러리를 유지할지, 교체할지, 직접 적응할지 의존성 단위로 결정하는 데 초점을 둡니다.
코드 공유와 플랫폼 호환성의 차이
안드로이드나 아이오에스에서 쓰던 패키지 선언과 업무 로직 일부를 유지할 수는 있습니다. 하지만 패키지에 네이티브 코드가 들어 있다면, 해당 구현이 하모니OS 넥스트에서도 실행된다는 뜻은 아닙니다. 리액트 네이티브 문서는 플랫폼별 파일과 조건부 코드를 사용해 플랫폼 전용 구현을 구성하는 방법을 설명합니다. 이는 리액트 네이티브의 공통 원칙이지, 특정 라이브러리가 하모니OS를 지원한다는 보장은 아닙니다. 플랫폼별 코드 구성 방식을 실제 패키지의 파일과 구현에서 확인해야 합니다.
의존성은 다음처럼 먼저 나눌 수 있습니다.
- 공개된 RNOH 적응 패키지가 확인되는 의존성
- 플랫폼 중립적인 자바스크립트 구현이 중심인 의존성
- 다른 구현으로 대체할 수 있는 의존성
- 업무상 필수 기능이라 직접 적응을 검토해야 하는 의존성
이 분류는 조사 순서를 정하는 초안입니다. 최종 판정은 아닙니다. 자바스크립트 전용 패키지도 내부에서 사용하는 시스템 API나 네이티브 모듈이 있다면 별도 확인이 필요합니다.
RNOH는 커뮤니티 프로젝트입니다. 적응 자료에 이름이 올라 있다는 사실을 하모니OS 공식 호환 인증이나 제품 전체의 동작 보증으로 읽지 마세요.
적응 자료가 말해 주는 범위
RN 라이브러리에 RNOH 적응 버전이 있는지 어떻게 확인하나요?
RNOH의 서드파티 라이브러리 사용 자료에서 원래 라이브러리와 적응 패키지의 연결을 찾고, 해당 패키지의 사용 설명과 공개된 지원 범위를 확인합니다. 목록에 있다는 이유만으로 대상 앱에서 검증됐다고 판정하지 마세요. 문서가 접속 방법만 다루는지, 지원 기능이나 확인된 환경까지 명시하는지 구분해야 합니다.
구체적인 접속 문서도 범위를 좁혀 읽어야 합니다. 예를 들어 RNOH의 부트 스플래시 라이브러리 안내는 해당 라이브러리의 접속 자료입니다. 이 자료 하나가 모든 RNOH 버전이나 프로젝트 설정에서 동작한다는 뜻은 아닙니다. 패키지의 최근 변경 기록과 프로젝트에서 사용하는 설정이 맞는지 추가로 확인해야 합니다.
안드로이드·아이오에스 네이티브 코드만 제공하는 패키지는 적응 구현이 있는지 따로 찾아야 합니다. 플랫폼 중립적으로 보이는 패키지도 카메라, 알림, 파일 접근처럼 시스템 기능을 호출한다면 그 기능의 구현 경로를 확인합니다. 리액트 네이티브의 네이티브 모듈 안내는 자바스크립트와 네이티브 구현의 경계를 이해하는 데 참고할 수 있지만, 하모니OS 지원 여부를 대신 증명하지는 않습니다.
버전 기록과 프로젝트 조합
RNOH 라이브러리는 어떤 리액트 네이티브 버전과 맞춰야 하나요?
패키지 이름만으로 버전 호환성을 추정하지 말고, 프로젝트의 리액트 네이티브 버전, RNOH 버전, 적응 패키지 버전, 개발 도구 체인을 한 줄씩 대조합니다. 각 관계를 설명하는 문서나 배포 기록이 없으면 ‘호환’이 아니라 ‘확인 필요’로 남겨야 합니다.
RNOH 공개 배포 기록은 프로젝트 버전과 변경 사항을 대조하는 자료입니다. 리액트 네이티브의 플랫폼 확장 설명도 새 플랫폼 구현이 별도 플랫폼 작업을 수반한다는 점을 이해하는 데 유용합니다. 어느 쪽도 개별 서드파티 패키지의 호환 조합을 자동으로 보장하지 않으므로, 적응 패키지의 자체 안내와 함께 봐야 합니다.
버전 범위가 문서에 없거나, 공개 기록이 오래됐거나, 현재 의존성과 간격이 큰 경우에는 성공을 추정하지 않습니다. 지원 중단 여부가 불명확해도 동일하게 보류합니다. 이때 필요한 것은 근거가 있는 적응 자료 또는 대상 프로젝트에서의 검증입니다.
시스템 기능과 업무 동작의 등가성
빌드가 성공하거나 샘플 화면이 뜨는 것은 필요한 기능이 모두 충족됐다는 증거가 아닙니다. 실제 업무 흐름에 맞춰 다음을 확인합니다.
- 호출하려는 시스템 기능이 대상 환경에서 제공되는지
- 권한 요청과 거부·재요청 흐름이 업무 요구에 맞는지
- 네이티브 화면 요소의 표시, 입력, 이동 동작이 필요한 수준인지
- 앱이 백그라운드로 이동하거나 다시 활성화될 때 상태가 유지되는지
- 오류 응답과 예외 상황을 앱이 처리할 수 있는지
이 점검은 기능이 “실행되는가”와 “요구사항을 충족하는가”를 분리합니다. 예컨대 로그인 화면이 표시되더라도 실제 인증 복귀 흐름이 확인되지 않았다면, 그 라이브러리를 온전히 재사용할 수 있다고 결론 내리기 어렵습니다.
리액트 네이티브의 원래 네이티브 플랫폼 개념은 플랫폼 구현 설명에서 확인할 수 있습니다. 이를 하모니OS의 특정 기능 지원 선언으로 확대 해석하지 말고, 각 RNOH 적응 자료와 기기 결과를 별도로 기록하세요.
의존성별 점검과 기록
아래 항목을 실제 의존성마다 확인하면 누락을 줄일 수 있습니다.
- [ ] 원래 패키지와 사용 중인 기능을 앱에서 확인합니다.
- [ ] RNOH 적응 패키지와 공개 사용 자료가 있는지 찾습니다.
- [ ] 원래 패키지, 적응 패키지, 리액트 네이티브, RNOH의 버전 근거를 기록합니다.
- [ ] 네이티브 API, 네이티브 화면, 권한, 생명주기 의존성을 구분합니다.
- [ ] 대상 기기에서 업무에 필요한 정상·예외 흐름을 실행합니다.
- [ ] 유지 보수 상태, 알려진 미지원 기능, 담당자를 기록합니다.
- [ ] 증거가 부족한 항목은 위험 목록에 남기고 판정을 보류합니다.
판정에는 유지 보수 책임도 포함해야 합니다. 적응 패키지의 업데이트 기록과 문제 응답이 빈약하거나 업무 핵심 기능이 빠져 있다면, 초기 접속이 성공해도 장기 유지 비용이 커질 수 있습니다. 반대로 직접 적응은 핵심 기능을 온전히 통제할 수 있지만, 구현뿐 아니라 향후 리액트 네이티브·RNOH 변경에 대응할 책임도 팀에 남습니다.
보존·교체·자체 적응 비교
| 선택 | 적용 조건 | 이점 | 주의할 점 |
|---|---|---|---|
| 보존 | 대응 적응 패키지, 버전 근거, 업무 기능의 기기 검증이 모두 확인됩니다. | 기존 의존성과 업무 로직을 이어갈 여지가 있습니다. | 공개 목록만 확인하고 검증을 생략하면 미지원 기능을 놓칠 수 있습니다. |
| 교체 | 유지 관리가 더 나은 대안이 있고, 필요한 기능을 충족하는지 확인할 수 있습니다. | 관리 책임을 줄이고 기능 공백을 피할 수 있습니다. | 대체 라이브러리의 시스템 기능과 화면 동작도 다시 검증해야 합니다. |
| 자체 적응 | 업무 핵심 기능이며, 동등한 대안이 없고 적응 작업을 맡을 책임자가 정해져 있습니다. | 필요한 기능과 동작을 프로젝트에 맞출 수 있습니다. | 구현 이후의 버전 대응과 유지 보수 책임이 팀에 남습니다. |
| 의존성 기록 항목 | 기록할 근거와 결과 |
|---|---|
| 원래 라이브러리·사용 기능 | 실제 코드에서 호출하는 기능과 플랫폼별 구현 |
| RNOH 적응 패키지 | 패키지 식별 정보와 공개 사용 자료 |
| 버전 근거 | 리액트 네이티브·RNOH·적응 패키지·도구 체인의 문서 또는 배포 기록 |
| 기기 검증 | 실행한 업무 흐름, 결과, 미확인 범위 |
| 기능 공백·유지 상태 | 미지원 기능, 변경 기록, 응답 상태와 관리 책임자 |
| 최종 처분 | 보존·교체·자체 적응 또는 근거 확보까지 보류 |
결정 규칙은 단순합니다. 적응 자료와 버전 근거가 있고 업무 흐름이 대상 기기에서 확인되면 보존합니다. 유지가 불안하거나 동등한 대안이 검증되면 교체합니다. 핵심 기능을 대신할 수 없을 때만 자체 적응을 검토하고, 이후 유지 책임까지 별도 항목으로 확정합니다. 한 번의 빌드 성공으로 위험 목록을 닫지 않습니다.
병행 검증 환경과 마무리
의존성 표에서 하모니OS 검증과 별도로 아이오에스 빌드나 기존 맥 기반 업무가 필요한 항목을 추리면, 작업 환경의 요구사항도 명확해집니다. 클라우드 맥은 맥에서 수행하는 병행 개발·빌드 작업을 위한 선택지일 수 있지만, 하모니OS 도구 체인이나 대상 기기 검증을 대신하지는 않습니다. 환경 운용 관련 정보는 ProxyMac 도움말과 사용자 콘솔 안내에서 확인할 수 있습니다.
현재 맥 환경을 쓰는 방식은 물리 장비를 직접 관리할 수 있다는 장점이 있지만, 일시적인 병행 작업에도 장비 확보와 관리가 필요합니다. 다른 원격 환경은 맥 전용 작업 조건과 접근 방식을 먼저 따져야 하며, 로컬 환경은 장비와 개발 도구를 팀이 직접 유지해야 합니다. 병행 작업이 일시적이고 물리 인터페이스가 필요하지 않다면 ProxyMac의 맥 렌탈을 선택지로 검토할 수 있습니다. 장기간 지속되는 상시 작업이나 물리 장비가 꼭 필요한 경우에는 직접 보유가 더 맞을 수 있습니다. 어떤 선택이든 라이브러리 호환 판정은 실제 하모니OS 환경의 증거를 기준으로 해야 합니다.