React Native TurboModules: 플랫폼 기능은 어떻게 JavaScript API가 되는가

30초 요약

TurboModule은 다음 세 부분이 함께 있어야 동작한다.

Spec은 Specification(명세)의 줄임말로 함수와 데이터 타입을 선언한 파일이다. TypeScript와 Flow 표기는 JavaScript 코드에 타입 정보를 붙이는 두 방식이며, Codegen은 이 명세를 읽어 Android·iOS 연결 인터페이스를 만드는 코드 생성 도구다. TurboModuleRegistry는 모듈 이름으로 현재 실행 플랫폼에 등록된 모듈 객체를 찾는다.

TypeScript 또는 Flow Spec
  → Codegen이 만든 Android·iOS 연결 인터페이스
  → 그 인터페이스를 구현하고 등록한 플랫폼 코드

TurboModuleRegistry.get()은 모듈이 없으면 null을 반환하고, getEnforcing()은 반드시 있어야 한다는 가정이 깨지면 예외를 던진다. 어느 쪽이 더 안전한지는 이름이 아니라 제품의 플랫폼 지원 계약으로 결정한다.

이 글을 관통하는 상황: Android 선택 기능 때문에 iOS 화면이 열리지 않는다

가상의 영수증 앱은 초안 저장을 Android에서만 먼저 제공한다. Android에는 NativeReceiptStore 구현과 등록이 있고, iOS에는 의도적으로 아직 없다. Spec 인터페이스는 메서드 모양만 선언하지만, 같은 파일의 getEnforcing 호출은 모든 실행 플랫폼에 모듈이 반드시 있다고 가정한다.

코드의 payload는 영수증 초안을 JSON 문자열로 만든 입력이다. Promise<boolean>은 저장 결과가 나중에 성공 여부로 도착한다는 뜻이다. loadDraft는 저장한 문자열을 다시 읽고, 값이 없으면 null을 돌려주는 계약이다.

// specs/NativeReceiptStore.ts
import type { TurboModule } from 'react-native'
import { TurboModuleRegistry } from 'react-native'
 
export interface Spec extends TurboModule {
  saveDraft(id: string, payload: string): Promise<boolean>
  loadDraft(id: string): Promise<string | null>
}
 
export default TurboModuleRegistry.getEnforcing<Spec>('NativeReceiptStore')

기록을 보기 전에 먼저 예측한다.

1. TypeScript의 Spec이 존재한다는 사실이 iOS 구현의 존재도 보장하는가?
2. getEnforcing은 모듈이 없을 때 null과 예외 중 무엇을 만드는가?
3. 선택 기능이 없는 iOS에서 앱 전체 Render가 시작되지 않는 것이 의도한 제품 계약인가?

fixture, 즉 미리 준비한 가상 증거 묶음은 같은 JavaScript 코드를 양쪽 플랫폼에서 실행해 다음 결과를 기록했다. 실제 React Native의 고정 오류 문구가 아니라 결정적인 관찰만 정리한 기록이다.

Android module registration   NativeReceiptStore 있음
Android Registry lookup       NativeReceiptStore 모듈 객체 반환
Android App Render             완료
 
iOS module registration       NativeReceiptStore 없음
iOS Registry lookup           getEnforcing 예외
iOS App Render                시작 전 중단

이 사례의 iOS 미지원은 정상 제품 범위인데, 조회 방식은 모듈 부재를 프로그래밍 오류로 처리한다. 타입 선언은 존재하지만 플랫폼 구현·등록이 없고, import할 때 파일 최상위에서 즉시 실행되는 조회의 예외가 화면보다 먼저 발생한다.

TurboModule은 한 파일이 아니라 경계의 묶음이다

각 부분의 실패 표면도 다르다.

자세한 생성 설정과 산출물 읽기는 다음 7편에서 다룬다. 현재 편에서는 “선언·생성·구현·등록·소비” 중 어느 표면이 비어 있는지 나누는 판단만 남긴다.

get과 getEnforcing은 제품 지원 계약이 다르다

따라서 둘의 선택은 다음처럼 나뉜다.

관통 사례는 두 번째다. Spec의 마지막 줄만 다음처럼 바꾼다.

export default TurboModuleRegistry.get<Spec>('NativeReceiptStore')

이제 코드를 검사할 때 보이는 import 결과의 타입은 Spec | null이다. 앱이 실제로 실행될 때의 값은 Spec 계약으로 취급하는 등록된 모듈 객체 또는 null이며, 앱 화면은 부재를 명시적으로 처리한다.

import { useState } from 'react'
import { Pressable, Text, View } from 'react-native'
import NativeReceiptStore from './specs/NativeReceiptStore'
 
export default function App() {
  const [status, setStatus] = useState('초안 저장 대기')
  const isSupported = NativeReceiptStore !== null
 
  async function handleSave() {
    if (!NativeReceiptStore) {
      setStatus('이 기기에서는 초안 저장을 지원하지 않습니다.')
      return
    }
 
    setStatus('저장 중')
 
    try {
      const payload = JSON.stringify({ merchant: '동네 상점', total: 12900 })
      const saved = await NativeReceiptStore.saveDraft(
        'receipt-42',
        payload,
      )
 
      if (!saved) {
        setStatus('초안 저장 실패')
        return
      }
 
      const stored = await NativeReceiptStore.loadDraft('receipt-42')
      setStatus(stored === payload ? '초안 저장 확인 완료' : '초안 저장 확인 실패')
    } catch {
      setStatus('초안 저장 오류')
    }
  }
 
  return (
    <View style={{ padding: 24 }}>
      <Pressable disabled={!isSupported} onPress={handleSave}>
        <Text>{isSupported ? '초안 저장' : '초안 저장 미지원'}</Text>
      </Pressable>
      <Text>
        {isSupported ? status : '이 기기에서는 초안 저장을 지원하지 않습니다.'}
      </Text>
    </View>
  )
}

교정 후 같은 fixture에서 기대할 결과는 다음과 같다.

Android Registry lookup  NativeReceiptStore 모듈 객체 반환
Android App Render        완료
Android 저장 버튼         저장 중 → 초안 저장 확인 완료
 
iOS Registry lookup      null 반환
iOS App Render            완료
iOS 저장 버튼             미지원 문구 표시, 네이티브 함수 호출 없음

성공 조건은 iOS 앱이 단순히 종료되지 않는 데서 끝나지 않는다. Android는 실제 저장 결과를 다시 읽어 확인하고, iOS는 저장 함수를 호출하지 않은 채 명확한 미지원 상태를 보여야 한다. 제품 계약이 나중에 양쪽 필수로 바뀌면 iOS의 null을 허용하는 테스트도 실패하도록 함께 바꾼다.

지연 로드는 요청 시점을 없애지 않는다

그러나 Spec 파일이 평가되면서 TurboModuleRegistry.get이나 getEnforcing을 호출하면 그 시점에 모듈을 요청한다. 지연 로드는 다음을 자동으로 보장하지 않는다.

• JavaScript가 해당 Spec 파일을 언제 import하는지
• 모듈 생성자가 무거운 일을 하지 않는지
• 첫 기능 호출의 초기화 비용이 작은지

따라서 모듈의 초기화 로그나 추적을 “앱 시작”과 “첫 조회·첫 함수 호출”로 나눠 본다. 지연 로드라는 설명만으로 시작 시간이나 첫 사용 응답성을 측정했다고 결론 내리지 않는다.

동기 호출은 목표가 아니라 선택지다

4편에서 본 것처럼 직접 호출과 실제 작업 비용은 다른 문제다.

작고 즉시 준비되는 값       → 측정 후 동기 반환을 검토할 수 있음
저장·네트워크·큰 계산        → 완료·오류를 나중에 전달하는 비동기 계약 검토
UI 스레드나 JS 응답을 막는 일 → 네이티브라는 이유만으로 동기화하지 않음

관통 사례의 저장은 완료 또는 실패가 나중에 결정될 수 있으므로 Promise<boolean>로 선언했다. 실제 저장 매체의 완료 의미와 스레드는 Android·iOS 구현 계약에서 각각 정해야 한다.

타입 명세는 런타임 데이터 검증과 같지 않다

외부 입력이나 오래 저장된 데이터라면 JavaScript 경계 또는 각 플랫폼 구현에서 업무 구조를 검증해야 한다. Codegen이 어떤 플랫폼 코드를 만들고 어떤 오류를 빌드에서 잡는지는 7편의 한 질문으로 분리한다.

같은 상황을 다시 진단한다

문제       Android 선택 기능의 모듈이 없는 iOS에서 App Render 전 예외 발생
잘못된 판단 TypeScript Spec이 있으므로 모든 플랫폼에도 구현이 자동으로 존재함
관찰       Android Registry는 NativeReceiptStore 모듈 객체 반환, iOS getEnforcing은 예외
원인       의도된 선택 기능 부재를 '반드시 존재' 조회로 처리함
행동       get으로 조회하고 null을 명시적인 플랫폼 미지원 UI로 번역
검증       Android 실제 저장 확인, iOS는 네이티브 호출 없이 미지원 상태 표시

풀 리퀘스트에서는 다음을 확인한다.

• Spec, 생성된 인터페이스, 각 플랫폼 구현·등록을 하나의 계약으로 검토했는가?
• 기능이 필수인지 선택인지에 따라 getEnforcing과 get을 골랐는가?
• 지연 로드라는 이름 대신 초기화와 첫 호출 시점을 관찰했는가?
• 동기·Promise 반환을 실제 작업 성격과 실행 계약으로 선택했는가?
• 생성 타입과 런타임 payload 검증을 같은 것으로 보지 않았는가?
• Android와 iOS의 지원·부재 결과를 각각 확인했는가?

기억할 문장은 짧다.

TurboModule은 Spec 하나가 아니라 선언·생성·구현·등록·소비가 이어진 플랫폼 API 계약이다.

다음 글에서는 이 Spec에서 Android·iOS 연결 코드를 만드는 Codegen의 책임을 살펴본다.