Modal 은 React Native 가 기본으로 제공하는 코어 컴포넌트다. 현재 화면 위에 콘텐츠를 띄워 사용자의 흐름을 잠시 끊고 확인이나 입력을 받을 때 쓴다. 알림, 확인 다이얼로그, 이미지 뷰어, 짧은 폼 정도가 흔한 용도다.

이름만 보면 zIndex 를 크게 준 View 와 비슷해 보이지만 실제 동작은 다르다. Modal 은 네이티브 계층에서 별도의 표시 영역으로 올라간다. iOS 는 UIViewController 의 모달 프리젠테이션을 쓰고, Android 는 별도의 Dialog 윈도우로 렌더링된다. 여기서 말하는 윈도우는 운영체제가 화면에 무언가를 그리려고 할당하는 독립적인 표시 영역이다. 보통 "앱 화면 하나"가 윈도우 하나에 해당한다.

그래서 Modal 은 React Navigation 스택이든 앱 안의 어떤 zIndex 든 상관없이 항상 위에 떠 있다. 편리한 특성이지만 동시에 이 글 뒷부분에 나오는 제약들의 원인이기도 하다.

기본 사용법

import React, {useState} from 'react';
import {Modal, View, Text, Pressable, StyleSheet} from 'react-native';

export default function ModalExample() {
  const [visible, setVisible] = useState(false);

  return (
    <View style={styles.container}>
      <Pressable onPress={() => setVisible(true)}>
        <Text>모달 열기</Text>
      </Pressable>

      <Modal
        animationType="slide"
        transparent
        visible={visible}
        onRequestClose={() => setVisible(false)}>
        <View style={styles.backdrop}>
          <View style={styles.sheet}>
            <Text>모달 내용</Text>
            <Pressable onPress={() => setVisible(false)}>
              <Text>닫기</Text>
            </Pressable>
          </View>
        </View>
      </Modal>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {flex: 1, justifyContent: 'center', alignItems: 'center'},
  backdrop: {
    flex: 1,
    backgroundColor: 'rgba(0,0,0,0.5)',
    justifyContent: 'center',
    alignItems: 'center',
  },
  sheet: {
    backgroundColor: 'white',
    padding: 24,
    borderRadius: 12,
  },
});

패턴 자체는 단순하다. visible 을 부모 컴포넌트의 state 로 들고 있고, 닫히는 모든 경로에서 그 state 를 false 로 내려주면 된다.

주의할 점은 visible 이 false 인 동안 Modal 의 children 은 렌더되지 않는다는 것이다. 상태가 유지된 채 숨어 있는 게 아니라, 열 때마다 자식 트리 전체가 새로 마운트된다. 모달 안에 무거운 리스트나 차트가 있으면 여는 순간 그 마운트 비용을 한꺼번에 치른다.

커스텀 배경을 만들 거라면 transparent 는 사실상 필수다. 이걸 켜지 않으면 모달 컨테이너 자체가 backdropColor(기본 흰색)로 채워져서 뒤 화면이 보이지 않는다.

주요 Props

Modal 은 View Props 를 상속한다. 그 위에 Modal 고유의 props 가 얹힌다.

공통

iOS 전용

onDismiss 는 실무에서 생각보다 자주 쓰인다. 모달을 닫고 곧바로 다른 모달을 띄우거나 화면을 전환해야 할 때, 이 콜백을 기다리지 않으면 애니메이션이 꼬인다. Android 에는 대응되는 prop 이 없어서 플랫폼 분기가 필요하다.

Android 전용

Android 15 부터 edge-to-edge 가 강제되면서 앱 화면은 기본적으로 시스템 바 아래까지 그려진다. 그런데 Modal 은 별도의 Dialog 윈도우라서 앱 화면의 설정을 그대로 물려받지 않는 경우가 많다. 전체 화면을 덮는 모달을 만들었는데 상태바 영역만 색이 다르게 남는다면 이 두 prop 을 먼저 확인하면 된다.

자주 부딪히는 제약

한 번에 하나

Modal 은 동시에 하나만 안정적으로 표시된다. 모달을 닫으면서 곧바로 다른 모달을 띄우면 두 번째가 열리지 않거나 애니메이션이 어긋난다. 닫힘이 끝난 뒤에 다음 것을 여는 식으로 순서를 만들어야 한다.

// iOS: onDismiss 로 닫힘 완료를 기다린다
<Modal visible={firstVisible} onDismiss={() => setSecondVisible(true)} ... />

Android 에는 onDismiss 가 없으므로 애니메이션 길이만큼 setTimeout 을 두거나, 애초에 모달 하나 안에서 내용만 바꾸는 방식으로 설계하는 편이 낫다. 모달을 겹쳐 띄우는 UX 가 반복해서 필요하다면 빌트인 Modal 로는 한계가 분명하다.

onRequestClose 와 백 버튼

Android 에서는 onRequestClose 가 필수다. 빼먹으면 경고가 뜨고, 하드웨어 백 버튼으로 모달을 닫을 수 없게 된다.

더 중요한 건 모달이 열려 있는 동안 BackHandler 이벤트가 아예 발생하지 않는다는 점이다. 백 버튼은 오직 모달의 onRequestClose 로만 간다. 화면 단에서 BackHandler 로 뒤로가기를 가로채는 로직을 짜뒀다면, 모달이 열린 동안에는 그 로직이 통째로 무시된다고 보면 된다. 반대로 이 동작이 필요해서 Modal 을 쓰는 경우도 있다.

키보드

모달 안에서 TextInput 을 쓰면 키보드가 입력창을 가리는 문제가 iOS 에서 특히 자주 나온다. 모달 내부에도 KeyboardAvoidingView 를 따로 감싸야 한다.

Android 는 Dialog 윈도우가 액티비티의 windowSoftInputMode 를 그대로 따르지 않기 때문에, 앱 화면에서는 잘 동작하던 키보드 회피가 모달 안에서만 어색해지는 일이 생긴다. 이 경우 원인을 코드에서 찾기 어려워서 시간을 많이 쓰게 된다.

세이프 에어리어

모달 컨테이너는 앱 화면의 세이프 에어리어 컨텍스트 밖에 있다. 노치나 홈 인디케이터를 피하려면 모달 안에서 별도로 처리해야 한다. react-native-safe-area-context 를 쓴다면 모달 내부를 SafeAreaProvider 로 다시 감싸거나, initialWindowMetrics 를 넘겨줘야 값이 제대로 잡힌다.

presentationStyle 과 transparent 조합

pageSheet 나 formSheet 는 iOS 가 그리는 시트 형태의 프리젠테이션이다. 여기에 transparent={true} 를 같이 주면 의도한 대로 동작하지 않는다. 시트 스타일은 투명 배경을 전제로 만들어진 게 아니기 때문이다. 커스텀 backdrop 이 필요하면 overFullScreen 을 쓰고 배경을 직접 그리는 쪽이 맞다.

대안 라이브러리

빌트인 Modal 로 부족하다고 느낄 때 흔히 쓰는 선택지들이다.

react-native-modal 은 빌트인 Modal 을 래핑한 것이라, 뒤에서 다룰 Android 의 별도 윈도우 문제는 그대로 안고 간다. 성능 때문에 대안을 찾는 상황이라면 이쪽이 아니라 Portal 계열을 봐야 한다.

정리

Modal 은 화면 위에 무언가를 잠깐 띄우는 가장 간단한 방법이다. 확인 다이얼로그나 단순한 알림 정도라면 빌트인으로 충분하고, 굳이 라이브러리를 붙일 이유가 없다.

다만 Modal 이 일반 View 가 아니라 네이티브의 별도 표시 영역이라는 사실은 기억해둘 필요가 있다. 한 번에 하나만 열린다는 점, 백 버튼이 가로채진다는 점, 세이프 에어리어와 키보드 처리가 앱 화면과 따로 논다는 점은 전부 이 구조에서 나온다. 제약을 만났을 때 코드가 아니라 구조를 의심해야 답이 빨리 나온다.

모달 내부에 상태 변경이 잦거나 무거운 자식 트리가 있다면 Android 에서 체감 성능이 눈에 띄게 나빠지는데, 이건 사용법으로 해결되는 문제가 아니다. 그 원인과 대안은 이어지는 두 글에서 다룬다.

앞 편들에서 dev/beta/pro 세 환경을 TestFlight·Play Store까지 올리는 뼈대를 완성했다. 이번 편은 그 위에 얹는 마감 작업 세 가지를 다룬다.

1. 환경별 아이콘·표시 이름 분리 — 한 폰에 dev/beta/pro를 깔았을 때 눈으로 구분되게
2. 버저닝 전략 고도화 — 대화형 입력·하드코딩에서 벗어나 버전 충돌을 구조적으로 막기
3. CI 연동 — 내 맥이 아니라 서버가 대신 빌드·배포하게 만들기

셋 다 "없어도 배포는 되지만, 팀이 커지면 반드시 아쉬워지는" 것들이다.

1. 환경별 아이콘·표시 이름 분리

왜 필요한가

앞 편에서 번들 ID/패키지명을 환경별로 나눴으니, 한 폰에 dev/beta/pro 세 앱이 동시에 깔린다. 그런데 아이콘과 이름이 다 똑같으면 홈 화면에 회색 아이콘 세 개가 나란히 떠서 어느 게 어느 빌드인지 알 수가 없다. QA가 "버그 재현됐어요" 했는데 알고 보니 dev 앱이었던 상황이 여기서 나온다.

목표는 간단하다. 이름에 접미사(MyApp / MyApp Beta / MyApp Dev)를 붙이고, 아이콘에 뱃지(DEV/BETA 리본)를 얹어 한눈에 구분되게 하는 것이다.

표시 이름 — 이미 절반은 해둔 상태

사실 이름 분리는 앞 편에서 이미 하고 있었다.

• iOS: update_info_plist(display_name: "MyApp-dev")로 lane마다 다른 이름을 넣었다.
• Android: 셸 스크립트(change_package_name.sh 계열)가 환경 전환 시 app_name 문자열을 바꾸거나, flavor를 쓴다면 resValue "string", "app_name", "MyApp Dev"로 지정한다.

즉 표시 이름은 이미 환경별로 다르게 나온다. 남은 건 아이콘이다.

아이콘 분리 — iOS

iOS 아이콘은 Assets.xcassets 안의 App Icon 세트로 관리된다. 환경별로 다른 아이콘을 쓰는 방법은 크게 둘이다.

방법 A — 아이콘 세트를 여러 개 두고 빌드 설정으로 고르기 Assets.xcassets에 AppIcon-Dev, AppIcon-Beta, AppIcon 세트를 각각 만들고, 어떤 세트를 쓸지 ASSETCATALOG_COMPILER_APPICON_NAME 빌드 설정으로 정한다. Build Configuration별 .xcconfig(빌드 설정을 파일로 빼둔 것)에 이렇게 적는다.

// Dev.xcconfig
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon-Dev

방법 B — 셸 스크립트로 아이콘 파일을 갈아끼우기 (이 시리즈 방식) 우리 프로젝트는 환경을 셸 스크립트로 전환하므로, 아이콘도 같은 결로 처리하는 게 자연스럽다. copy_config.sh가 Firebase 설정을 복사하듯, 환경별 아이콘 이미지를 AppIcon.appiconset에 덮어쓰게 한 줄 추가하면 된다.

# copy_config.sh 안 (개념 예시)
cp "icons/$1/"*.png "MyApp/Images.xcassets/AppIcon.appiconset/"
# $1 = dev / beta / pro

방법 A가 더 "정석"이지만, 셸 스크립트 방식과 섞으면 관리 포인트가 둘로 갈린다. 이미 스크립트로 환경을 가르고 있다면 방법 B로 통일하는 게 덜 헷갈린다.

아이콘 분리 — Android

Android 아이콘은 android/app/src/main/res/mipmap-*/ 폴더의 ic_launcher 이미지들이다.

flavor를 쓰는 경우: src/dev/res/mipmap-*/, src/beta/res/mipmap-*/에 각 환경 아이콘을 넣으면 gradle이 알아서 main의 것을 덮어쓴다. 별도 코드가 필요 없어 가장 깔끔하다.

셸 스크립트를 쓰는 경우(이 시리즈): change_package_name.sh 계열이 환경 전환 시 해당 환경의 mipmap을 main/res로 복사하게 한다. iOS 방법 B와 같은 발상이다.

뱃지(리본) 자동 생성 — 팁

아이콘을 환경마다 손으로 그리기 귀찮다면, fastlane의 badge 플러그인으로 운영 아이콘 위에 DEV/BETA 리본을 자동 합성할 수 있다.

bundle exec fastlane add_plugin badge

# lane 안에서 (dev/beta일 때만)
add_badge(shield: "DEV-blue-orange", dark: true)   # 아이콘 모서리에 리본

원본 아이콘 하나만 관리하고, 나머지는 빌드 때 리본을 얹어 만들면 유지보수가 편하다. 단, CI에서 아이콘을 매번 변형하므로 원본이 커밋 대상에서 바뀌지 않게 주의한다.

2. 버저닝 전략 고도화

지금 방식의 한계

앞 편의 실제 Fastfile을 떠올리면, 버전 관리가 이랬다.

• dev/beta: 실행할 때 사람이 확인/입력 (UI.confirm / UI.input)
• pro: 코드에 버전을 하드코딩
• 빌드 번호/versionCode: 로컬 파일 값 +1

이건 혼자 로컬에서 돌릴 땐 잘 굴러가지만, 아래 상황에서 깨진다.

• 여러 명이 배포하면, 각자 로컬의 빌드 번호가 달라 충돌한다. (A가 42로 올렸는데 B의 로컬은 아직 40이라 41로 올리려다 거부당함)
• CI에서 자동 배포하려면 대화형 프롬프트(UI.input)가 사람 입력을 기다리다 멈춘다.
• iOS와 Android 버전이 따로 논다. 마케팅 버전을 양쪽에서 각자 관리하다 어긋난다.

핵심 원칙은 하나다. 버전의 "정답"을 한 곳에만 두고, 나머지는 거기서 계산되게 한다.

전략 1 — 빌드 번호는 "스토어 기준"으로 자동 계산

로컬 값 +1 대신, 스토어에 이미 올라간 최댓값 +1을 쓰면 누가 어디서 돌리든 충돌이 안 난다.

# iOS
increment_build_number(
  build_number: latest_testflight_build_number(app_identifier: ENV["APP_IDENTIFIER"]) + 1
)

# Android
latest = google_play_track_version_codes(
  package_name: ENV["PACKAGE_NAME"], track: "internal", json_key: ENV["PLAY_STORE_JSON_PATH"]
).max || 0
new_version_code = latest + 1

이러면 빌드 번호는 사람이 신경 쓸 필요가 없어진다. 환경별 번들 ID/패키지명이 다르므로 app_identifier·package_name을 꼭 같이 넘겨, 환경별로 독립적인 번호가 유지되게 한다.

전략 2 — 마케팅 버전은 단일 소스에서 읽기

마케팅 버전(1.2.11 같은 사용자용 버전)은 한 파일에서 읽어 iOS·Android가 같은 값을 쓰게 한다. RN 프로젝트라면 package.json의 version을 소스로 삼는 게 자연스럽다. (RN 개발자에게 가장 익숙한 위치다.)

# Fastfile 공통 (ios/android 양쪽에서)
require 'json'
pkg = JSON.parse(File.read("../../package.json"))   # 경로는 프로젝트에 맞게
marketing_version = pkg["version"]                   # 예: "1.2.11"

# iOS
increment_version_number(version_number: marketing_version)
# Android
android_set_version_name(version_name: marketing_version)

이제 배포 전에 package.json의 버전만 올리면(예: npm version patch), iOS·Android가 자동으로 같은 마케팅 버전을 쓴다. 버전이 양쪽에서 어긋나는 문제가 사라진다.

npm version patch는 package.json의 버전을 1.2.11 → 1.2.12로 올리고 git 태그까지 만들어주는 npm 기본 명령이다. 이걸 "버전 올리는 공식 절차"로 정하면 팀 규칙이 단순해진다.

전략 3 — CI에서는 대화형을 끄기

UI.confirm/UI.input은 사람이 있을 때만 쓸 수 있다. CI에서는 이 부분을 건너뛰고 값을 자동으로 정하게 분기한다. fastlane은 지금이 대화형인지 아닌지를 UI.interactive?로 알려준다.

if UI.interactive?
  # 로컬: 기존처럼 확인/입력 받기
  new_version = UI.confirm("...") ? suggested : UI.input("...")
else
  # CI: 물어보지 않고 자동값 사용
  new_version = suggested_version
end

이렇게 두면 로컬에서는 지금처럼 확인 절차가 살아있고, CI에서는 멈추지 않고 자동으로 굴러간다. 하나의 lane으로 두 환경을 다 커버할 수 있다.

정리하면

3. CI 연동

왜 필요한가

지금은 배포하려면 내 맥에서 명령을 쳐야 한다. 이 방식의 문제는 이렇다.

• 배포할 수 있는 사람이 특정 맥을 가진 사람으로 한정된다.
• 그 사람 로컬 환경(Xcode 버전, 인증서 상태 등)에 따라 결과가 달라진다.
• 빌드 도는 20~40분 동안 그 맥을 못 쓴다.

CI(Continuous Integration)는 이걸 서버가 대신 하게 만든다. "main에 태그가 붙으면 자동으로 beta 배포" 같은 규칙을 걸어두면, 사람은 버튼만 누르거나 태그만 밀면 된다. 여기서는 가장 널리 쓰는 GitHub Actions 기준으로 설명한다. (Bitrise·Codemagic 같은 SaaS도 있지만, 원리는 같다.)

CI에서 달라지는 것들

로컬과 CI의 결정적 차이는 CI에는 아무것도 미리 깔려 있지 않다는 점이다. 인증서도, keystore도, Node도, Ruby도 매번 새로 준비해야 한다. 그래서 두 가지를 챙겨야 한다.

1) 비밀값은 CI Secrets로 주입. 인증서 비번, API 키, keystore, service account JSON 등을 코드에 두면 안 되니, GitHub의 Secrets(암호화 저장소)에 넣고 워크플로에서 꺼내 쓴다. 파일(예: .p8, .keystore, .json)은 base64로 인코딩해 Secret에 넣고, CI에서 디코딩해 파일로 복원하는 게 표준이다.

# 로컬에서 파일을 base64 문자열로 변환 → 이 값을 Secret에 붙여넣음
base64 -i AuthKey_XXX.p8 | pbcopy

2) 인증서·keychain 준비. iOS는 CI용 임시 키체인이 필요하다. fastlane의 setup_ci가 이걸 만들어 잠금을 풀어준다. 그리고 match는 CI에서 새 인증서를 만들지 않도록 readonly: true로 부른다. (안 그러면 CI가 실수로 인증서를 발급해 개발자 계정 한도에 걸린다.)

before_all do
  setup_ci if ENV["CI"]                 # CI 환경이면 임시 키체인 준비
end
# match 호출 시
match(type: "appstore", readonly: ENV["CI"] ? true : false)

플랫폼별 러너 선택

• iOS: 반드시 macOS 러너여야 한다. 그리고 이 시리즈 앞부분에서 다뤘듯, 2026년 현재 App Store 제출은 Xcode 26 이상을 요구하므로 러너의 Xcode 버전을 26으로 맞춰야 한다.
• Android: Linux(ubuntu) 러너면 충분하다. macOS보다 빠르고 저렴하다.

GitHub Actions 예시 — Android (ubuntu)

# .github/workflows/android-deploy.yml
name: Android Deploy

on:
  workflow_dispatch:          # 수동 실행 버튼
    inputs:
      lane:
        description: "dev / beta / pro"
        required: true
        default: "beta"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: yarn
      - run: yarn install --frozen-lockfile

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17

      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true      # Gemfile 기반 캐시 자동

      # Secret에 base64로 넣어둔 파일들을 복원
      - name: Restore secrets
        run: |
          echo "${{ secrets.PLAY_STORE_JSON_BASE64 }}" | base64 -d > android/play-service-account.json
          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 -d > android/app/upload.keystore

      - name: Fastlane
        working-directory: android
        env:
          PLAY_STORE_JSON_PATH: ${{ github.workspace }}/android/play-service-account.json
          KEYSTORE_PATH: ${{ github.workspace }}/android/app/upload.keystore
          SIGNING_STORE_PASSWORD: ${{ secrets.ANDROID_STORE_PASSWORD }}
          SIGNING_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
          SIGNING_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
        run: bundle exec fastlane ${{ github.event.inputs.lane }} --env ${{ github.event.inputs.lane }}

GitHub Actions 예시 — iOS (macOS)

# .github/workflows/ios-deploy.yml
name: iOS Deploy

on:
  workflow_dispatch:
    inputs:
      lane:
        description: "dev / beta / pro"
        required: true
        default: "beta"

jobs:
  deploy:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      # Xcode 26 고정 (App Store 제출 요구사항)
      - uses: maxim-lobanov/setup-xcode@v1
        with:
          xcode-version: "26"

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: yarn
      - run: yarn install --frozen-lockfile

      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true

      - name: Restore App Store Connect API key
        run: |
          mkdir -p ios/fastlane
          echo "${{ secrets.ASC_API_KEY_BASE64 }}" | base64 -d > ios/fastlane/AuthKey.p8

      - name: Fastlane
        working-directory: ios
        env:
          CI: true
          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
          MATCH_GIT_BASIC_AUTHORIZATION: ${{ secrets.MATCH_GIT_AUTH }}   # 인증서 repo 접근용
          APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.ASC_KEY_ID }}
          APP_STORE_CONNECT_API_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
          APP_STORE_CONNECT_API_KEY_PATH: ${{ github.workspace }}/ios/fastlane/AuthKey.p8
        run: |
          bundle exec pod install --project-directory=. || true
          bundle exec fastlane ${{ github.event.inputs.lane }} --env ${{ github.event.inputs.lane }}

위 두 예시의 env 블록에 넣은 변수 이름은 앞 편에서 lane이 ENV[...]로 읽던 그 이름들과 정확히 일치해야 한다. CI는 결국 "로컬에서 .env가 하던 역할을 Secrets가 대신하는 것"뿐이다.

대화형 lane을 CI에서 돌리기

앞 편 실제 lane에는 UI.confirm/UI.input이 있었다. 버저닝 전략 3에서 만든 UI.interactive? 분기가 여기서 빛을 발한다. CI에서는 UI.interactive?가 false라 프롬프트를 건너뛰고 자동 버전으로 진행하므로, lane을 고치지 않고도 로컬·CI 양쪽에서 같은 lane을 쓸 수 있다. (이 분기가 없다면 CI가 입력을 기다리다 타임아웃으로 죽는다.)

언제 자동으로 돌릴까 — 트리거

위 예시는 버튼으로 돌리는 workflow_dispatch만 걸었다. 익숙해지면 트리거를 넓힐 수 있다.

• git 태그 푸시 → 자동 배포: v1.2.12 태그를 밀면 pro 배포. (on: push: tags: ['v*'])
• 특정 브랜치 머지 → beta 배포: develop에 머지되면 beta.

단, pro(운영) 자동화는 신중히 한다. 앞 편에서 Android가 internal/draft로만 올리고 사람이 승급하게 한 것과 같은 맥락으로, 운영 배포는 사람의 명시적 확인을 한 단계 두는 게 안전하다.

마무리 — 시리즈 전체 정리

이번 시리즈를 통해 다음을 만들었다.

• ✅ Fastlane 환경 세팅 (Ruby/Bundler/Gemfile)
• ✅ iOS: match로 인증서 공유, dev/beta/pro 환경 분리, TestFlight 자동 업로드
• ✅ Android: keystore·Play App Signing·Service Account, 환경 분리, Play Store 자동 업로드
• ✅ 환경별 아이콘·표시 이름 분리로 한 폰에서 세 빌드 구분
• ✅ 단일 소스 기반 버저닝 + 스토어 기준 빌드 번호 + CI 대응 분기
• ✅ GitHub Actions로 빌드·배포를 서버에 위임

핵심은 처음부터 끝까지 하나였다. 손으로 하던 배포의 각 단계를 코드로 옮기고, 그 코드가 로컬이든 CI든 똑같이 돌게 만드는 것. Fastlane은 그 단계들을 대체한 게 아니라 "호출"했을 뿐이고, 우리는 그 호출을 환경별로·플랫폼별로·자동으로 엮었다.

여기서 더 나아가고 싶다면 다음을 살펴보면 좋다: Slack 배포 알림(slack 액션), 크래시 심볼 업로드(dSYM → Sentry/Firebase), 스토어 메타데이터·스크린샷 자동화(deliver/supply의 metadata 기능), 그리고 자동 changelog 생성.

reanimated, gesture-handler, mmkv, vision-camera 같이 네이티브 코드를 포함한 라이브러리를 다룰 때, 실무에서 반복적으로 부딪히는 것들만 추렸다. 한 줄 요약하면 "JS 패키지만 올리면 끝이 아니다. 플랫폼별 한 단계가 더 필요하다" 가 전부다.

공통: 설치/업그레이드 직후 워크플로우

라이브러리를 추가하거나 버전을 올린 직후 매번 돌리는 시퀀스이다.

# 1) JS 의존성 동기화
pnpm install   # 또는 yarn / npm
# 2) iOS 네이티브 의존성 동기화
cd ios && bundle exec pod install && cd ..
# 3) Android 빌드 캐시 정리
cd android && ./gradlew clean && cd ..

이 세 단계를 빼먹으면 거의 모든 빌드 문제가 여기서 비롯된다. JS 버전과 네이티브 측 버전이 동기화되어야 헤더/심볼 mismatch가 나지 않는다.

iOS 핵심

1. pod install은 무조건 실행이다

RN 0.60+의 autolinking은 JS 의존성을 감지하는 것까지만 해준다. 실제로 네이티브 의존성을 받아오고 Podfile.lock을 갱신하는 건 pod install의 몫이다. JS 패키지를 업그레이드한 뒤 pod install을 안 돌리면 JS와 네이티브 버전이 어긋나 빌드가 멈춘다. 확인 방법: Podfile.lock의 해당 pod 버전이 package.json 버전과 일치하는지 본다.

2. 빌드가 이상하면 캐시 두 곳을 비운다

iOS 빌드 캐시는 두 군데에 있다.

# Pod 산출물
cd ios
rm -rf Pods Podfile.lock build
bundle exec pod install
cd ..
# DerivedData
rm -rf ~/Library/Developer/Xcode/DerivedData/<프로젝트명>-*

업그레이드 후 빌드가 깨지면 이 두 군데부터 의심한다.

3. pnpm을 쓴다면 node-linker=hoisted

pnpm 기본 isolated 모드(node_modules/.pnpm/...)는 CocoaPods 스크립트와 충돌이 잦다. 프로젝트 루트 .npmrc에 다음을 박아두면 마찰이 사라진다.

node-linker=hoisted

4. New Architecture 모드를 명시적으로 통제한다

RN 0.76+부터 New Architecture가 기본 활성화이다. reanimated, gesture-handler 같은 라이브러리는 모드별로 동작 코드가 달라진다. 의도와 다르게 빌드되는 걸 막으려면 환경 변수로 명시한다.

RCT_NEW_ARCH_ENABLED=1 bundle exec pod install   # 켜기
RCT_NEW_ARCH_ENABLED=0 bundle exec pod install   # 끄기

5. Xcode 15+ 에서 빌드 스크립트가 멈추면 샌드박싱 의심

Xcode 15부터 ENABLE_USER_SCRIPT_SANDBOXING이 기본 YES로 바뀌었다. RN의 일부 Pod 스크립트 페이즈와 충돌한다. Podfile의 post_install에서 끈다.

post_install do |installer|
  react_native_post_install(installer, config[:reactNativePath])
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
    end
  end
end

Android 핵심

1. ./gradlew clean이 iOS의 pod install에 해당한다

Android는 별도의 "install" 명령이 없는 대신, Gradle이 빌드 시점에 node_modules를 스캔해서 네이티브 의존성을 결정한다. 라이브러리 변경 직후에는 이전 빌드 산출물이 캐시되어 있을 수 있으므로 clean을 돌려야 한다.

cd android && ./gradlew clean && cd ..

2. Kotlin 버전 불일치가 가장 흔한 빌드 실패 원인이다

라이브러리들이 요구하는 Kotlin 버전이 제각각이라, 새 라이브러리를 추가하면 충돌이 자주 난다. 증상은 compileKotlin 단계에서 실패하거나 Unresolved reference 에러이다. 해결책은 프로젝트의 kotlinVersion을 요구 버전 중 가장 높은 것에 맞춰 올리는 것이다.

// android/build.gradle
buildscript {
    ext {
        kotlinVersion = "2.0.21"  // 라이브러리 요구치 이상으로
    }
}

3. JDK 버전이 AGP와 맞아야 한다

RN 0.73+는 JDK 17이 필요하다. JDK 버전이 안 맞으면 Unsupported class file major version 에러가 난다.

java -version                          # 현재 버전 확인
export JAVA_HOME=$(/usr/libexec/java_home -v 17)   # macOS에서 JDK 17 강제

4. 릴리스 빌드만 깨지면 ProGuard 의심

디버그는 통과하는데 릴리스에서만 크래시하거나 빌드가 깨지면, 새 라이브러리가 리플렉션을 쓰는데 ProGuard 규칙이 없을 가능성이 높다. 라이브러리 README의 ProGuard 섹션을 확인하고 android/app/proguard-rules.pro에 규칙을 추가한다.

5. 큰 업그레이드 후엔 에뮬레이터/디바이스의 앱을 한 번 지운다

네이티브 모듈의 ABI가 바뀌면 부분 업데이트로 인해 런타임 크래시가 난다. 안전하게는 앱을 삭제한 뒤 다시 설치한다.

업그레이드 후 검증 순서

1. package.json + lockfile 갱신 확인
2. iOS:  bundle exec pod install
3. Android: ./gradlew clean
4. 빌드 → 시뮬레이터/에뮬레이터에서 동작 확인
5. 깨지면 → 캐시(DerivedData, Pods, android/build) 정리 후 재시도
6. 그래도 깨지면 → 라이브러리 README의 "Installation" 다시 읽기
   (peer dependency, post_install, ProGuard 규칙 등 누락 항목 체크)

정리

세 줄로 요약하면 이게 다이다.

1. JS 패키지 갱신 직후 항상 pod install + ./gradlew clean을 같이 돌린다.
2. 버전이 어긋나면 캐시부터 의심한다 — iOS는 DerivedData와 Pods, Android는 android/build.
3. 빌드 도구 호환성을 확인한다 — iOS는 Xcode 버전, Android는 Kotlin/JDK 버전. 라이브러리 README의 Installation 섹션을 꼼꼼히 읽고, 위 워크플로우만 빠뜨리지 않으면 대부분의 문제는 비껴간다.

AppState는 React Native가 제공하는 모듈로, 앱이 포그라운드에 있는지 백그라운드에 있는지를 알려준다. AppState.currentState는 그중에서 현재 앱 상태를 동기적으로 읽을 수 있는 정적 프로퍼티이다.

import { AppState } from 'react-native';

console.log(AppState.currentState); // 'active'

이벤트를 기다리지 않고 즉시 현재 값을 얻는 용도이며, 상태 변화를 추적하려면 별도의 리스너가 필요하다.

가능한 값

Android에는 inactive가 없다. 포그라운드 → 백그라운드가 곧바로 전환된다. 따라서 inactive에 의존하는 로직을 짜면 Android에서 동작하지 않는다.

주의점: currentState는 스냅샷이다

currentState는 읽는 시점의 값일 뿐 반응형(reactive) 값이 아니다. 렌더 함수 안에서 직접 참조하면 상태가 바뀌어도 리렌더가 발생하지 않아 stale한 값을 보게 된다.

// 나쁜 예: 상태가 바뀌어도 리렌더되지 않는다
function Screen() {
  return <Text>{AppState.currentState}</Text>;
}

또한 앱 초기 마운트 시점에 null이 반환될 수 있다. 네이티브 초기화가 끝나기 전에 접근하는 경우이며, 초기값 처리를 항상 방어적으로 해야 한다.

올바른 사용 패턴

currentState는 초기값으로만 쓰고, 이후 변화는 addEventListener로 추적하는 것이 정석이다.

import { useEffect, useRef, useState } from 'react';
import { AppState, AppStateStatus } from 'react-native';

export function useAppState() {
  const appState = useRef<AppStateStatus>(AppState.currentState);
  const [state, setState] = useState<AppStateStatus>(AppState.currentState);

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (next) => {
      if (appState.current.match(/inactive|background/) && next === 'active') {
        // 백그라운드 → 포그라운드 복귀 시점
        // 토큰 갱신, 데이터 리페치 등을 여기서 처리한다
      }
      appState.current = next;
      setState(next);
    });

    return () => subscription.remove();
  }, []);

  return state;
}

구독 해제 방식

RN 0.65부터 addEventListener는 subscription 객체를 반환한다. 구버전의 AppState.removeEventListener('change', handler)는 제거되었으므로, 반드시 subscription.remove()를 사용해야 한다.

실전 활용 예

• 세션 만료 처리: 백그라운드에 머문 시간을 재서 일정 시간이 지나면 재인증을 요구한다.
• 데이터 리페치: 복귀 시 서버 데이터를 다시 가져온다. React Query의 focusManager도 내부적으로 AppState를 쓴다.
• 타이머 보정: 백그라운드에서 setInterval은 신뢰할 수 없으므로, 복귀 시 실제 경과 시간을 다시 계산한다.
• 민감 정보 가리기: iOS에서 inactive 진입 시 앱 스위처 스냅샷을 블러 처리한다. Android는 FLAG_SECURE가 더 적합하다.

정리

• AppState.currentState는 현재 값을 즉시 읽는 용도이지 상태 관리 수단이 아니다.
• 초기값으로만 쓰고 변화 추적은 addEventListener + subscription.remove()로 한다.
• inactive는 iOS 전용이므로 플랫폼 분기를 고려해야 한다.
• 초기 마운트 시 null이 나올 수 있으니 방어 코드를 넣는다.

출시 준비를 "스토어 심사를 통과하는가"로만 보면 절반만 보는 것이다. 실제로 문제가 되는 건 올린 뒤다. 디버그에서 멀쩡하던 화면이 릴리스 빌드에서 흰 화면이 되고, 심사에서 막히는 지점은 대부분 코드가 아니라 정책 신고 항목이며, 출시 후에 가장 아쉬운 건 크래시가 났는데 그 사실조차 몰랐다는 상황이다.

이 글은 그 세 가지를 단계별로 정리한 체크 리스트다. 릴리스 빌드에서만 드러나는 문제, 스토어 정책 때문에 리젝당하는 지점, 그리고 운영을 시작하고 나서 후회하는 부분을 순서대로 다룬다. 날짜가 걸린 정책 항목은 2026년 9월 기준이다.

검증 전제

체크 리스트를 돌리기 전에 검증 환경부터 맞춰야 한다. 아래 세 가지가 어긋나면 그 뒤의 모든 확인이 의미가 없다.

릴리스 빌드로만 검증한다. 디버그 빌드는 Metro 서버에 의존하고 JS를 런타임에 평가한다. 프로덕션은 번들이 앱 안에 포함되고 최적화와 난독화가 켜진 상태다. 실행 조건 자체가 다르기 때문에 "디버그에서는 됐다"는 아무 근거가 되지 못한다. iOS는 --mode Release, Android는 assembleRelease 또는 bundleRelease 산출물로 테스트한다.

진짜 콜드 스타트로 검증한다. 개발 중에 쓰는 reload는 네이티브 프로세스를 살려둔 채 JS만 다시 초기화한다. 영속 저장 누락이나 초기화 순서 버그는 이 방식으로는 절대 재현되지 않는다. 앱을 스와이프로 완전히 종료한 뒤 다시 실행해서 확인한다.

실기기에서 검증한다. 시뮬레이터와 에뮬레이터는 메모리, CPU, 네트워크 조건이 실기기와 다르다. 특히 저사양 안드로이드 기기는 반드시 한 대 포함한다. 리스트 스크롤이 버벅이는지, 콜드 스타트가 몇 초 걸리는지는 그 기기에서만 드러난다.

빌드와 릴리스 설정

공통

• __DEV__ 분기 코드가 프로덕션으로 새어 들어가지 않는지 확인한다. 디버그 전용 로깅, 목업 데이터, 테스트 플래그가 대표적인 후보다.
• console.log는 릴리스 빌드에서 제거한다. Hermes에서도 과도한 로깅은 비용이고, 민감 정보가 그대로 찍히는 사고도 흔하다. babel-plugin-transform-remove-console을 릴리스 환경에만 적용한다.
• 소스맵을 생성해 크래시 리포팅 도구에 업로드한다. 난독화와 minify를 거친 스택트레이스는 소스맵 없이는 읽을 수 없다.
• 버전은 두 축으로 관리한다. 사용자에게 보이는 versionName / CFBundleShortVersionString과 빌드 식별자인 versionCode / CFBundleVersion을 분리하고, 빌드 넘버 자동 증가는 CI에 넣는다.

Android

• AAB로 출시한다. Play Store는 APK 직접 업로드를 받지 않는다. ./gradlew bundleRelease로 만든다.
• R8을 켠다. minifyEnabled true, shrinkResources true. 다만 켜는 순간 리플렉션에 의존하는 라이브러리가 깨질 수 있다. proguard-rules.pro에 keep 규칙을 추가하고, R8을 켠 릴리스 빌드로 전 기능 회귀 테스트를 한 번 돌린다. 난독화 관련 버그는 거의 예외 없이 릴리스에서만 나타나기 때문에, 이 테스트를 건너뛰면 사용자가 먼저 발견한다.
• ABI 분할 또는 AAB의 자동 분할로 불필요한 아키텍처를 제외해 다운로드 용량을 줄인다.
• android:debuggable이 릴리스에서 false인지, android:usesCleartextTraffic이 의도치 않게 열려 있지 않은지 확인한다.

iOS

• Release scheme으로 아카이브한다. 로컬 IP에 대한 ATS 예외처럼 디버그 전용으로 넣어둔 설정이 Release에 섞이지 않게 한다.
• Bitcode는 Apple이 폐기했으므로 신경 쓰지 않아도 된다.
• dSYM을 보존하고 크래시 리포팅 도구에 업로드한다.

서명과 키 관리

Android는 업로드 키와 앱 서명 키를 구분해야 한다. Play App Signing을 쓰면 구글이 앱 서명 키를 관리하고 개발자는 업로드 키만 보관한다. 키스토어와 비밀번호를 잃어버리면 같은 앱으로 업데이트하는 경로가 영구적으로 막힌다. 새 패키지명으로 다시 올리는 것 말고는 방법이 없고, 그동안 쌓은 설치 수와 리뷰는 전부 사라진다. 키스토어와 비밀번호는 비밀 관리 시스템에 백업하고 저장소에는 절대 커밋하지 않는다.

iOS는 배포 인증서와 프로비저닝 프로파일을 관리한다. fastlane match로 팀의 서명 자산을 한곳에 모아두면 만료나 재발급 때문에 릴리스가 멈추는 일을 줄일 수 있다. 인증서 만료일은 캘린더에 등록해 둔다.

두 플랫폼 모두 서명에 쓰는 비밀값은 CI 시크릿으로만 주입한다. 키스토어 비밀번호, App Store Connect API 키가 코드나 저장소에 들어가면 그 순간 전부 폐기하고 재발급해야 한다.

스토어 정책 요구사항

심사에서 가장 자주 막히는 지점들이다. 코드 문제가 아니라 신고 항목과 빌드 설정 문제라서, 출시 직전에 발견하면 일정이 통째로 밀린다.

Google Play

타깃 API 레벨. 2026년 8월 31일부터 신규 앱과 업데이트 모두 Android 16, 즉 API 36 이상을 타깃해야 제출할 수 있다. 아직 준비가 안 됐다면 2026년 11월 1일까지 연장을 신청할 수 있지만, 연장은 유예일 뿐 면제가 아니다. 구글은 "최신 메이저 릴리스로부터 1년 이내"라는 규칙을 매년 적용하므로, targetSdkVersion 상향은 연례 작업으로 잡아두는 편이 낫다.

16KB 페이지 크기. 2025년 11월 1일부터 Android 15 이상을 타깃하는 앱은 네이티브 라이브러리가 16KB 페이지 정렬을 지원해야 한다. 일회성 연장 마감도 이미 지났다. React Native 코어는 진작에 대응됐지만 문제는 서드파티다. 카메라, 결제, 영상, 암호화, AR 계열 네이티브 모듈 중 하나라도 비호환이면 업로드 자체가 막힌다. AAB를 Play Console에 올려 메모리 페이지 크기 항목을 확인하거나, 아래처럼 직접 검사한다.

readelf -h lib*.so | grep 'Page size'

값이 16384가 아니면 비호환이다. NDK 28 이상으로 재빌드된 최신 버전으로 올리고, 업데이트가 끊긴 라이브러리라면 대체재를 찾아야 한다. 이 작업은 라이브러리 메이저 업그레이드로 이어지는 경우가 많아서 출시 2주 전에 시작하면 늦다.

데이터 안전 폼. 수집하고 공유하는 데이터 유형을 정확히 신고한다. 실제 동작과 다르면 리젝은 물론 앱 정지 사유가 된다. 직접 수집하지 않더라도 광고나 분석 SDK가 수집하는 항목까지 포함해야 한다.

권한. 선언한 권한이 실제 기능과 맞는지 확인한다. 백그라운드 위치나 접근성 같은 민감 권한은 정당한 사유를 별도로 소명해야 한다.

App Store

프라이버시 매니페스트. 2024년 5월 1일부터 PrivacyInfo.xcprivacy가 필수다. 파일 타임스탬프, 디스크 여유공간, 시스템 부팅 시간, UserDefaults처럼 사유 선언이 필요한 API를 쓰면 매니페스트에 사유를 적어야 하고, 없으면 App Store Connect가 업로드 단계에서 ITMS-91061 같은 오류로 거부한다. React Native는 코어와 상당수 서드파티 SDK가 이 API를 건드리므로, 앱 매니페스트뿐 아니라 사용하는 SDK들의 매니페스트까지 갖춰져 있어야 한다.

App Tracking Transparency. IDFA 등으로 추적을 한다면 ATT 권한 요청과 사유 문구가 반드시 있어야 한다.

프라이버시 영양성분 표시. 실제 수집 항목과 일치하게 작성한다. Play의 데이터 안전 폼과 내용이 어긋나면 그것도 문제가 된다.

권한 사용 설명 문자열. NSCameraUsageDescription처럼 사용하는 모든 권한에 대한 설명이 채워져 있어야 한다. 비어 있으면 리젝된다. 라이브러리가 요구하는데 정작 앱에서는 안 쓰는 권한이 남아 있는 경우도 흔하니, 최종 빌드의 Info.plist를 직접 열어 확인한다.

시크릿과 보안

API 키와 시크릿을 JS 번들에 넣지 않는다. RN 번들은 추출하기 쉽다. react-native-config에 넣은 값도 빌드 산출물에서 꺼낼 수 있다고 전제해야 한다. 진짜 비밀은 서버에 두고 클라이언트는 토큰 교환만 담당하게 만든다.

토큰과 자격증명은 iOS Keychain, Android Keystore를 사용하는 보안 저장소에 저장한다. react-native-keychain이 대표적이다. AsyncStorage와 MMKV는 암호화되지 않은 일반 저장소이므로 민감 정보를 평문으로 두면 안 된다. MMKV를 쓴다면 암호화 옵션을 켠다.

통신은 HTTPS만 허용한다. 금융이나 의료처럼 보안 요구 수준이 높은 앱이라면 SSL 피닝을 검토한다. 루팅과 탈옥 탐지, 디버거 탐지, 난독화 강도는 앱의 위협 모델에 맞춰 결정할 문제다. 모든 앱이 여기까지 갈 필요는 없다.

성능

New Architecture와 Hermes V1이 켜져 있는지 확인한다. React Native 0.84부터 Hermes V1이 기본값이 되었고 레거시 아키텍처는 제거됐다. 최신 버전에서 새로 만든 프로젝트라면 신경 쓸 일이 없지만, 오래된 템플릿에서 마이그레이션한 프로젝트는 설정이 남아 있는 경우가 있으니 한 번 확인한다.

화면을 넘어가는 길이의 리스트는 FlashList를 쓴다. FlatList도 동작은 하지만, 항목이 많고 높이가 제각각인 리스트에서는 FlashList 쪽이 스크롤 성능 차이가 확실하다.

애니메이션은 Reanimated worklet으로 UI 스레드에서 돌린다. JS 스레드에서 프레임을 계산하면 다른 작업 하나에 애니메이션이 통째로 끊긴다.

출시 전에 프로파일링을 한 번은 한다. Hermes Sampling Profiler나 React DevTools Profiler를 쓴다. "어딘가 느리다"의 원인은 대개 특정 컴포넌트 하나의 불필요한 리렌더인데, 이건 코드를 아무리 읽어도 잘 안 보인다. 측정하면 5분이면 찾는다.

그 외에 이미지 캐싱과 리사이즈가 적절한지, 큰 이미지의 네이티브 디코딩 부담이 없는지 점검한다. 콜드 스타트 지표는 P75 화면 로드 시간처럼 기준선을 정해 측정해 둬야 다음 릴리스에서 나빠졌는지 알 수 있다. 메모리 누수는 useEffect cleanup에서 리스너, 타이머, 구독을 해제했는지 확인하는 것이 기본이다.

안정성과 모니터링

크래시 리포팅은 출시 전에 붙인다. Sentry나 Firebase Crashlytics 중 하나면 된다. 소스맵과 dSYM 업로드는 CI에 자동화한다. 이걸 안 붙이고 출시하면 사용자 크래시를 눈감고 맞이하는 셈이고, 리뷰에 "자꾸 꺼져요"만 남는다.

처리되지 않은 Promise rejection과 전역 에러를 잡아 리포팅하는 핸들러도 함께 붙인다. New Architecture에서도 처리되지 않은 JS 예외는 앱 종료로 이어질 수 있다.

에러 바운더리로 화면 단위 크래시를 격리한다. 한 화면의 렌더 오류가 앱 전체를 흰 화면으로 만들지 않게 하는 최소한의 방어선이다.

가입이나 결제 같은 핵심 퍼널에는 이벤트 로깅을 심어둔다. 출시 후 어디서 이탈하는지 보려면 데이터가 처음부터 쌓여 있어야 한다.

네트워크와 백엔드 연동

환경 분리. dev, staging, prod API 엔드포인트가 빌드 타입별로 정확히 갈리는지 확인한다. 프로덕션 빌드가 staging 서버를 바라보는 사고는 생각보다 자주 일어난다.

버전 호환성. 앱은 서버보다 오래 살아남는다. 사용자가 업데이트를 안 하면 1년 전 버전이 그대로 돌아간다. 구버전 앱이 신버전 서버와 통신해도 깨지지 않도록 후방 호환을 설계하고, 그럼에도 막아야 할 상황을 위해 강제 업데이트 게이트를 미리 넣어둔다. 이건 나중에 추가할 수 없다. 게이트가 없는 버전은 영원히 게이트가 없다.

실패 처리. 네트워크 없음, 타임아웃, 5xx 각각에 대한 화면을 정의한다. 재시도는 멱등성 키로 중복 요청을 막는다. 결제 API를 재시도하다 이중 결제가 되는 사고가 여기서 나온다.

타임존과 로케일. 서버 시간 기준으로 처리하는지, 다국어와 RTL 대응이 필요한지 점검한다.

권한과 프라이버시 UX

런타임 권한은 거부 시나리오를 반드시 처리한다. 사용자가 카메라나 위치를 거부해도 앱이 진행 가능한 대체 경로가 있어야 한다. 거부하면 아무것도 못 하고 멈추는 화면은 리젝 사유가 되기도 한다.

권한 요청은 맥락이 생긴 시점에 한다. 앱 첫 실행에 필요한 권한을 전부 몰아서 요청하면 승인율이 눈에 띄게 떨어진다.

개인정보처리방침 URL은 스토어 등록 정보와 앱 내부 양쪽에 둔다. 스토어 필수 항목이다. 계정 생성이 가능한 앱이라면 앱 안에서 계정과 데이터를 삭제할 수 있는 경로를 제공해야 한다. 양쪽 스토어 모두 정책으로 요구한다.

출시 운영

단계적 출시. 한 번에 100%로 풀지 않는다. Play와 App Store 모두 단계적 출시를 지원하니 1~10%부터 시작해 크래시율을 보면서 확대한다. 문제가 생겼을 때 영향받는 사용자 수가 달라진다.

OTA 업데이트 경로. JS 핫픽스 경로를 미리 마련해 두면 급한 버그를 스토어 심사 없이 고칠 수 있다. Microsoft App Center의 CodePush는 2025년에 서비스가 종료됐으므로, 지금은 Expo Updates나 자체 호스팅 서버, 서드파티 서비스 중에서 고르게 된다. 어느 쪽이든 네이티브 변경은 OTA로 내보낼 수 없다는 점을 팀 전체가 알고 있어야 한다. 그리고 OTA 페이로드도 스토어 정책 안에서 운영해야 한다. 앱의 핵심 목적을 바꾸는 변경은 금지다.

롤백 절차. 직전 정상 버전으로 되돌리는 방법을 문서로 남긴다. 장애 상황에서 문서 없이 기억에 의존하면 복구가 늦어진다.

베타 트랙. TestFlight나 Play의 내부·비공개 테스트 트랙을 거쳐 실사용자 손에 한 번은 쥐여보고 나간다. 내부 테스터가 못 찾는 버그를 외부 테스터가 하루 만에 찾는다.

모니터링. 출시일에는 대시보드를 띄워두고 크래시율, ANR, 핵심 퍼널을 실시간으로 본다. 롤아웃 확대 여부를 판단할 근거가 여기서 나온다.

최종 체크리스트

빌드와 검증

• R8과 minify를 켠 릴리스 빌드로 전 기능 회귀 테스트 완료
• 실기기(저사양 안드로이드 포함)에서 콜드 스타트 검증
• __DEV__ 분기, console.log, 디버그 코드 제거 확인
• 소스맵과 dSYM 생성 및 크래시 리포팅 업로드

서명

• Android 키스토어와 비밀번호 안전 백업, 저장소 미커밋
• iOS 인증서와 프로파일 유효, 만료일 등록
• 모든 서명 비밀은 CI 시크릿으로만 주입

스토어 정책

• Android 타깃 API 36 이상 (또는 연장 승인 상태)
• 모든 네이티브 .so의 16KB 페이지 크기 호환 확인
• AAB로 출시
• iOS PrivacyInfo.xcprivacy와 사용 SDK 매니페스트 구비
• 데이터 안전 폼과 프라이버시 영양성분 표시가 실제 동작과 일치
• 모든 권한 사용 설명 문자열과 정당 사유 작성
• 개인정보처리방침 URL, 해당 시 계정 삭제 경로 제공

보안

• API 키와 시크릿 번들 미포함, 토큰은 Keychain / Keystore
• HTTPS 전용, 민감 정보 평문 저장 없음

성능과 안정성

• New Architecture와 Hermes V1 활성 확인
• 출시 전 프로파일링 1회, 핵심 화면 60fps 확인
• 크래시 리포팅, 전역 에러 핸들러, 에러 바운더리 동작 확인
• 리스너, 타이머, 구독 cleanup 점검

네트워크와 운영

• prod 엔드포인트 분기 확인, 강제 업데이트 게이트 준비
• 오프라인과 실패 UX, 멱등 재시도
• 단계적 출시와 롤백 절차 문서화
• OTA 핫픽스 경로 마련, 모니터링 대시보드 준비

정리

이 체크 리스트를 한 문장으로 줄이면 이렇다. 디버그에서 되는 것과 프로덕션에서 안 터지는 것은 다른 문제다.

검증은 릴리스 빌드로, 실기기에서, 완전 종료 후 재실행으로 한다. 출시 후를 볼 눈, 즉 크래시 리포팅과 모니터링을 먼저 붙이고 나서 단계적으로 내보낸다. 서명 키 백업과 강제 업데이트 게이트처럼 나중에 추가할 수 없는 항목은 첫 출시 전에 끝내둔다.

스토어 정책의 구체적인 날짜와 타깃 버전은 매년 갱신된다. 출시 직전에 Play Console과 App Store Connect의 현행 요구사항, 그리고 React Native 릴리스 노트를 한 번 더 확인하는 습관을 들이는 게 좋다.

React Native로 앱을 만들다 보면 한 번쯤 이런 의문이 생긴다. iOS에는 UINavigationController가 있고 Android에는 Fragment와 백스택이 있는데, 왜 React Navigation은 이걸 그대로 쓰지 않고 JS에서 화면 스택을 관리할까.

화면 전환이 JS 레벨에서 일어난다는 건 단순한 구현 선택이 아니라 React Native의 구조에서 따라 나오는 결과다. 그리고 이 구조를 이해하고 있으면 "버튼을 눌렀는데 화면이 늦게 뜬다" 같은 문제를 훨씬 정확하게 진단할 수 있다.

1. 앱의 화면 구조는 곧 React 트리

React Native 앱에서 화면은 결국 컴포넌트다. HomeScreen, ProductDetailScreen 모두 다른 컴포넌트와 다를 게 없는 함수 컴포넌트이고, 이들이 모여 하나의 React 트리를 구성한다. 그 트리를 소유하고 있는 건 JS 런타임이다.

네이티브 쪽은 이 트리가 그려낸 결과를 화면에 올리는 렌더링 대상에 가깝다. RN 앱은 보통 하나의 Activity 또는 하나의 UIViewController 위에 단일 루트 뷰를 올리고, 그 안에서 모든 화면이 렌더링된다.

이 상태에서 네이티브가 화면 스택을 소유한다고 가정해 보면 문제가 분명해진다. 네이티브가 "지금은 상세 화면"이라고 알고 있고, JS도 "지금은 상세 화면"이라고 알고 있어야 한다. 두 개의 상태를 항상 동기화해야 하고, 어긋나는 순간 뒤로가기가 이상하게 동작하거나 화면이 두 번 쌓인다.

그래서 내비게이션 상태를 앱 상태의 일부로 보고 JS에 두는 쪽이 자연스럽다. 화면 전환은 결국 navigate() 호출로 상태를 바꾸고, 그 결과로 React가 리렌더링하는 흐름이다.

2. 플랫폼마다 다른 내비게이션 모델

두 번째 이유는 iOS와 Android의 내비게이션 모델이 생각보다 많이 다르다는 점이다.

Android에는 시스템 백 버튼과 태스크 백스택이 있지만 iOS에는 없다. iOS에는 화면 왼쪽 끝에서 시작하는 스와이프 백 제스처가 표준이지만 Android는 제조사와 OS 버전에 따라 동작이 다르다. 화면 전환 애니메이션의 기본값, 헤더 처리 방식, 모달의 표현도 제각각이다.

이 차이를 그대로 노출하면 개발자는 플랫폼별 분기 코드를 잔뜩 써야 한다. 내비게이션 상태를 JS가 소유하면 그 위에 공통 API를 하나 얹고, 플랫폼별 표현만 아래에서 처리할 수 있다. navigation.navigate('Detail')이라는 한 줄이 양쪽에서 동일하게 동작하는 이유다.

3. 상태로 표현되기 때문에 얻는 것들

내비게이션이 상태라는 점은 실무에서 꽤 큰 편의로 돌아온다.

로그인 여부에 따라 화면 구성을 통째로 바꾸는 경우를 보면 명확하다.

function RootNavigator() {
  const { user, isLoading } = useAuth();

  if (isLoading) return <SplashScreen />;

  return (
    <Stack.Navigator>
      {user ? (
        <>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen name="Profile" component={ProfileScreen} />
        </>
      ) : (
        <Stack.Screen name="Login" component={LoginScreen} />
      )}
    </Stack.Navigator>
  );
}

로그아웃 시 스택을 비우고 로그인 화면으로 보내는 별도의 명령형 코드가 필요 없다. user가 null이 되면 트리가 바뀌고 화면도 따라 바뀐다.

딥링크 처리도 마찬가지다. URL을 파싱해서 내비게이션 상태 객체를 만들면 되고, 앱을 종료했다 다시 켰을 때 화면 위치를 복원하는 것도 상태를 직렬화했다 복원하는 문제로 환원된다.

4. react-native-screens가 네이티브로 옮긴 것

여기서 흔한 오해가 하나 있다. native-stack을 쓰면 화면 전환이 네이티브에서 일어나니까 JS와 무관하다는 오해다.

react-native-screens가 하는 일은 내비게이션 상태를 네이티브로 옮기는 게 아니라, 화면을 담는 컨테이너를 네이티브 컴포넌트로 바꾸는 것이다. iOS에서는 UINavigationController, Android에서는 Fragment 기반 컨테이너를 실제로 사용한다.

덕분에 전환 애니메이션과 스와이프 백 제스처가 네이티브 구현을 그대로 따르고, 화면에 보이지 않는 스크린은 네이티브 뷰 계층에서 분리되어 메모리와 렌더링 비용을 줄인다. 하지만 "다음에 어떤 화면을 쌓을지" 결정하는 주체는 여전히 JS다.

방향도 양쪽으로 흐른다. 사용자가 스와이프 백 제스처를 하면 네이티브가 그 제스처를 처리해 애니메이션을 그리면서, 동시에 그 사실을 JS로 전달해 내비게이션 상태를 갱신한다. 그래서 JS 스레드가 완전히 멈추면 화면 전환도 결국 멈춘다.

참고로 react-native-navigation처럼 각 화면을 네이티브 뷰 컨트롤러로 등록하고 네이티브가 스택을 소유하는 방식의 라이브러리도 있다. 전환 품질은 좋지만 화면마다 별도의 React 루트가 생기면서 상태 공유가 까다로워지고 네이티브 설정이 늘어난다. 생태계가 JS 소유 방식으로 수렴한 데는 이런 트레이드오프가 있었다.

5. New Architecture에서의 차이

New Architecture로 넘어와도 내비게이션 상태가 JS에 있다는 사실은 변하지 않는다. React 트리는 여전히 JS에 있고, Fabric은 그 결과를 C++ 섀도우 트리로 만들어 네이티브에 커밋한다.

달라진 부분은 커밋 경로다. 브릿지를 통한 비동기 직렬화 대신 JSI 기반으로 동작하면서 레이아웃 정보 접근과 커밋 순서가 훨씬 예측 가능해졌다. 예전 아키텍처에서 native-stack이 헤더나 화면 크기 계산에서 간헐적으로 어긋나던 문제들이 상당 부분 정리된 배경이다.

React 18의 동시성 기능을 쓸 수 있게 된 점도 실무에서는 의미가 있다. 무거운 화면의 첫 렌더를 startTransition으로 감싸 우선순위를 낮추는 식의 대응이 가능해졌다.

6. 전환이 느리게 느껴질 때

이 구조를 알고 나면 "화면 전환이 버벅인다"는 증상을 두 가지로 나눠 볼 수 있다.

애니메이션 자체가 끊기는 경우는 native-stack을 쓰고 있다면 잘 발생하지 않는다. 전환 애니메이션은 네이티브에서 그려지기 때문이다. 만약 JS 기반 stack을 쓰고 있다면 native-stack으로 바꾸는 것만으로 개선되는 경우가 많다.

애니메이션은 부드러운데 새 화면이 빈 상태로 나타났다 뒤늦게 채워지는 경우가 훨씬 흔하다. 이건 애니메이션 문제가 아니라 새 화면의 첫 렌더가 JS에서 일어나기 때문이다. 화면 컴포넌트가 무겁거나, 마운트 직후 큰 데이터를 동기적으로 가공하거나, 그 시점에 다른 작업이 JS 스레드를 점유하고 있으면 그대로 지연으로 이어진다.

이 경우 데이터를 미리 당겨오는 게 효과적이다.

const queryClient = useQueryClient();

const openDetail = (id: string) => {
  queryClient.prefetchQuery({
    queryKey: ['product', id],
    queryFn: () => fetchProduct(id),
  });

  navigation.navigate('ProductDetail', { id });
};

리스트 아이템을 누르는 시점, 또는 화면에 보이는 시점에 미리 요청을 보내두면 상세 화면이 마운트될 때 캐시에서 바로 읽는다.

화면 컴포넌트 자체가 무거운 경우라면 첫 렌더에서 그려야 할 것을 줄이는 쪽이 우선이다. 상단 영역만 먼저 그리고 아래쪽 무거운 섹션은 이후에 붙이는 식으로 나누는 편이 낫다.

뒤로 간 화면이 계속 리렌더링되는 문제도 짚어둘 만하다. 화면이 스택에 남아 있으면 React 트리에서 언마운트되지 않기 때문에, 전역 상태가 바뀔 때마다 보이지도 않는 화면들이 함께 리렌더링될 수 있다. 최근 버전의 react-native-screens는 화면이 포커스를 잃으면 렌더링을 동결하는 동작이 기본으로 적용되어 있고, 화면 단위로 freezeOnBlur 옵션을 조정할 수 있다.

정리

React Native에서 화면 전환이 JS 레벨에서 일어나는 이유는 앱의 화면 구조 자체가 React 트리이고, 그 트리를 소유한 쪽이 JS이기 때문이다. 내비게이션 상태까지 네이티브에서 별도로 관리하면 JS와 네이티브의 상태를 동기화해야 한다. 이렇게 관리해야 할 상태가 늘어나면 구조가 복잡해지고, 단순히 네이티브에서 상태를 관리하는 것보다 얻는 이점이 크지 않을 수 있다.

native-stack과 react-native-screens는 이 구조를 바꾸는 게 아니라, 화면을 담는 컨테이너와 전환 애니메이션을 네이티브로 내려 사용자가 체감하는 품질을 끌어올린다. 상태는 JS, 표현은 네이티브라는 역할 분담이다.

그래서 전환이 느리다고 느껴질 때 봐야 할 곳은 애니메이션이 아니라 새 화면의 첫 렌더 비용인 경우가 대부분이다. 데이터를 미리 가져오고, 첫 렌더에서 그리는 양을 줄이고, 보이지 않는 화면이 불필요하게 일하지 않게 하는 것이 실질적인 개선으로 이어진다.

Android에서 상세 화면 상단의 헤더(뒤로가기 · 공유 등 액션 버튼이 있는 바)에서 공유하기를 누르면 OS 기본 공유 시트(시스템 바텀시트)가 올라온다. 그 시트를 닫는 순간, 헤더가 한 번 아래로 내려갔다가 다시 제자리로 튀어 올라오는 스프링 같은 진동(덜컹거림)이 발생했다.

여기서 두 가지를 구분해야 한다.

• 불가피한 기본 동작(baseline): Android는 공유 시트가 올라올 때 상단 status bar가 잠깐 사라진다. 그러면 화면 상단 여백이 줄면서 콘텐츠 전체가 살짝 위로 붙었다가, 시트가 닫히면 status bar가 돌아오며 원위치로 내려온다. 이건 다른 상용 앱들에서도 동일하게 나타나는 OS 레벨 현상이라 없앨 수 없다.
• 우리 앱에만 있던 추가 버그: baseline은 "위로 올라갔다 → 내려옴" 한 방향 움직임이다. 그런데 우리 헤더 UI는 그 위에 반대 방향으로 한 번 더(아래로 내려갔다 → 위로) 오버슈트하며 진동했다. 이 추가 진동이 제거 대상이었다.

iOS에서는 이 현상이 없었다. Android 전용 문제다.

2. 배경 지식

헤더의 세로 위치는 무엇이 결정하나

이 헤더는 화면 최상단에 position: absolute, top: 0으로 고정되는 오버레이다. 스크롤 위에 떠 있으면서 위로 밀리지 않는다. 그래서 헤더 안 콘텐츠(버튼 줄)의 세로 위치는 사실상 위쪽 안전영역 패딩(top inset) 하나로만 결정된다.

<View position='absolute' top={0} paddingTop={safePaddingTop}>
  {/* 뒤로가기 / 공유 등 액션 버튼 줄 */}
</View>

이 safePaddingTop은 status bar 높이만큼 버튼들을 아래로 밀어내, 버튼이 status bar에 가려지지 않게 하는 값이다.

safePaddingTop은 "라이브" 값이었다

safePaddingTop은 안전영역 inset을 읽는 훅에서 나온다.

function useSafePaddingTop(): number {
  const { top } = useSafeAreaInsets();
  return top;
}

핵심은 useSafeAreaInsets()가 라이브 React 상태라는 점이다. 시스템이 전달하는 inset 값이 바뀌면 이 훅을 쓰는 컴포넌트가 리렌더되고, paddingTop이 새 값으로 다시 적용되어 헤더가 즉시 재배치된다.

3. 원인 분석

1) 헤더 안의 Reanimated는 범인이 아니다

처음엔 헤더 내부의 Reanimated 애니메이션을 의심했다. 하지만 헤더가 쓰는 애니메이션 값은 불투명도(opacity)와 아이콘 크기(scale)만 구동한다. 스크롤에 따라 배경/타이틀을 페이드인하고 아이콘을 살짝 키우는 용도다. 세로 위치(translateY)를 움직이는 애니메이션은 하나도 없다.

따라서 "헤더가 아래로 내려갔다 올라오는" 세로 진동은 헤더의 애니메이션 코드에서 나올 수 없다. Reanimated는 이 증상에 대해선 무죄였다.

2) 진짜 원인 — 라이브 inset에 묶인 위치

헤더의 세로 위치를 움직일 수 있는 유일한 변수는 paddingTop = safePaddingTop이고, 이 값은 라이브 inset이다. 즉 inset 값이 흔들리면 헤더도 그대로 흔들린다.

남은 질문은 하나다. "왜 공유 시트를 닫을 때 inset 값이 한 방향이 아니라 위아래로 진동(오버슈트)하는가?"

3) Android 공유 시트는 별도의 시스템 윈도우다

iOS의 공유 시트(UIActivityViewController)는 같은 앱 윈도우 안에 뜨는 모달이다. 그래서 안전영역 inset이 바뀌지 않는다. → iOS에선 헤더가 흔들릴 이유가 없다.

반면 Android의 공유 시트는 Intent.createChooser로 뜨는 별도의 시스템 윈도우다. 이 윈도우가 떴다가 닫히는 과정에서 우리 앱 윈도우는 포커스를 잃었다가 되찾고, 그때 시스템이 WindowInsets(status bar 등 여백 정보)를 다시 내려보낸다(re-dispatch). 이 재전달 과정에서 top inset 값이 출렁인다.

4) KeyboardProvider가 inset 변화를 스프링으로 보간한다

앱 루트에는 react-native-keyboard-controller의 KeyboardProvider가 감싸여 있다. 이 라이브러리는 Android에서 시스템 윈도우 inset 전환을 부드럽게 처리하려고 inset 변화를 스프링(spring) 보간 프레임으로 흘려보낸다.

스프링 보간은 본질적으로 목표값을 향해 가면서 오버슈트(목표를 살짝 지나쳤다가 되돌아오는)가 생긴다. 그래서 공유 시트가 닫힐 때 top inset이 "원래값 → 살짝 초과 → 되돌아옴" 식으로 위아래로 여러 프레임에 걸쳐 진동하며 도착한다.

결과적으로:

공유 시트 닫힘
  → 시스템이 WindowInsets 재전달
  → KeyboardProvider가 inset 변화를 spring으로 보간 (오버슈트 진동)
  → useSafeAreaInsets().top 값이 위아래로 진동
  → 라이브 inset에 묶인 헤더 paddingTop이 진동
  → 헤더가 덜컹거림 (baseline 위에 얹힌 추가 진동)

이것이 "내려갔다 다시 올라오는" 추가 진동의 정체다. baseline(status bar가 사라졌다 돌아오는 한 방향 움직임)은 어쩔 수 없지만, 그 위에 얹힌 스프링 오버슈트 진동은 우리가 라이브 inset을 그대로 따라가도록 둔 탓이었다.

4. 해결 과정

해결의 방향은 명확했다. 헤더의 위치를 "진동하는 라이브 inset"에서 떼어내, 안정된 값 하나에 고정하는 것.

1) 1차 시도 — 앱 시작 시점의 고정 inset 사용 (부작용 발생)

처음엔 안전영역 라이브러리가 제공하는 "앱 시작 시점에 측정된 고정 inset"을 쓰려고 했다.

// 1차 시도: 앱 시작값으로 고정
const initialTop = initialWindowMetrics?.insets.top;
const baseTop = stable && initialTop != null ? initialTop : liveTop;

이 값은 앱 부팅 때 한 번 측정되고 이후 변하지 않으므로, 공유 시트로 인한 진동에 영향을 받지 않는다. 진동(덜컹거림)은 사라졌다.

그러나 새로운 부작용이 생겼다. 헤더의 초기 위치가 평소보다 한 칸 정도 아래로 내려간 것이다.

원인은 이렇다. "앱 시작 시점 측정값(initialWindowMetrics)"과 "화면에 안정적으로 자리잡은 라이브값(useSafeAreaInsets)"은 항상 같지 않다. 이 기기/edge-to-edge 설정 조합에서는 시작 시점 측정값이 settled 라이브값보다 더 컸다. 그래서 그 값으로 고정하니 패딩이 커져 헤더가 아래로 밀린 것이다.

즉, 진동은 잡았지만 기준점이 어긋났다.

2) 최종 해결 — 마운트 시점의 settled 라이브값을 1회 래치

올바른 기준값은 "앱 시작 순간의 값"이 아니라 "이 헤더가 화면에 떴을 때 이미 안정적으로 자리잡은 라이브 inset"이다. 그래서 시작 시점 메트릭을 버리고, 헤더가 마운트될 때 라이브값을 딱 한 번 캡처(래치)해서 고정하는 방식으로 바꿨다.

function useStableSafePaddingTop(): number {
  const liveTop = useSafePaddingTop();

  // 첫 유효(>0) 값을 한 번만 래치한 뒤 그 값을 계속 반환
  const stableRef = useRef<number | null>(null);
  if (stableRef.current === null && liveTop > 0) {
    stableRef.current = liveTop;
  }

  return stableRef.current ?? liveTop;
}

동작 원리:

• 초기 위치 마운트 때의 라이브값을 그대로 캡처하므로, 기존(원래) 위치와 동일하다. 1차 시도의 "한 칸 내려감" 부작용이 사라졌다.

• 진동 제거 한 번 래치한 뒤로는 라이브 inset이 어떻게 진동하든 무시하고 고정값만 반환한다. 공유 시트 오버슈트가 헤더에 전달되지 않는다.

• 오염 걱정 없음 이 헤더는 앱이 부팅된 뒤 사용자가 상세 화면으로 진입할 때 마운트된다. 그 시점엔 안전영역 inset이 이미 안정적으로 자리잡은 상태라, 첫 캡처값이 곧 정상값이다. 공유 시트는 마운트보다 한참 뒤에 열리므로 캡처 순간엔 진동이 존재하지 않는다.

• 폴백 혹시 첫 값이 아직 유효하지 않으면(0) 래치하지 않고 라이브값을 그대로 흘려보내, inset이 해결되는 리렌더에서 자연스럽게 보정된다.

3) 전용 훅으로 분리

useSafePaddingTop은 앱 전반의 여러 헤더에서 쓰는 공용 훅이다. 이 안정화 동작이 필요한 곳은 현재 이 상세 화면 헤더 하나뿐이라, 공용 훅에 옵션을 끼워 넣어 모두에게 영향을 주기보다 별도 훅으로 분리하는 편이 깔끔했다.

그래서 안정화 로직은 useStableSafePaddingTop이라는 전용 훅에 담고, useSafePaddingTop은 원래 형태 그대로 두었다.

// 헤더에서의 사용 — 일반 useSafePaddingTop 대신 안정화 버전을 호출
const safePaddingTop = useStableSafePaddingTop();

5. 적용 범위와 트레이드오프

• 적용 대상 화면 상단에 absolute로 고정되며, 앱 부팅 이후 진입하는 화면의 헤더이다. 일반 flow 컴포넌트는 보통 루트 SafeAreaView 한 곳에서 top inset을 1회 먹는다. absolute 오버레이는 그 흐름 밖이라 자동으로 안 밀린다 → 컴포넌트가 직접 paddingTop = inset 손배선. 그래서 inset 진동을 직격으로 맞는다.

• 일반 화면 안정화가 필요 없다. 기존 useSafePaddingTop을 그대로 쓴다.

• 트레이드오프 한 번 래치한 뒤로는 inset 변화를 따라가지 않으므로, 화면 회전이나 status bar 높이의 실제 변경에는 반응하지 않는다. 이 상세 화면은 세로 고정이라 실질적 영향이 없지만, 회전을 지원하는 화면에서 이 훅을 재사용한다면 이 한계를 고려해야 한다.

• 확장 다른 absolute 헤더(예: 다른 탭·화면들의 헤더)에서도 같은 덜컹거림이 보인다면, 그 헤더의 useSafePaddingTop 호출을 useStableSafePaddingTop으로 바꾸면 동일하게 해결된다.

6. 핵심 교훈

• 증상이 보이는 곳과 원인이 있는 곳은 다를 수 있다. 헤더가 흔들렸지만 헤더의 애니메이션 코드엔 위치 애니메이션이 없었다. 진짜 원인은 "헤더가 라이브 inset에 묶여 있다"는 데이터 바인딩 쪽이었다.
• "진동하는 신호를 매번 구독"하는 대신 "안정된 값을 한 번 캡처해서 붙박이로" — 외부에서 출렁이는 값에 UI를 직접 묶지 말고, 의미 있는 한 시점의 값을 고정하는 패턴이 떨림을 없앤다.
• 플랫폼 차이를 활용해 원인을 좁혀라. iOS는 멀쩡하고 Android만 깨졌다는 사실이, "같은 윈도우 내 모달 vs 별도 시스템 윈도우 + inset 재전달"이라는 핵심 차이로 곧장 안내했다.
• 고정값의 출처를 정확히 골라라. "앱 시작 시점값"과 "마운트 시점 settled값"은 다르다. 진동을 잡겠다고 아무 고정값이나 쓰면 기준점이 어긋난다.

운영체제는 메모리(RAM)를 한 바이트씩 다루지 않는다. 너무 비효율적이기 때문이다. 대신 메모리를 일정한 크기의 고정된 덩어리로 잘라서 관리하는데, 이 덩어리 하나를 페이지(page)라고 부른다. 그리고 그 덩어리의 크기가 페이지 크기(page size)다.

비유하자면 메모리는 한 권의 책이고, OS는 책을 한 글자씩 읽는 게 아니라 페이지 단위로 넘기며 읽는다. OS 입장에서 메모리 관리의 최소 단위가 곧 페이지인 셈이다.

페이지라는 단위가 존재하는 이유는 크게 두 가지다.

• 가상 메모리(Virtual Memory) 관리: OS는 앱마다 "가상 주소"를 주고, 이걸 실제 물리 메모리 주소로 매핑한다. 이 매핑을 페이지 단위로 관리한다.
• 바이트 단위로 일일이 추적하면 관리 비용이 폭발한다. 페이지라는 큰 단위로 묶으면 추적해야 할 항목 수가 크게 줄어든다.

2. android 의 페이지 정책 변화

지금까지 대부분의 안드로이드(ARM64) 기기는 페이지 크기를 4KB로 써왔다. 오랫동안 이게 표준이었다.

그런데 기기에 탑재되는 RAM이 점점 커지면서, 더 큰 페이지 크기인 16KB를 쓰는 방향으로 바뀌고 있다. Android 15(API 35)부터 AOSP가 16KB 페이지를 정식 지원한다.

페이지 크기를 키우면 얻는 이점은 이렇다.

• 앱 실행 속도 향상 : 메모리 압박 상황에서 평균 약 3%, 일부 앱은 최대 30%까지 빨라진다.
• 전력 소모 감소 : 앱 실행 시 평균 약 4.5% 절감된다.
• 시스템 부팅 시간 단축 : 평균 약 8%(약 950ms) 빨라진다.

원리는 단순하다. 페이지가 커지면 CPU가 자잘한 메모리 조각을 일일이 관리하는 데 드는 오버헤드가 줄고, 그만큼 실제 작업에 자원을 더 쓸 수 있다.

단점도 있다. 페이지가 커지면 작은 메모리를 요청해도 최소 16KB 페이지 하나를 통째로 차지하므로, 평균적으로 메모리를 약간 더 쓴다.

3. RN 앱에서 왜 이게 문제가 되는가

여기가 핵심이다. 순수 JavaScript만으로 이루어진 앱은 페이지 크기와 무관하다. 페이지 정렬은 어디까지나 네이티브 바이너리(.so 파일) 수준의 이야기이기 때문이다.

문제는 React Native 앱이 결코 순수 JS가 아니라는 점이다. RN 앱은 다음과 같은 네이티브 라이브러리(.so)를 잔뜩 포함한다.

• Hermes 엔진 (libhermes.so)
• JSI / New Architecture 관련 네이티브 코드 (libreactnative.so 등)
• 서드파티 네이티브 모듈: Reanimated, react-native-svg, gesture-handler, MMKV, 카메라, 지도, 결제 SDK 등 상당수가 C/C++ 네이티브 코드를 포함한다.

이 .so 파일들이 4KB 페이지를 가정하고 정렬(alignment)된 채로 빌드되어 있으면, 16KB 페이지를 쓰는 기기에서 제대로 로드되지 못하거나 크래시(segmentation fault)가 날 수 있다.

즉, RN 앱의 16KB 대응이란 결국 "앱 안에 들어있는 모든 .so 파일이 16KB 정렬로 빌드되어 있는가" 의 문제다.

4. '정렬(Alignment)'이라는 개념

.so 파일을 메모리에 올릴 때, OS는 파일의 각 세그먼트(LOAD section)를 페이지 경계에 맞춰 배치한다. 이때 세그먼트의 시작 주소가 페이지 크기의 배수여야 깔끔하게 들어맞는다. 이것을 "정렬되어 있다"고 표현한다.

• 4KB 정렬 : 세그먼트가 4KB(0x1000)의 배수 주소에서 시작
• 16KB 정렬 : 세그먼트가 16KB(0x4000)의 배수 주소에서 시작

4KB의 배수가 항상 16KB의 배수인 것은 아니다. 그래서 4KB로 정렬된 .so는 16KB 기기에서 경계가 어긋난다. APK Analyzer나 빌드 도구에서 다음과 같은 경고가 뜨는 이유가 바로 이것이다.

4 KB LOAD section alignment, but 16 KB is required

이 경고는 앱 다운로드 용량과는 전혀 무관하다. 오로지 네이티브 라이브러리의 메모리 정렬에 관한 이야기다.

5. Google Play의 요구사항

구글은 이 변화에 맞춰 정책을 도입했다.

• 2025년 11월 1일: Android 15(API 35) 이상을 타겟팅하는 신규 앱 및 업데이트 제출 시 16KB 페이지 지원 필수
• 연장 기한: Play Console을 통해 신청 시 2026년 5월 31일까지 연장 가능

대응하지 않으면 해당 마감 이후 앱 업데이트를 게시할 수 없게 된다. 버그 수정도, 신규 기능도, 보안 패치도 올릴 수 없다는 뜻이다.

6. React Native에서의 대응

다행히 RN은 16KB 페이지를 이미 공식 지원한다. 대응의 본질은 결국 버전 업그레이드와 재빌드다.

핵심 조치

1. React Native 버전 업그레이드 RN은 0.75.3부터 16KB를 지원하기 시작했으며, 0.76 이상(New Architecture 기본)으로 올리는 것이 가장 안전하다.

2. 빌드 툴체인 업데이트

   • NDK r28 이상
   • Android Gradle Plugin(AGP) 8.5.1 이상

   이 버전들은 빌드 시 16KB 정렬을 자동으로 처리해준다.

3. 서드파티 네이티브 모듈 최신화 네이티브 코드를 포함한 라이브러리(Reanimated, MMKV 등)를 16KB 호환 버전으로 올린다. 보통 라이브러리 메이저/마이너 버전 업으로 해결된다.

테스트 방법

실제 16KB 환경에서 동작을 검증하는 것이 가장 확실하다.

• 에뮬레이터: Android Studio SDK Manager에서 "16 KB Page Size" 시스템 이미지를 받아 AVD를 생성한다.
• 실기기: Pixel(Android 15 QPR1 이상)의 개발자 옵션에서 16KB 페이지를 직접 켤 수 있다.
• 기기에서 실제 페이지 크기는 다음 명령으로 확인한다.

adb shell getconf PAGE_SIZE
# 4096 또는 16384 출력

@gorhom/bottom-sheet로 바텀시트를 구현하다 보면, 동일한 UI/UX 요구사항임에도 BottomSheetModal과 BottomSheet 사이에 드래그 응답성 차이가 발생하는 경우가 있다. 두 컴포넌트는 내부적으로 동일한 코어를 공유하지만, 마운트 위치가 달라지면서 React 렌더링 파이프라인과 UI 스레드 자원 점유 양상이 달라진다. 이 글에서는 그 기술적 원인을 라이브러리 내부 구조 관점에서 분석하고, 실무에서 적용 가능한 최적화 방안을 정리한다.

본 글은 @gorhom/bottom-sheet v5(Reanimated v3 + Gesture Handler v2) 기준으로 작성되었다.

문제 현상

• BottomSheetModal 사용 시: 드래그(상하 제스처) 중 프레임 드롭과 응답 지연이 관측된다. 특히 하위 화면이 지도, 비디오, 캔버스 등 네이티브 GPU 자원을 점유하는 뷰일 때 두드러진다.
• BottomSheet 사용 시: 동일한 시각 구조에서도 60fps에 가까운 부드러운 드래그가 유지된다.

체감상으로는 "모달 쪽이 더 무겁다"는 인상이지만, 실제로 두 컴포넌트의 코어 로직은 동일하다. 차이는 거의 전적으로 마운트 위치에서 비롯된다.

원인 분석

문제의 본질은 컴포넌트 단일의 연산 속도가 아니라, React 트리에서의 마운트 위치 차이와 그로부터 파생되는 reconciliation 범위, 제스처/애니메이션 worklet의 컨텍스트 부담, 네이티브 뷰 레이아웃 비용의 차이에 있다.

1) 마운트 위치의 차이 : Portal Host

BottomSheet는 자신을 사용하는 컴포넌트의 자식으로 그 자리에 마운트된다. 반면 BottomSheetModal은 내부적으로 @gorhom/portal을 사용해 BottomSheetModalProvider가 제공하는 Portal Host로 children을 옮겨 마운트한다. BottomSheetModal은 사실상 Portal로 감싸진 BottomSheet이다.

실제로 체감 성능 차이를 만드는 지점은 다음 세 가지다.

2) React 트리 구조와 Context 의존성

BottomSheetModalProvider는 보통 앱 루트(App.tsx) 근처에 위치한다 즉, BottomSheetModal의 children은 화면 컴포넌트가 아닌 앱 루트 근처의 Context 영향권에 마운트된다. 이로 인해 다음과 같은 부수 효과가 발생할 수 있다.

• 상위 Provider(예: NavigationContainer, 테마, 인증, i18n)의 값이 변경되면 Portal 내부 children까지 리렌더링 대상에 포함된다.
• 화면 단위에서만 의미 있는 Context를 모달 내부에서 참조하면, 해당 Context를 위로 끌어올리거나 별도 동기화 로직이 필요해진다. 이 과정에서 불필요한 리렌더가 누적될 수 있다.

이는 GPU의 합성 비용이 아니라 JS 스레드의 reconciliation 비용으로 누적되며, 드래그처럼 매 프레임 worklet과 JS 간 통신이 빈번한 상황에서 체감 성능에 영향을 준다. 때문에 해당 BottomSheetModal의 바로 상위부모에 위치하도록 바텀시트모달Provider를 구현하면 좋다.

3) Reanimated worklet과 Gesture Handler의 컨텍스트

@gorhom/bottom-sheet의 드래그 동작은 react-native-gesture-handler와 react-native-reanimated의 worklet 위에서 실행된다. 라이브러리는 BottomSheetInternalContext를 통해 animatedPosition 등의 SharedValue를 공유하며, 이 값들은 UI 스레드에 상주하므로 이상적인 환경에서는 JS 스레드의 부하와 무관하게 60/120fps를 유지할 수 있다.

문제는 다음과 같은 상황에서 발생한다.

• 모달 내부에서 JS 스레드에 의존하는 값(예: 외부 상태, Context, 네트워크 결과)을 useAnimatedStyle이나 useDerivedValue에서 참조하면, worklet 실행마다 JSI 호출이 끼어들어 프레임 일관성이 깨진다.
• Portal 구조상 모달이 앱 루트에 가깝게 마운트되므로, 화면 단위 상태를 worklet에서 참조하려면 shared value로 끌어올리는 별도 설계가 필요하다. 이를 누락하면 JS 의존성이 늘어나 worklet의 이점이 약화된다.

즉, 핵심은 "GPU 합성 비용 증가"보다는 UI 스레드 자원 경합과 네이티브 뷰의 자체 갱신 부담이다.

2.5 컴포넌트 생명주기와 상시 마운트

BottomSheetModal을 화면 진입과 동시에 트리에 두면, 닫혀 있어도 다음과 같은 비용이 유지된다.

• children의 초기 마운트 비용이 화면 진입 시점에 발생한다.
• Provider 하위에 상주하므로 부모 리렌더의 영향권에 계속 포함된다.
• 내부 SharedValue와 worklet 핸들러가 메모리에 유지된다.

이는 단일 화면에서는 미미해 보일 수 있으나, 화면 스택이 깊어지면 누적 부담이 된다.

3. 측정과 가설 검증

최적화에 앞서, 체감으로만 판단하지 말고 다음 도구로 병목 위치를 좁혀야 한다.

• Perf Monitor (DevSettings): JS FPS와 UI FPS를 분리해서 확인한다. UI FPS는 멀쩡한데 JS FPS만 떨어진다면 reconciliation/JS 의존성 문제이고, UI FPS가 같이 떨어진다면 네이티브 뷰 갱신이나 worklet 자체 비용 문제다.
• Reanimated useAnimatedReaction 로깅: worklet 내부에서 SharedValue 변화 빈도를 확인한다. JS bridge로 새는 호출이 없는지 점검할 수 있다.
• Flipper / Hermes Profiler: 드래그 중 어떤 컴포넌트가 리렌더되는지 추적한다. React DevTools의 "Highlight updates"도 동일한 목적에 유효하다.
• Systrace / Android Studio Profiler: 네이티브 뷰의 draw 비용이 의심될 때 사용한다.

원인을 분리해두면, 아래 최적화 중 어떤 것이 실제로 효과가 있을지 빠르게 판단할 수 있다.

4. 최적화 전략

1) 렌더링 위치 선택 : 모달이 꼭 필요한가?

전역 어디서든 띄울 필요가 없고, 특정 화면 내에서만 동작하는 바텀시트라면 BottomSheetModal 대신 BottomSheet를 사용한다. Portal Host를 거치지 않으므로 화면 Context를 그대로 사용할 수 있고, reconciliation 범위가 좁아진다.

BottomSheetModal이 적합한 경우는 다음과 같다.

• 여러 화면에서 동일한 모달을 띄워야 하는 경우
• 네비게이션 헤더/탭바 위에 시각적으로 겹쳐야 하는 경우
• 모달을 제어하는 주체와 표시되는 위치가 서로 다른 컴포넌트인 경우(예: 전역 액션 시트)

2) Snap Point 단순화

snapPoints={['25%', '50%', '90%']}처럼 다단계 스냅을 두면 드래그 범위와 worklet 계산 빈도가 늘어난다. 다음을 검토한다.

• 사용자가 실제로 사용하는 스냅이 1~2개라면 단일 스냅으로 줄이고 enablePanDownToClose로 닫기만 허용한다.
• 동적 콘텐츠 높이가 필요하면 enableDynamicSizing(v5에서 기본값 true)을 활용해 불필요한 좌표 추적을 줄인다. 단, 콘텐츠 크기 변화가 잦은 경우 오히려 layout 비용이 증가할 수 있으므로 측정 후 결정한다.

3) 지연 마운트 패턴

const [visible, setVisible] = useState(false);
const bottomSheetRef = useRef<BottomSheetModal>(null);

return (
  <>
    <Button onPress={() => setVisible(true)} title="Open" />
    {visible && (
      <MySheet
        ref={bottomSheetRef}
        onDismiss={() => setVisible(false)}
      />
    )}
  </>
);

BottomSheetModal을 쓰더라도 children 자체를 조건부로 마운트하면, 닫혀 있는 동안의 reconciliation 부담을 제거할 수 있다. dismiss()만으로는 children 트리가 유지되는 경우가 있어, 무거운 children일수록 조건부 마운트가 유효하다.

4) worklet 친화적 설계

드래그 중 변하는 값은 SharedValue로 관리하고, JS 상태는 scheduleOnRN로 필요한 시점에만 동기화한다.

// ❌ worklet 안에서 JS Context를 직접 참조 — 매 프레임 JSI 호출
const animatedStyle = useAnimatedStyle(() => {
  return { opacity: theme.isDark ? 0.8 : 1 }; // theme은 JS 객체
});

// ✅ 필요한 값만 SharedValue로 끌어올리고 worklet에서는 그것만 참조
const opacity = useSharedValue(theme.isDark ? 0.8 : 1);
useEffect(() => {
  opacity.value = theme.isDark ? 0.8 : 1;
}, [theme.isDark]);

const animatedStyle = useAnimatedStyle(() => {
  return { opacity: opacity.value };
});

추가로:

• 모달 내부에서 외부 Context를 worklet에서 직접 참조하지 않는다. 필요한 값만 SharedValue로 끌어올린다.
• BottomSheetScrollView / BottomSheetFlatList 등 라이브러리가 제공하는 통합 스크롤 컴포넌트를 사용한다. 일반 ScrollView를 쓰면 제스처 충돌과 추가 JS 핸들링이 발생한다.
• onChange 같은 콜백 안에서 무거운 setState를 호출하지 않는다. 필요하면 useDerivedValue로 UI 스레드에서 처리하고, JS 동기화는 최소 빈도로 한다.

5) 하위 네이티브 뷰 부담 줄이기

지도/비디오/캔버스 위에 모달이 떠야 한다면 다음을 고려한다.

• 모달이 열려 있는 동안 하위 뷰의 갱신 빈도를 낮춘다. 지도 카메라 애니메이션 일시 중지, 비디오 일시정지, Skia 렌더 루프 중단(useFrameCallback의 setActive(false)) 등.
• 모달이 충분히 큰 영역을 가린다면 pointerEvents="none"만으로는 부족하므로, 상태 기반으로 하위 뷰의 활성화 여부를 분기한다.
• 가능하면 react-native-maps의 liteMode(Android) 등 경량 모드를 검토한다. iOS에는 직접적인 대응이 없으므로, 카메라 이동/마커 갱신을 멈추는 방식으로 우회한다.

5. 의사결정 체크리스트

실무에서 빠르게 판단하기 위한 요약이다.

1. 이 바텀시트, 정말 모달이어야 하는가?
   • 상시 열려 있고 닫을 수 없는 시트 → BottomSheet
   • 열고 닫는 동작이 있는 시트 → BottomSheetModal
2. 닫혀 있을 때도 마운트되어 있는가?
   • 그렇다 → {visible && <Sheet />} 패턴으로 지연 마운트
3. 스냅 포인트가 3개 이상인가?
   • 사용자가 실제로 다 쓰는지 확인 → 1~2개로 축소
4. worklet에서 JS 객체나 Context를 직접 참조하는가?
   • 그렇다 → SharedValue로 끌어올림
5. 하위에 지도/비디오/WebView/Skia가 있는가?
   • 그렇다 → 모달 오픈 동안 갱신 빈도 낮춤
6. Fabric을 켰는가?
   • 안 켰다면, 신규 프로젝트는 켜고 재측정

6. 요약

• BottomSheetModal의 성능 저하는 GPU 합성 자체의 문제가 아니라, Portal로 인한 마운트 위치 변화, reconciliation 범위 확대, worklet의 JS 의존성, 하위 네이티브 뷰와의 UI 스레드 자원 경합이 결합된 결과이다.
• 최적화 전에 Perf Monitor와 프로파일러로 병목이 JS 스레드인지 UI 스레드인지부터 분리해야 한다.
• 모달이 반드시 필요하지 않다면 BottomSheet로 통합한다.
• 스냅 포인트를 단순화하고, children을 조건부로 마운트하며, worklet에서 JS 의존성을 최소화한다.
• 하위에 무거운 네이티브 뷰가 있다면, 모달이 열린 동안 그 뷰의 갱신 비용을 능동적으로 낮춘다.

프리로드하는 URL은 컴포넌트가 실제로 렌더링할 URL과 글자 단위까지 동일해야 한다. FastImage는 URL(+헤더)를 캐시 키로 쓰기 때문에, URL이 조금이라도 다르면 다른 캐시로 취급되어 프리로드가 무효가 된다.

// 컴포넌트가 이걸 렌더링한다면
<FastImage source={{ uri: 'https://cdn.example.com/img.jpg?w=300' }} />

// 프리로드도 정확히 같은 URL로 해야 한다
FastImage.preload([{ uri: 'https://cdn.example.com/img.jpg?w=300' }]);

2. 리사이징된 이미지는 리사이징된 URL로 프리로드한다

서버/CDN에서 리사이징한 이미지를 표시한다면, 리사이징된 URL로 프리로드해야 한다.

// ❌ 잘못된 예 — 원본을 프리로드, 화면엔 리사이즈본을 표시
FastImage.preload([{ uri: 'https://cdn.example.com/img.jpg' }]);
//... 마운트 시
<FastImage source={{ uri: 'https://cdn.example.com/img.jpg?w=300&h=300' }} />
// → 캐시 키가 다름 → 마운트 시 재다운로드 → 프리로드 의미 없음

// ✅ 올바른 예 — 표시할 URL 그대로 프리로드
const displayUrl = 'https://cdn.example.com/img.jpg?w=300&h=300';
FastImage.preload([{ uri: displayUrl }]);
//... 마운트 시
<FastImage source={{ uri: displayUrl }} />

표시용 URL을 만드는 함수를 하나 만들어 두고, 프리로드와 렌더링 양쪽에서 같은 함수를 호출하면 불일치를 원천 차단할 수 있다.

const buildImageUrl = (id: string, w: number, h: number) =>
  `https://cdn.example.com/${id}.jpg?w=${w}&h=${h}`;

const url = buildImageUrl('img', 300, 300);
FastImage.preload([{ uri: url }]); // 프리로드
<FastImage source={{ uri: url }} />; // 렌더링

3) resizeMode와 "실제 리사이징"을 혼동하지 않는다

즉 resizeMode만 다르고 URL이 같으면 프리로드는 그대로 유효하다. 신경 쓸 건 "URL이 달라지는 리사이징"뿐이다.

4) URL이 미세하게 달라지는 케이스 주의 (캐시 미스 유발)

같은 이미지인데 캐시 미스가 나는 흔한 원인들:

• 쿼리 파라미터 순서가 다름 (?w=300&h=300 vs ?h=300&w=300)
• 불필요한 파라미터가 붙거나 빠짐 (&t=... 타임스탬프, 트래킹 파라미터 등)
• 프로토콜/도메인 차이 (http vs https, cdn. 유무)
• 대소문자/인코딩 차이 (%2F vs /)

→ URL을 정규화(normalize) 해서 프리로드와 렌더링에 동일하게 쓰는 것이 안전하다.

5) 인증 헤더 / 서명(presigned) URL 주의

• 헤더가 필요한 이미지는 프리로드 시에도 같은 headers를 넘겨야 한다.

  FastImage.preload([
    { uri: url, headers: { Authorization: `Bearer ${token}` } },
  ]);

• 서명/만료되는 URL(presigned) 은 특히 주의한다.

  • 프리로드할 때 생성한 URL과 렌더링할 때 생성한 URL의 서명 쿼리(X-Amz-Signature, 토큰 등)가 다르면 서로 다른 캐시 키가 된다 → 캐시 미스.
  • 프리로드 후 마운트까지 시간이 지나 토큰이 만료되면 다운로드 자체가 실패할 수 있다.
  • 대응: 같은 URL 문자열을 재사용하거나, 만료 시간을 충분히 길게 잡거나, (포크가 지원한다면) 안정적인 cacheKey를 사용한다.

6) 프리로드 양과 타이밍

• 곧 화면에 보일 것만 선별적으로 프리로드한다. 리스트 전체를 한 번에 프리로드하면 대역폭·디스크·메모리 낭비다.
• 다음 화면 진입 직전, 또는 리스트에서 곧 보일 다음 페이지 정도만 미리 받는 패턴이 적절하다.
• 프리로드는 fire-and-forget 으로 두되, 결과를 기다려 UI를 막지 않는다.

7) 프리로드가 보장하는 범위

• 프리로드는 보통 네트워크 다운로드 + 디스크 캐시 저장까지를 보장한다.
• 디코딩(decode)·디스플레이 준비까지 미리 끝내주는 것은 아니다. 따라서 마운트 시점에 디코딩 비용은 남을 수 있다. "프리로드 = 화면에 즉시 픽셀이 뜬다"가 아니라 "네트워크 왕복을 없애준다"로 이해한다.

정리

이미지 URL에 리사이징·최적화 파라미터를 붙이는 것은 단순한 편의 기능이 아니라, 네트워크·메모리·렌더링 성능을 한 번에 개선하는 핵심 최적화 기법이다. 요점은 다음과 같다.

• 표시 크기에 맞춰 w를 지정해 불필요하게 큰 이미지를 받지 않는다.
• React Native에서는 PixelRatio를 반영하되, 과도한 요청을 막기 위해 DPR 상한을 두는 것을 고려한다.
• q=75~85로 화질과 용량의 균형을 맞춘다.
• f=webp(또는 상황에 따라 avif)로 포맷을 최적화한다.
• 파라미터 조합을 일정하게 유지해 CDN 캐시 적중률을 높인다.

특히 메모리에 민감한 모바일 환경에서는, 비트맵 디코딩 메모리가 파일 용량이 아니라 픽셀 수에 비례한다는 점 때문에 리사이징의 효과가 웹보다 훨씬 크게 나타난다.

모던 웹·앱에서 이미지를 다룰 때, 원본 이미지를 그대로 내려받는 경우는 거의 없다. 대신 이미지 CDN 또는 이미지 변환 서버(image transformation server)에 쿼리 파라미터를 붙여서 "내가 필요한 크기·품질·포맷으로 변환해서 내려달라"고 요청한다. 이 방식을 on-the-fly image resizing 또는 dynamic image optimization이라 부른다.

대표적인 서비스로 Cloudinary, imgix, Thumbor, Cloudflare Images, Next.js Image Optimization, ImageKit 등이 있다. 파라미터 이름은 서비스마다 조금씩 다르지만 개념은 동일하다.

https://cdn.example.com/photo.jpg?w=300&q=85&f=webp
                                  └──────┬──────┘
                                   변환 요청 파라미터

서버는 이 요청을 받으면 원본을 변환한 결과를 생성하고, 그 결과를 캐시에 저장한 뒤 응답한다. 같은 파라미터로 다시 요청이 오면 캐시된 결과를 즉시 반환하므로 변환 비용은 최초 1회만 발생한다.

1.주요 파라미터

1) w / h — 너비·높이 (width / height)

출력 이미지의 크기를 픽셀 단위로 지정한다. 가장 핵심적인 파라미터다.

?w=300        // 너비 300px로 리사이즈 (높이는 비율 유지)
?w=300&h=200  // 300×200으로 리사이즈

원본이 4000×3000인 이미지를 화면에서는 300px로만 보여준다면, 원본을 그대로 받는 것은 거대한 낭비다. w=300으로 요청하면 서버가 300px짜리로 줄여서 내려주므로 전송량이 수십 배 줄어든다.

2) q — 품질 (quality)

JPEG·WebP 같은 손실 압축 포맷의 압축 강도를 지정한다. 보통 1~100 범위이며, 값이 낮을수록 용량은 작아지지만 화질이 떨어진다.

?q=85   // 품질 85 (용량/화질 균형점으로 널리 쓰임)

대체로 75~85 구간이 사람 눈에 화질 저하가 거의 느껴지지 않으면서 용량을 크게 줄이는 sweet spot이다. 100은 거의 무손실에 가깝지만 용량 대비 이득이 작아 실무에서는 잘 쓰지 않는다.

3) f / fm / format — 출력 포맷 (format)

이미지를 어떤 포맷으로 변환할지 지정한다.

?f=webp   // WebP로 변환
?f=avif   // AVIF로 변환
?f=auto   // 클라이언트가 지원하는 최적 포맷 자동 선택

포맷별 특징은 아래와 같다.

동일 화질 기준으로 WebP는 JPEG보다 보통 25~35% 작고, AVIF는 그보다 더 작다. 다만 AVIF는 디코딩에 CPU를 더 쓰므로 저사양 기기에서는 렌더링이 느려질 수 있어 트레이드오프를 고려해야 한다.

4) dpr — 디바이스 픽셀 비율 (device pixel ratio)

고해상도 디스플레이를 위한 배율이다. 일부 CDN은 w와 별개로 dpr를 받아 내부적으로 곱해준다.

?w=100&dpr=3   // 실제로는 300px짜리를 생성

이 파라미터를 지원하지 않는 서버라면, 클라이언트에서 직접 w에 픽셀 비율을 곱해 보내야 한다(아래 React Native 섹션 참고).

5) fit / c — 크롭·맞춤 모드 (fit / crop)

지정한 박스에 이미지를 어떻게 맞출지 결정한다.

?w=300&h=300&fit=cover     // 박스를 꽉 채우고 넘치는 부분은 잘라냄
?w=300&h=300&fit=contain   // 비율 유지하며 박스 안에 모두 담음(여백 생길 수 있음)

cover는 썸네일·프로필 이미지처럼 정사각형 박스를 빈틈없이 채워야 할 때, contain은 이미지 전체가 잘리지 않고 보여야 할 때 쓴다.

React Native에서의 활용

React Native에서는 PixelRatio를 통해 기기의 픽셀 밀도를 얻어 w 파라미터에 반영하는 패턴이 핵심이다. 레이아웃 단위(dp)와 실제 물리 픽셀(px)이 다르기 때문이다.

import { PixelRatio } from 'react-native';

export const resizeImageUrl = (url: string, width: string): string => {
  if (!url) return '';

  const newWidth = width * PixelRatio.get();
  const quality = 85;
  const separator = url.includes('?') ? '&' : '?';

  return url + `${separator}w=${Math.floor(newWidth)}&q=${quality}&f=webp`;
};

핵심은 width * PixelRatio.get()이다. PixelRatio.get()은 기기의 DPR을 반환한다(@2x 기기면 2, @3x 기기면 3). 화면에 100dp로 그릴 이미지라도 @3x 기기에서는 300px짜리 이미지를 받아와야 선명하게 보인다. 이 보정을 하지 않으면 고해상도 화면에서 이미지가 뿌옇게 보이고, 반대로 항상 최대 배율로 받으면 저해상도 기기에서 불필요하게 큰 이미지를 받게 된다.

separator 처리는 URL에 이미 쿼리스트링이 있는지에 따라 ?와 &를 구분해 붙여 URL이 깨지지 않게 하는 안전장치다.

보완 포인트

PixelRatio.get()을 그대로 곱하면 @3x 기기에서 넓은 이미지를 요청할 때 요청 너비가 과하게 커질 수 있다. 다음과 같은 방식으로 다듬을 수 있다.

// 방법 1: RN이 제공하는 헬퍼 사용 (반올림 처리까지 해줌)
const newWidth = PixelRatio.getPixelSizeForLayoutSize(width);

// 방법 2: DPR에 상한선을 둠 (예: 최대 2배까지만)
const dpr = Math.min(PixelRatio.get(), 2);
const newWidth = width * dpr;

DPR에 상한을 두는 이유는, @3x와 @2x의 실질적 화질 차이가 사람 눈에 잘 구분되지 않는 경우가 많은 반면 용량 차이(3²:2² = 2.25배)는 크기 때문이다. 화질과 용량의 균형을 위해 실무에서 자주 쓰는 기법이다.

효과

1) 네트워크 트래픽 절감

가장 직접적인 효과다. 4000×3000(약 5MB) 원본을 300px WebP(수십 KB)로 변환하면 전송량이 수십 배에서 100배 이상 줄어든다. 모바일 데이터 환경에서 체감 로딩 속도가 크게 개선되고, CDN 전송 비용도 절감된다.

2) 메모리 사용량 감소

이 효과는 특히 React Native에서 중요하다. 이미지는 디코딩되면 압축이 풀린 비트맵 상태로 메모리에 올라간다. 비트맵 메모리는 대략 너비 × 높이 × 4바이트(RGBA)로 계산된다.

• 4000×3000 원본 : 약 48MB (파일 용량과 무관하게 디코딩 시 메모리)
• 300×225로 리사이즈 : 약 270KB

긴 리스트에서 원본 이미지를 그대로 쓰면 메모리가 폭증해 OOM(Out Of Memory) 크래시로 이어지기 쉽다. 표시 크기에 맞춰 리사이즈된 이미지를 받으면 이 문제를 근본적으로 줄일 수 있다.

3) 렌더링·스크롤 성능 향상

디코딩해야 할 픽셀 수가 줄어들면 디코딩 시간이 짧아지고, GPU에 올리는 텍스처 크기도 작아진다. 그 결과 이미지가 화면에 표시되기까지의 지연이 줄고, 리스트 스크롤 시 프레임 드랍이 완화된다.

4) 포맷 최적화에 따른 추가 절감

f=webp 또는 f=avif로 변환하면 같은 화질에서 용량을 추가로 줄인다. WebP는 JPEG 대비 평균 25~35% 작으므로, 리사이즈 효과와 곱해져 전체 절감 폭이 더 커진다.

5) CDN 캐싱과의 시너지

변환 결과는 파라미터 조합을 키로 캐싱된다. 즉 ?w=300&q=85&f=webp로 들어온 요청은 최초 1회만 변환되고 이후에는 엣지 캐시에서 즉시 응답된다. 사용하는 파라미터 조합의 가짓수를 일정하게 유지(예: DPR 상한, 정해진 너비 단계 사용)하면 캐시 적중률이 높아져 변환 부하와 응답 지연이 함께 줄어든다.

<FastImage />만 잘 써도 대부분의 화면은 동작한다. 하지만 리스트 → 상세 화면 전환에서 이미지가 한 박자 늦게 뜨는 깜빡임, 무거운 갤러리 화면 진입 후 앱이 버벅이거나 백그라운드에서 강제 종료(OOM kill)되는 현상, 사용자 저장 공간을 잡아먹는 누적 디스크 캐시 등은 결국 언제 캐시에 올리고 언제 비울 것인가의 문제다.

RN CLI 환경에서 이미지 캐싱과 관련해 자주 부딪치는 세 가지 작업—프리로드, 메모리 캐시 정리, 디스크 캐시 정리—을 각각 어떤 타이밍에 호출하는 것이 적절한지 정리해보자.

본 글은 @d11/react-native-fast-image를 기준으로 작성했다. 원본 react-native-fast-image(DylanVann)는 유지보수가 멈췄고, @d11 포크가 New Architecture(Fabric)를 지원하므로 New Arch 프로젝트에서는 이쪽을 쓴다. iOS는 SDWebImage, Android는 Glide를 내부 백엔드로 사용한다.

• 프리로드: FastImage.preload(sources)
• 메모리 캐시 정리: FastImage.clearMemoryCache()
• 디스크 캐시 정리: FastImage.clearDiskCache()

1. 메모리 캐시 vs 디스크 캐시

타이밍 얘기 전에 먼저 두 캐시의 차이를 분명히 해두는 게 좋다. 헷갈리면 잘못된 시점에 잘못된 캐시를 비우게 된다.

핵심은 메모리 캐시 정리는 비교적 안전한 동작이고, 디스크 캐시 정리는 비싸고 되돌릴 수 없는 동작이다. 이 비대칭을 기억하면 호출 타이밍 판단이 훨씬 쉬워진다.

2. 프리로드 (preload)

목적: 사용자가 화면을 보기 직전에 미리 이미지를 다운받아, 진입하자마자 깜빡임 없이 노출되도록 하는 것이 목표이다.

1) 언제 호출하는가

① 목록 → 상세 화면 진입 직전

리스트에서 카드를 누르는 순간(onPress 핸들러 내부)에 다음 화면의 메인 이미지를 프리로드한다. 네비게이션 전환 애니메이션(보통 250~400ms) 동안 이미지가 백그라운드에서 로드되어, 상세 화면이 뜨는 시점에는 이미 메모리에 올라와 있다.

const onPressItem = (item: Item) => {
  FastImage.preload([{ uri: item.heroImageUrl }]);
  navigation.navigate('Detail', { itemId: item.id });
};

onPress가 아니라 onPressIn에 걸면 더 일찍 시작할 수도 있다. 다만 사용자가 실수로 닿기만 해도 호출되므로 트래픽 낭비가 생긴다. onPress가 균형점이다.

② 무한 스크롤 / 페이지네이션 데이터 도착 직후

다음 페이지의 API 응답을 받은 직후, 렌더링 전에 상위 N개 아이템의 이미지를 프리로드한다.

const { data } = await fetchNextPage();
const urlsToPreload = data
  .slice(0, 12)               // 화면에 먼저 보일 만큼만
  .map(item => item.thumbnail);
FastImage.preload(urlsToPreload.map(uri => ({ uri })));

③ 앱 진입 직후 (필수 데이터에 한정)

스플래시 화면이나 초기 부트스트랩 단계에서, 홈 최상단에 반드시 노출되는 배너/히어로 이미지 1~2개. 그 이상은 권장하지 않는다.

④ 다음 캐러셀 슬라이드

스와이프 캐러셀에서 현재 슬라이드의 다음 1~2장. 사용자가 스와이프하는 순간 이미지가 이미 메모리에 있다.

2) 실무 팁

선택과 집중 — 전부 프리로드하지 마라

데이터 배열의 모든 이미지를 프리로드하면 다음이 발생한다.

• 네트워크 병목 수십~수백 개 요청이 동시에 발사되어 정작 화면에 보이는 이미지 다운로드가 느려진다.

• 유저 데이터 요금 낭비 셀룰러 사용자에겐 보이지도 않을 이미지에 대한 트래픽 청구.

• 메모리 캐시 오염 보이지 않을 이미지가 메모리를 차지해, 정작 필요한 이미지가 밀리게 된다.

배치 상한선을 두는 것이 표준이다. 예를 들어 한 번에 최대 40~50개로 제한하는 식이다.

const PRELOAD_BATCH_LIMIT = 48;

function safePreload(urls: string[]) {
  const sources = urls
    .slice(0, PRELOAD_BATCH_LIMIT)
    .map(uri => ({ uri }));
  FastImage.preload(sources);
}

우선순위 — '먼저 보일 것'을 먼저

스크롤 아래 안 보이는 이미지를 프리로드하느니, 상단 viewport에 곧 들어올 이미지에 집중한다. FastImage는 priority: 'high' | 'normal' | 'low'를 지원하므로 활용한다.

FastImage.preload([
  { uri: heroUrl, priority: FastImage.priority.high },
  ...thumbnailUrls.map(uri => ({ uri, priority: FastImage.priority.normal })),
]);

캐시 정책 — source.cache로 갱신 동작을 제어

FastImage는 소스 단위로 캐시 제어 옵션을 제공한다. 프리로드/렌더 시 동일하게 지정한다.

• FastImage.cacheControl.immutable(기본값): URL이 같으면 갱신하지 않는다. 콘텐츠가 바뀌지 않는 정적 리소스에 적합하다.
• FastImage.cacheControl.web: HTTP 캐시 헤더(만료/ETag)를 존중해 필요 시 재검증한다.
• FastImage.cacheControl.cacheOnly: 캐시에서만 로드하고 네트워크 요청은 하지 않는다.

FastImage.preload([
  { uri: heroUrl, cache: FastImage.cacheControl.web }, // 자주 바뀌는 이미지
]);

네트워크 상태 고려

셀룰러나 저속 네트워크에서는 프리로드를 줄이거나 끄는 것이 좋다. @react-native-community/netinfo로 연결 종류를 확인할 수 있다.

const { type } = await NetInfo.fetch();
if (type === 'wifi') {
  FastImage.preload(sources);
}

프리로드는 "결과를 기다리지 않는" 패턴

대부분의 경우 프리로드는 fire-and-forget이다. 완료를 기다리지 않고 즉시 다음 단계로 진행하며, 운 좋게 미리 받아져 있으면 좋고 아니면 평소처럼 로드된다. await FastImage.preload(...)로 묶는 건 의미가 없을 뿐 아니라(promise도 아님) 화면 진입을 지연시키는 안티패턴이다.

3. 메모리 캐시 정리 (clearMemoryCache)

목적: RAM 점유를 낮춰 OOM 종료를 방지하고, 무거운 화면 진입 후의 메모리 압박을 완화한다.

1) 언제 호출하는가

① 이미지 많은 화면을 떠날 때 (unmount)

수십 장의 이미지가 노출되는 갤러리, 탐색, 피드 상세 화면 등이 unmount 될 때 useEffect의 cleanup에서 호출한다.

useEffect(() => {
  return () => {
    FastImage.clearMemoryCache();
  };
}, []);

여기서 디스크 캐시는 그대로 남아 있으므로, 사용자가 다시 그 화면으로 돌아왔을 때 네트워크 재다운로드는 발생하지 않는다(디스크에서 복원). 그래서 비교적 안전한 동작이다.

② 앱이 백그라운드로 전환될 때

AppState를 감지해 'background' 진입 시점에 메모리 캐시를 비우면, OS가 메모리 부족 상태에서 우리 앱을 강제 종료할 확률이 줄어든다. 특히 이미지가 많은 앱에서는 효과가 크다.

useEffect(() => {
  const sub = AppState.addEventListener('change', state => {
    if (state === 'background') {
      FastImage.clearMemoryCache();
    }
  });
  return () => sub.remove();
}, []);

③ 메모리 경고 시 (iOS) / Trim Memory 콜백 (Android)

iOS는 UIApplicationDidReceiveMemoryWarningNotification을, Android는 onTrimMemory 콜백을 발생시킨다. 이 신호를 받는 시점이야말로 메모리 캐시를 비우기 가장 좋은 타이밍이다. 다만 RN JS 측에서 직접 듣기는 까다로워서, 보통은 라이브러리가 내부적으로 처리하거나 별도 네이티브 모듈/브릿지(New Architecture라면 TurboModule)가 필요하다. FastImage는 내부적으로 SDWebImage(iOS) / Glide(Android)를 사용하므로 메모리 경고에 대한 기본 대응이 어느 정도 들어 있다.

2) 주의사항

1. 너무 자주 비우면 깜빡임이 생긴다

화면 전환마다 메모리 캐시를 비우면, 디스크에서 다시 RAM으로 끌어와 디코딩하는 비용이 매번 발생해 미세한 깜빡임이나 지연이 보일 수 있다. 확실한 분기점(무거운 화면 unmount, 백그라운드 전환)에서만 호출한다.

2. 리스트 컴포넌트 unmount에서 무분별하게 호출 금지

탭 전환마다 unmount되는 화면에서 매번 메모리 캐시를 비우면, 탭을 오갈 때마다 모든 이미지가 다시 디코딩된다. 충분히 무거운 화면(50장 이상의 이미지, 큰 해상도)에 한정해서 적용한다.

3. clearMemoryCache()는 Promise를 반환한다

FastImage.clearMemoryCache()는 Promise를 반환한다. 완료를 기다려야 하는 시나리오는 거의 없지만, 로그아웃 등 후속 동작이 있는 경우에는 await로 묶는다.

4. 디스크 캐시 정리 (clearDiskCache)

사용자의 물리적 저장 공간을 확보하고, 캐시 무결성을 보장하는 것을 목적으로 한다. (예: 동일 URL이지만 내용이 바뀐 이미지가 있는 경우)

1) 언제 호출하는가

① 사용자의 명시적 요청

설정 화면의 "캐시 데이터 지우기" 버튼처럼, 사용자가 의도적으로 누른 경우.

const onPressClearCache = async () => {
  await FastImage.clearDiskCache();
  await FastImage.clearMemoryCache(); // 함께 정리하는 게 일반적
  showToast('캐시를 정리했습니다');
};

② 로그아웃 / 회원 탈퇴 시

이전 사용자의 프로필 사진, 비공개 이미지 등이 디스크에 남아 있을 수 있다. 다음 사용자에게 노출되지 않도록 정리한다. auth 도메인의 로그아웃 핸들러 내부에서 호출한다.

async function logout() {
  await apiLogout();
  await FastImage.clearDiskCache();
  await FastImage.clearMemoryCache();
  resetAuthState();
}

③ 앱 버전 업데이트 후 (선택적)

이미지 URL 정책이 바뀌었거나, 캐시 키 구조가 바뀌었거나, CDN을 교체한 경우 한 번에 한해 정리. 사용자 모르게 자동으로 실행되도록 한다.

④ 캐시 무결성 이슈 발생 시

서버에서 동일 URL의 이미지 내용을 바꿔버린 경우(잘못된 운영 관행이지만 현실에선 자주 발생), 기존 디스크 캐시는 잘못된 이미지를 계속 반환한다. 이때 임시 대응으로 사용. 근본 해결은 URL에 해시/버전을 붙이는 것이다.

2) 실무 팁

• 렌더링 사이클이나 스크롤 중에는 절대 호출하지 않는다

디스크 I/O는 비용이 큰 작업이다. 스크롤 도중 호출하면 프레임 드랍이 발생한다. UI가 정적인 시점(설정 화면, 로그아웃 직후 등)에서만 호출한다.

• 비가역적이라는 점을 사용자에게 인지시킨다

디스크 캐시를 비우면 사용자가 자주 보던 이미지도 다시 네트워크에서 받아와야 한다. 셀룰러 환경에선 추가 데이터 요금이 나간다. 명시적 정리 버튼에는 확인 다이얼로그를 띄우는 것이 일반적이다.

• 자동 정리는 신중하게

"일정 주기마다 자동으로 디스크 캐시 비우기" 같은 정책은 거의 항상 잘못된 결정이다. FastImage는 내부 백엔드(SDWebImage / Glide)의 LRU 기반 캐시 evict 정책을 그대로 사용하므로, 수동 개입 없이도 무한정 늘어나지 않는다. 굳이 자동 정리를 한다면 "디스크 사용량이 X MB를 넘으면" 같은 임계치 기반이 더 적절하다.

5. 자주 만나는 함정

1) 프리로드를 useEffect로 매 렌더마다 호출

// ❌ 의존성 배열 잘못 잡으면 매 렌더 호출
useEffect(() => {
  FastImage.preload(items.map(i => ({ uri: i.url })));
});

items가 새 배열로 만들어질 때마다 동일 URL을 재요청한다. 라이브러리가 중복 제거를 해주긴 하지만, 검사 비용이 발생한다. 의존성을 정확히 지정하거나, 데이터가 처음 도착했을 때 한 번만 호출하는 패턴을 쓴다.

2) 로그아웃 시 메모리 캐시만 비우고 디스크는 안 비움

토큰이 만료된 상태로 디스크 캐시에 남은 인증 이미지 URL이 있다면, 다음 로그인 시점에 잘못된 권한으로 이미지가 표시되거나(또는 안 표시) 다른 사용자의 캐시가 노출될 수 있다. 로그아웃 시에는 메모리 + 디스크 모두 비우는 것이 안전하다.

3) 모든 화면에서 clearMemoryCache

"메모리 절약된다"는 이유로 모든 화면 unmount마다 호출하면, 디코딩 비용이 매번 발생하고 오히려 체감 성능이 나빠진다. 이미지가 많고 무거운 화면에 한정한다.

4) Image.prefetch(React Native 내장)와 FastImage.preload 혼동

React Native 내장 Image.prefetch()는 OS 레벨 HTTP 캐시에만 영향을 주고, FastImage의 내부 캐시(iOS의 SDWebImage, Android의 Glide)와는 별개다. FastImage를 쓴다면 반드시 FastImage.preload()를 써야 캐시가 실제로 채워진다. 둘을 섞어 쓰면 프리로드했다고 생각한 이미지가 정작 FastImage 렌더 시 캐시 미스로 다시 받아진다.

6. 정리

원칙은 단순하다.

• 프리로드는 "곧 보일 것"에만, 상한선을 두고.
• 메모리 캐시 정리는 "확실한 분기점"에서만.
• 디스크 캐시 정리는 "사용자가 동의한 명시적 시점"에서만.

이 세 가지만 지켜도 이미지 깜빡임, OOM kill, 저장 공간 잠식이라는 흔한 세 가지 문제를 대부분 막을 수 있다.

디자이너가 만든 애니메이션을 앱에 그대로 옮기는 일은 생각보다 까다롭다. 로딩 스피너 하나만 해도 회전 속도, 이징, 페이드 타이밍을 코드로 다시 맞춰야 하고, 결과물은 대체로 원본과 미묘하게 다르다.

Lottie는 이 과정을 없애는 방식으로 접근한다. After Effects에서 만든 애니메이션을 Bodymovin 플러그인으로 JSON으로 내보내면, 네이티브 런타임이 그 JSON을 읽어 벡터로 직접 그린다. 개발자가 다시 만들 필요가 없고, 디자이너가 수정하면 JSON 파일만 교체하면 된다.

React Native에서는 lottie-react-native가 iOS의 lottie-ios와 Android의 lottie-android를 감싸서 제공한다. 현재 최신 버전은 7.x대이며 New Architecture를 지원한다.

Lottie를 선택하는 기준

애니메이션을 넣는 방법은 크게 세 가지다. Reanimated로 직접 구현하거나, GIF나 동영상을 재생하거나, Lottie를 쓰는 것이다.

Reanimated는 사용자 입력에 반응해야 할 때 유리하다. 드래그 위치에 따라 카드가 따라오거나, 스크롤 값에 헤더가 연동되는 동작은 Lottie로 표현하기 어렵다. 반대로 복잡한 일러스트가 여러 레이어로 움직이는 애니메이션을 Reanimated로 만드는 건 비효율적이다.

GIF나 동영상은 래스터 이미지라 고해상도 기기에서 뭉개지고, 배경 투명 처리가 번거롭고, 파일이 무겁다. 같은 애니메이션이 GIF로 2MB일 때 Lottie JSON은 수십 KB에 그치는 경우가 흔하다.

Lottie는 정해진 타임라인을 그대로 재생하는 데 최적화되어 있다. 스플래시, 온보딩 일러스트, 로딩 인디케이터, 결제 성공 화면, 빈 목록 화면처럼 "예쁘게 보여주고 끝나는" 구간이 주 무대다. 여기에 재생 구간을 나눠 상태에 따라 다른 부분을 재생하는 정도의 인터랙션까지는 충분히 소화한다.

설치와 New Architecture

RN CLI 프로젝트 기준으로 설치는 단순하다.

npm install lottie-react-native
cd ios && pod install

New Architecture가 켜져 있어도 별도 설정은 필요 없다. 7.x는 Fabric 컴포넌트로 구현되어 있어 newArchEnabled=true 상태에서 그대로 동작한다. 다만 6.x 이하 버전은 Fabric 지원이 불완전해 iOS에서 첫 렌더가 비는 문제가 보고된 적이 있으므로, New Architecture를 쓴다면 7.x 이상으로 올리는 편이 안전하다.

애니메이션 파일은 src/assets/lottie/ 같은 디렉터리에 두고 require로 참조한다. Metro가 기본적으로 .json을 처리하므로 추가 설정은 없다.

기본 사용법

import LottieView from 'lottie-react-native';

export function LoadingIndicator() {
  return (
    <LottieView
      source={require('@/assets/lottie/loading.json')}
      style={{ width: 120, height: 120 }}
      autoPlay
      loop
    />
  );
}

style에 크기를 반드시 지정해야 한다. LottieView는 기본 크기를 갖지 않아서 크기가 없으면 아무것도 보이지 않는다. Lottie가 안 나온다는 문의의 절반 이상이 여기서 나온다.

resizeMode는 contain, cover, center를 지원하며 기본값은 contain이다. 디자인 시안의 비율과 컨테이너 비율이 다르면 여백이 생기므로, 배경에 꽉 채워야 하는 경우에만 cover를 쓴다.

재생 제어

autoPlay만으로 부족한 경우 ref로 명령형 제어를 한다.

const lottieRef = useRef<LottieView>(null);

lottieRef.current?.play();        // 처음부터 재생
lottieRef.current?.play(30, 90);  // 30~90 프레임 구간만 재생
lottieRef.current?.pause();
lottieRef.current?.resume();
lottieRef.current?.reset();

구간 재생이 실무에서 가장 쓸모 있다. 하나의 JSON에 여러 상태의 애니메이션을 담아두고 프레임 범위로 나눠 쓰는 방식인데, 파일을 여러 개로 쪼개는 것보다 관리가 편하고 상태 전환도 매끄럽다.

좋아요 버튼이 전형적인 예다.

export function LikeButton({ liked, onToggle }: Props) {
  const lottieRef = useRef<LottieView>(null);

  const handlePress = () => {
    if (!liked) {
      lottieRef.current?.play(0, 60); // 채워지는 구간
    } else {
      lottieRef.current?.reset();
    }
    onToggle();
  };

  return (
    <Pressable onPress={handlePress} hitSlop={8}>
      <LottieView
        ref={lottieRef}
        source={require('@/assets/lottie/heart.json')}
        style={{ width: 40, height: 40 }}
        loop={false}
        progress={liked ? 1 : 0}
      />
    </Pressable>
  );
}

progress를 함께 넘긴 이유는 서버 상태가 늦게 도착하거나 화면을 다시 진입했을 때의 초기 표시 때문이다. 애니메이션 없이 이미 좋아요가 눌린 상태를 그려야 하는 순간이 반드시 생긴다.

재생이 끝나는 시점을 잡아야 한다면 onAnimationFinish를 쓴다.

<LottieView
  source={require('@/assets/lottie/payment-success.json')}
  style={styles.animation}
  autoPlay
  loop={false}
  onAnimationFinish={() => navigation.replace('OrderDetail', { orderId })}
/>

loop가 켜져 있으면 이 콜백은 호출되지 않는다. 그리고 일부 7.x 초기 버전에서 마운트 직후 콜백이 한 번 잘못 발화되는 이슈가 있었으므로, 화면 전환처럼 되돌릴 수 없는 동작을 붙일 때는 실제 기기에서 확인하고 필요하면 플래그로 한 번만 실행되게 막는다.

색상 커스터마이징

다크 모드나 테마 대응 때문에 애니메이션 색상만 바꿔야 할 때가 있다. 매번 디자이너에게 색상별 파일을 요청하는 대신 colorFilters로 특정 레이어의 색을 덮어쓸 수 있다.

<LottieView
  source={require('@/assets/lottie/spinner.json')}
  style={{ width: 48, height: 48 }}
  colorFilters={[{ keypath: 'Shape Layer 1', color: theme.colors.primary }]}
  autoPlay
  loop
/>

keypath는 After Effects의 레이어 이름과 정확히 일치해야 한다. 디자이너에게 레이어 이름을 의미 있게 지어달라고 미리 요청해두면 나중에 훨씬 편하다. 다만 이 기능은 iOS와 Android의 렌더러 구현 차이 때문에 결과가 완전히 같지 않은 경우가 있어, 양쪽 모두에서 확인이 필요하다.

주의사항

After Effects 기능이 전부 지원되지는 않는다. 표현식, 일부 마스크, 블렌드 모드, 특정 이펙트는 무시되거나 다르게 그려진다. 시안이 확정되기 전에 디자이너와 지원 범위를 맞춰두는 게 낫다. 작업이 끝난 뒤 "이 부분이 안 나온다"를 발견하면 재작업 비용이 크다.

JSON 파일 크기를 확인한다. 벡터로만 구성된 애니메이션은 대체로 가볍지만, 비트맵 이미지가 포함되면 base64로 인코딩되어 파일이 수 MB까지 부풀 수 있다. 번들 크기와 파싱 시간에 직접 영향을 주므로, 이미지가 포함된 파일을 받았다면 벡터로 다시 작업할 수 있는지 물어보는 편이 좋다.

리스트 안에서 여러 개를 동시에 재생하지 않는다. FlatList의 각 아이템마다 Lottie가 루프를 돌면 프레임 드랍이 눈에 띄게 발생한다. 화면에 보이는 항목만 재생하도록 viewabilityConfig와 연동하거나, 리스트에서는 정적 이미지를 쓰고 상세 화면에서만 애니메이션을 재생하는 방식을 고려한다.

백그라운드 전환 후 복귀를 확인한다. 앱이 백그라운드로 갔다 돌아오면 애니메이션이 멈춘 채로 남는 경우가 있다. 로딩 오버레이처럼 계속 돌아야 하는 요소라면 AppState를 구독해 다시 resume()을 호출한다.

모션 감소 설정을 존중한다. OS에서 모션 줄이기를 켠 사용자에게는 애니메이션이 불편할 수 있다. AccessibilityInfo.isReduceMotionEnabled()로 확인해 정적인 대체 화면을 보여주는 처리를 넣어두면 좋다.

트러블슈팅

아무것도 보이지 않을 때는 style의 크기부터 확인한다. 크기가 있는데도 안 보인다면 JSON 파일 자체가 올바른지, 애니메이션의 색상이 배경과 같지는 않은지 본다.

.lottie 파일이 로드되지 않을 때는 .json으로 바꿔본다. dotLottie 형식은 내부적으로 zip이라 별도 처리가 필요한데, Android의 New Architecture 환경에서 zip을 JSON으로 파싱하려다 실패하는 버그가 보고된 적이 있다. 압축률이 절실하지 않다면 .json이 무난하다.

네이티브 로그를 먼저 본다. JS 콘솔에는 아무 메시지가 없어도 Android의 Logcat이나 Xcode 콘솔에는 파싱 실패 이유가 남는 경우가 많다. 소수점이 들어가면 안 되는 값에 소수가 들어간 것처럼 파일 자체가 규격에 어긋난 상황도 여기서 확인된다.

원격 URL로 불러올 때는 캐싱을 직접 처리해야 한다. source에 URL 문자열을 넘기면 동작하지만 매번 다시 받아오므로, 자주 쓰는 애니메이션은 번들에 포함하고 자주 바뀌는 것만 원격으로 두는 식으로 나눈다.

정리

Lottie는 디자이너의 결과물을 그대로 앱에 옮기기 위한 도구다. 정해진 타임라인을 재생하는 영역에서는 직접 구현보다 압도적으로 효율적이고, 사용자 입력에 실시간으로 반응해야 하는 영역에서는 Reanimated가 여전히 맞다. 이 경계를 구분하는 것이 도입의 출발점이다.

실무에서 자주 마주치는 지점은 세 가지로 압축된다. style에 크기를 지정하는 것, 하나의 파일을 프레임 구간으로 나눠 상태별로 재생하는 것, 그리고 파일 크기와 동시 재생 개수를 성능 관점에서 관리하는 것이다.

New Architecture 환경이라면 7.x 이상을 쓰고, dotLottie 대신 JSON을 기본으로 두면 대부분의 문제를 미리 피할 수 있다.

React Native + Tamagui Dialog로 만든 알림 모달이 등장할 때마다 미세한 jank가 발생했다. 처음엔 모달 컴포넌트 자체가 무겁다고 의심했지만, 진짜 범인은 모달이 뜨는 그 순간 같이 발사되는 5개의 네트워크 요청이었다. 이 글은 그 원인을 좁혀가며 시도했던 우회들이 왜 실패했는지, 그리고 실무에서 제일 실용적인 해결법은 무엇이었는지 정리한 기록이다.

1. 증상

폼에서 "등록" 버튼을 누르면 BottomSheet가 닫히고 곧바로 "게시글이 등록되었습니다" 같은 알림 모달이 뜨는 흐름이 있었다.

• 모달이 등장할 때 약 1~2프레임 정도 끊김이 있었다.
• iOS·Android 모두 발생.
• 항상 끊기는 것은 아니다. 같은 동작을 반복하면 부드러울 때도, 끊길 때도 있었다.
• 모달이 사라질 때도 가끔 끊김. 다만 등장보다는 빈도가 훨씬 낮았다.

이 "있을 때도 있고 없을 때도 있다"가 결국 원인 추적의 결정적인 단서가 됐다.

2. 첫 번째 가설 — Tamagui Dialog가 무거운가?

알림 모달은 Tamagui의 Dialog + Dialog.Portal + Dialog.Overlay + Dialog.Content 조합으로 구현돼 있었다. Tamagui의 Dialog.Portal은 내부적으로 React Native의 Modal 컴포넌트를 mount한다. 즉 등장·소멸 시점마다 native modal window의 생성·해제 비용이 발생한다.

같은 코드베이스에 이미 다른 패턴으로 만든 특정 동작의 모달이 있었다. 그 모달은 Tamagui의 Portal(RN Modal이 아닌, 자체 PortalProvider 위치에 mount되는 쪽)과 Reanimated의 FadeIn/FadeOut을 직접 조합해서 native modal을 우회하고 있었다.

// 패턴 A — 자체 Portal + Reanimated 애니메이션
<Portal>
  <AnimatedView entering={BACKDROP_ENTERING} exiting={BACKDROP_EXITING} ...>
    <AnimatedView entering={CONTENT_ENTERING} exiting={CONTENT_EXITING} ...>
      {/* content */}
    </AnimatedView>
  </AnimatedView>
</Portal>

가설을 하나 세워봤다. "알림 모달도 패턴 A로 바꾸면 native modal 비용이 사라지니까 jank가 줄어들지 않을까?"

하지만 이 단계에서 멈춰서 진짜 원인이 무엇인지 한 번 더 확인하기로 했다. 우회로를 먼저 깔면 원인은 모른 채로 코드만 복잡해진다.

3.두 번째 가설 — 모달 등장 시점에 동시에 일어나는 일

모달이 뜨는 트리거를 따라가봤다. 게시글 생성 mutation의 onSuccess 콜백은 대략 이런 흐름이었다.

const { mutate: createReview } = useMutation({
  mutationFn: createPost,
  onSuccess: () => {
    dismissBottomSheetAndNext(() => {
      resetForm();
      setCompletedModalType('CREATED'); // ← 모달 등장 트리거

      queryClient.invalidateQueries({ queryKey: ... });  
       queryClient.invalidateQueries({ queryKey: ... });
    });
  },
});

같은 tick에서 모달 등장 + 폼 state 리셋 3~4개 + invalidateQueries 2개가 한꺼번에 실행되고 있었다.

특히 [POST_KEYS.ROOT] 같은 prefix key로 invalidate하면 그 prefix를 공유하는 모든 쿼리가 동시에 refetch된다. 네트워크 탭을 열어보니 실제로 모달이 뜨는 순간 5개의 API가 동시에 호출되고 있었다.

이게 jank의 핵심이었다.

1. setCompletedModalType이 모달 mount를 트리거.
2. 같은 tick에서 invalidate가 5개 쿼리에 refetch를 큐잉.
3. JS 스레드는 무효화/refetch 트리거 처리에 점유됨.
4. 응답들이 짧은 간격으로 도착하면서 각 구독자 컴포넌트가 연쇄적으로 리렌더.
5. 모달의 등장 애니메이션 프레임이 그 사이에 끼면서 1~2프레임을 드롭.

"항상 끊기지는 않는다"는 점이 여기서 설명된다. 네트워크 응답 타이밍에 따라 리렌더가 등장 애니메이션 윈도우에 겹치는 경우와 겹치지 않는 경우가 갈리는 것이다.

4. 가설 검증

원인을 확정하기 위해 가장 간단한 검증을 했다. invalidateQueries 호출만 일시적으로 주석 처리하고 빌드.

결과: 모달이 완전히 부드럽게 등장. 주석을 풀면 jank가 다시 돌아왔다. 재현 가능했다.

이 시점에서 패턴 A(자체 Portal로 모달 재작성)는 본질적인 해결책이 아니라는 것이 분명해졌다. native modal 비용도 영향을 줄 수는 있지만, 진짜 큰 비용은 동시에 발사되는 5개의 refetch였다.

5. 실패한 우회 1 — InteractionManager.runAfterInteractions

해결 방향은 명확했다. invalidate 호출을 모달 등장 애니메이션이 끝난 다음으로 미루기.

가장 먼저 떠오른 API는 InteractionManager.runAfterInteractions였다. "현재 진행 중인 인터랙션/애니메이션이 끝난 다음 콜백을 실행해준다"는 시맨틱이 정확히 우리가 원하는 것이었다.

InteractionManager.runAfterInteractions(() => {
  queryClient.invalidateQueries({ queryKey: [REVIEW_KEYS.ROOT] });
});

그런데 코드를 쓰자마자 의문이 들었다. React Native 최신 버전에서 deprecated 아니던가?

확인을 위해 node_modules/react-native/Libraries/Interaction/InteractionManager.d.ts를 열어봤다.

/**
 * @deprecated
 */
export interface InteractionManagerStatic {
  ...
  /**
   * Schedule a function to run after all interactions have completed.
   * @deprecated
   */
  runAfterInteractions(...): { ... };
  ...
}

InteractionManager.js 본체에도 @deprecated JSDoc이 있었고, 심지어 ReactNativeFeatureFlags.disableInteractionManager() 플래그가 켜지면 통째로 stub으로 대체되는 분기까지 들어가 있었다. 미래에 사라질 수 있는 API에 의존하는 건 분명한 안티패턴이었다.

실패 이유: API가 deprecated이며 stub으로 교체 가능. 시맨틱은 깔끔하지만 의존하면 안 됨.

6. 실패한 우회 2 — setImmediate

다음 후보는 setImmediate였다. "현재 task가 끝난 직후 다음 task에서 실행"이라는 시맨틱이고 deprecated도 아니었다.

setImmediate(() => {
  queryClient.invalidateQueries({ queryKey: [REVIEW_KEYS.ROOT] });
});

빌드하고 테스트했다. 여전히 끊겼다.

이유는 시간 스케일 미스매치였다.

• setImmediate는 보통 0~16ms 안에 실행된다.
• 모달의 fade-in 애니메이션은 약 200ms 안팎에 걸쳐 진행된다.

즉 setImmediate로 미뤄도 모달이 아직 fade-in 중인 시점에 invalidate가 시작된다. JS 스레드는 곧바로 다시 점유되고, 5개 응답이 도착할 때마다 리렌더가 등장 애니메이션 위에 떨어진다. "다음 tick" 정도의 지연은 등장 애니메이션 윈도우를 벗어나기엔 한참 짧았다.

실패 이유: 지연 시간이 모달 등장 애니메이션 duration에 비해 한 자릿수 짧음.

7. 작동한 해결책 — setTimeout 300ms

결국 가장 단순한 답으로 돌아왔다.

setCompletedModalType('CREATED');

setTimeout(() => {
  queryClient.invalidateQueries({ queryKey: [REVIEW_KEYS.ROOT] });
  queryClient.invalidateQueries({
    queryKey: [ENTITY_KEYS.WITH_BOOKMARK, ENTITY_KEYS.GET_DETAIL, entityId],
  });
}, 300);

300ms는 모달 fade-in duration(~210ms)에 약간의 여유를 더한 값이다. 빌드하고 테스트하니 jank가 완전히 사라졌다. 반복해도 끊김이 재현되지 않았다.

이게 적절한 해결책일까?

"setTimeout으로 시간을 때려박는 게 정답이라고?" 라는 직감이 드는 건 자연스럽다. 객관적으로 평가해보자. 살짝 꼼수처럼 쓰여지는 느낌이 없지않아 있다.

• 매직 넘버: 왜 300인지 코드만 보면 알 수 없다. 모달 애니메이션 duration이 바뀌면 깨질 수 있다.
• 시간 기반 동기화: "애니메이션이 끝났을 것이다"라는 시간 가정에 의존. 진짜 끝났는지 시그널을 받는 게 아니다.
• 인과관계가 드러나지 않음: 주석 없으면 다음 사람은 이 setTimeout이 왜 필요한지 모른다.

그럼에도 받아들여지는 패턴인 이유

1. TanStack Query 메인테이너도 인정한 패턴. "애니메이션 후 invalidate"는 커뮤니티에서 자주 인용된다.
2. deprecated API 의존이 없음. setTimeout은 사라질 일이 없는 표준 API.
3. 수정 비용 대비 효과 압도적. 1~2줄 추가로 jank 해결.
4. 시간 가정이 깨질 위험이 낮음. 모달 애니메이션 duration은 fixed value고, 디바이스 성능에 거의 영향받지 않는다(JS 스레드 점유로 늘어날 수는 있지만, 그 경우 더 잘 작동하는 방향).

산업 관행상 받아들여지는 "정당한 트레이드오프"의 범주에 들어간다. 꼼수의 색이 약간 있는 건 사실이지만, 안티패턴은 아니다.

더 본질적인 대안들 (참고)

setTimeout이 마음에 들지 않는다면 더 본질적인 방향도 있다. 다만 각각 다른 비용을 진다.

1. 낙관적 업데이트로 fan-out 자체 제거

invalidateQueries를 호출하지 않고, mutation 응답에 들어온 새 객체로 캐시를 직접 갱신한다.

onSuccess: (newReview) => {
  queryClient.setQueryData([REVIEW_KEYS.ROOT, REVIEW_KEYS.MINE, entityId], newReview);
  queryClient.setQueryData(
    [REVIEW_KEYS.ROOT, REVIEW_KEYS.LIST, entityId],
    (prev) => prependToInfiniteList(prev, newReview),
  );
  // ...
};

• 장점: refetch fan-out 자체가 없다. 시간 의존 0. 데이터 반영도 즉각적.
• 단점: 각 쿼리의 캐시 형태에 맞춰 분기 코드를 써야 한다. InfiniteData인지 단순 객체인지, 집계 데이터를 어떻게 업데이트할지 등. 코드량과 유지보수 부담이 늘어난다.

가장 본질적이지만 가장 비싸다. 캐시 모양이 자주 바뀌는 화면이면 비용이 더 커진다.

2. 모달 닫힐 때 invalidate

등장 시점이 아니라 사용자가 모달의 "확인" 버튼을 눌러 닫는 시점에 invalidate를 호출한다.

<Button onPress={() => {
  setCompletedModalType(null);
  queryClient.invalidateQueries({ queryKey: [REVIEW_KEYS.ROOT] });
}}>
  확인
</Button>

• 장점: 등장은 100% 부드럽다. 매직 넘버 없음.
• 단점: 닫힘 시점에 jank가 생길 수 있다. 또한 사용자가 모달을 보는 동안 뒤 화면 데이터는 stale 상태가 된다. 사용자가 모달을 닫지 않고 백 제스처로 뒤로 가면 새 데이터가 반영되지 않는다. dismiss 경로가 여러 개라면 모든 경로에서 invalidate가 호출되도록 신경써야 한다.

3. 애니메이션 완료 콜백으로 정확히 동기화

모달을 Tamagui Dialog가 아닌 Reanimated 기반으로 재작성하면 withTiming의 완료 콜백을 통해 정확한 시점에 invalidate를 호출할 수 있다.

opacity.value = withTiming(1, { duration: 210 }, (finished) => {
  if (finished) {
    runOnJS(handleInvalidate)();
  }
});

• 장점: 매직 넘버 제거. 실제 애니메이션 종료에 정확히 동기화.
• 단점: 모달 컴포넌트 자체를 재작성해야 한다. 단순 알림 모달엔 과한 투자.

현재 모달처럼 복잡한 UI라면 정당화되지만, 알림 한 줄짜리 모달에는 ROI가 떨어진다.

정리

이 패턴은 결국 "무거운 데이터 동기화와 UI 애니메이션을 같은 tick에 발사하지 않는다"는 원칙으로 요약된다. 그 원칙을 구현하는 방법의 비용 대비 효과는 대략 이렇다.

대부분의 경우 setTimeout + 상수 추출 + 의도 주석이 가장 합리적이다. 다음 사람이 코드를 안전하게 손댈 수 있을 만큼 의도를 드러내고, deprecated 의존 없이 동작하며, 변경 비용도 최소화된다. 캐시 구조가 단순하고 응답 페이로드에 갱신할 데이터가 모두 들어 있다면 그때 낙관적 업데이트로 한 단계 올리면 된다.

이 트러블슈팅에서 얻은 가장 큰 교훈은 "눈에 보이는 컴포넌트를 의심하기 전에, 그 컴포넌트가 등장하는 시점에 같이 일어나는 일을 의심하라" 였다. 모달이 끊기니까 모달 구현을 바꾸려고 했지만, 실제 원인은 모달과 무관한 위치의 invalidateQueries였다.

prefix 기반 invalidateQueries는 코드를 짧게 쓰게 해주지만, 그 prefix가 얼마나 많은 쿼리에 fan-out되는지 무심코 놓치기 쉽다. mutation 직후 같은 화면을 가리는 모달을 띄우는 패턴이라면, 항상 한 번 더 의심해볼 가치가 있다.

그리고 deprecated API를 추천하기 전에 node_modules의 타입 정의를 직접 열어보는 것도 의미가 있다. 메모리상 "있다고 알고 있는" API의 상태는 종종 현재의 상태와 다르다.

긴 리스트의 성능 문제는 결국 "화면에 보이지 않는 아이템까지 다 그리느냐"의 싸움이다. 세 라이브러리 모두 가상화(virtualization), 즉 보이는 영역 주변만 렌더링하는 방식으로 이 문제를 푼다. 다만 그 방식과 튜닝 노브가 서로 다르다.

이 글은 실무에서 실제로 손대게 되는 성능 관련 props 위주로, 세 가상화 리스트를 구별해 정리한 것이다.

1. 세 리스트에 공통으로 존재하는 성능 관여 props

FlashList와 LegendList는 둘 다 FlatList의 drop-in 대체제를 표방한다. 그래서 API 표면 대부분이 FlatList와 호환되고, 성능과 직결되는 다음 props는 세 라이브러리에 공통으로 존재한다.

keyExtractor — 셋 다 가장 중요한 성능 prop이다. 각 아이템에 안정적인 고유 키를 부여해, data가 바뀌어도 변경된 아이템만 갱신하고 나머지 레이아웃 정보는 재사용하게 한다. 인덱스를 키로 쓰면(재정렬·prepend 시) 리스트가 크게 깨지므로 반드시 데이터 고유값을 반환해야 한다. LegendList는 중복 키를 감지하면 경고를 띄울 정도로 이 부분을 중요하게 본다.

onEndReached / onEndReachedThreshold — 페이지네이션(무한 스크롤)의 기본이다. 데이터를 한 번에 다 들고 있지 않고 끝에 가까워질 때 나눠 불러오는 것 자체가 성능 전략이다. onEndReachedThreshold는 화면 크기 배수로 계산되므로, 0.5면 "끝에서 화면 절반 거리"에서 콜백이 발동한다.

numColumns / horizontal — 레이아웃 모드를 결정하는 공통 props이며, 컬럼 구성과 측정 방식에 영향을 준다.

다만 여기서부터가 핵심인데, "깊은 성능 튜닝 노브"는 세 라이브러리가 완전히 갈라진다. FlatList는 렌더링 윈도우를 개발자가 수동으로 조율하는 방식이고, FlashList와 LegendList는 그 수치 조율을 대부분 내부로 흡수하고 아이템 재활용(recycling)으로 접근한다. 아래에서 하나씩 구별한다.

1. FlatList (React Native 코어)

FlatList는 아이템을 재활용하지 않는다. 화면에 들어오면 마운트하고 나가면 언마운트하는 방식이라, 성능 튜닝이 "렌더링 윈도우를 얼마나 크게/촘촘하게 둘 것인가"의 수동 조율로 귀결된다. 그래서 props가 가장 많고 손이 많이 간다.

실무에서 만지는 핵심 props는 다음과 같다.

• windowSize (기본값 21) — 렌더링해 둘 영역의 크기다. 단위는 아이템 개수가 아니라 화면(viewport) 높이의 배수다. 기본 21은 "보이는 화면 1 + 위로 10 + 아래로 10"을 의미한다. 줄이면 메모리는 절약되지만 빠르게 스크롤할 때 빈 칸(blank area)이 보일 수 있다.
• maxToRenderPerBatch (기본값 10) — 한 배치(batch)에서 렌더링하는 아이템 수다. 키우면 스크롤 중 콘텐츠 채워지는 속도가 빨라지지만 한 번에 일을 많이 해서 프레임이 끊길 수 있다.
• initialNumToRender (기본값 10) — 첫 렌더에서 그릴 아이템 수다. 첫 화면을 꽉 채울 최소 개수로 맞추는 게 초기 로딩 체감에 좋다.
• updateCellsBatchingPeriod (기본값 50ms) — 배치 렌더링 사이의 간격(ms)이다. 늘리면 렌더 빈도가 줄어 부하가 분산되지만 빈 칸 노출 시간이 길어진다.
• removeClippedSubviews (Android 기본값 true, iOS 기본값 false) — 화면 밖 뷰를 네이티브 뷰 계층에서 떼어내는 옵션이다. 효과는 있지만 콘텐츠 사라짐·포커스 버그 위험이 있어 공식 문서가 "본인 책임하에 사용"을 권고한다. 특히 아이템에 TextInput·비디오·복잡한 중첩 뷰가 있으면 신중해야 한다.
• getItemLayout — 아이템 높이가 고정일 때 가장 강력한 최적화다. 각 아이템 위치를 동적 측정 없이 계산식으로 알려줘서, 측정 비용을 없애고 scrollToIndex도 정확해진다. 가변 높이라면 쓰기 어렵다.

정리하면 FlatList 튜닝은 windowSize / maxToRenderPerBatch / initialNumToRender 3종 세트를 데이터 특성에 맞게 맞추고, 고정 높이면 getItemLayout을 더하는 흐름이다.

2. FlashList v2 (@shopify/flash-list)

FlashList는 Shopify가 만든 고성능 리스트로, 아이템을 재활용(recycling)한다. 화면 밖으로 나간 컴포넌트를 버리지 않고 새 아이템에 재사용하는 방식이라 FlatList보다 빠르다.

여기서 중요한 건 v2가 완전 재작성판이라는 점이다. 실무 관점에서 v1과의 차이를 반드시 알아야 한다.

• New Architecture(신아키텍처)가 필수다. v2는 RN 신아키텍처 위에서만 동작한다. 구아키텍처 프로젝트라면 v2를 쓸 수 없다. (RN CLI 프로젝트라면 자신의 아키텍처 설정을 먼저 확인해야 한다.)
• estimatedItemSize가 사라졌다. v1의 가장 번거로운 점이 아이템 크기를 추정해 넘겨주는 것이었는데, v2는 신아키텍처의 동기 레이아웃 측정을 이용해 추정값 없이 크기를 알아서 계산한다. 즉 v1에서 쓰던 estimatedItemSize, estimatedListSize, estimatedFirstItemOffset, onBlankArea, disableAutoLayout 등은 제거되거나 더 이상 필요 없다.
• maintainVisibleContentPosition이 기본 활성화다. 위쪽에서 아이템이 추가·변경돼도 현재 보고 있는 콘텐츠가 튀지 않는다.
• masonry가 prop이 됐다. 별도 MasonryFlashList 컴포넌트는 deprecated 되고, <FlashList masonry numColumns={3} />처럼 prop으로 핀터레스트식 레이아웃을 쓴다. optimizeItemArrangement로 컬럼 높이 차이를 줄이는 옵션도 생겼다.
• inverted가 deprecated 됐다. 대신 maintainVisibleContentPosition로 채팅형 UI를 처리하는 방향이다.
• overrideItemLayout은 이제 span(컬럼 차지 수)만 지원한다. v1에서 가능했던 size 추정 지정은 빠졌다.
• drawDistance — 뷰포트 위아래로 미리 렌더링해 둘 버퍼(px)다. FlatList의 windowSize에 대응하는, FlashList의 미리 그리기 조절 노브다.
• ref 타입이 FlashList에서 FlashListRef로 바뀌었다.

실무 포인트는 명확하다. 신아키텍처만 쓴다면 FlashList v2는 추정값 입력이 사라져서 가장 손이 안 가는 선택지가 됐다. 반대로 아직 구아키텍처라면 v2는 후보에서 빠진다.

3. LegendList v2 (@legendapp/list)

LegendList는 Legend App(Jay Meistrich)이 만든 신생 리스트로, 가장 큰 특징은 100% 자바스크립트 구현이라 네이티브 코드 의존성이 없다는 점이다. 그래서 RN Web, macOS, Windows, TV 등 어떤 RN 플랫폼에서도 동작하고, 설치 후 네이티브 빌드 이슈가 적다. FlatList와 FlashList 양쪽 모두의 drop-in 대체제를 표방한다.

성능 관점에서 알아둘 props는 다음과 같다.

• recycleItems (기본값 false) — 이게 FlashList와의 결정적 차이다. LegendList는 재활용을 끄고 시작한다. 즉 기본 상태에서는 아이템마다 새 컴포넌트를 만들어서(덜 빠르지만) 내부 상태가 있는 아이템도 안전하다. 최고 성능을 원하면 명시적으로 recycleItems를 켜야 하는데, 그 경우 아이템에 로컬 state가 있으면 재사용 과정에서 엉뚱하게 섞일 수 있어 주의해야 한다. FlashList 동작과 똑같이 맞추려면 이 prop을 켜면 된다.
• drawDistance (기본값 250) — 뷰포트 위아래로 미리 그려둘 버퍼(px)다. 키우면 빠른 스크롤 시 빈 칸이 줄지만 메모리를 더 쓴다.
• estimatedItemSize / getEstimatedItemSize (선택) — 첫 프레임 레이아웃을 추정하는 힌트다. 안 줘도 동작하며(이후엔 실제 측정한 평균 크기를 사용한다), 안 주면 최적값을 로그로 제안해준다. FlashList v2처럼 "추정 없이도 됨" 방향으로 정리됐다.
• getFixedItemSize (v2) — 아이템 크기가 고정임을 알려주면 측정·갱신 오버헤드를 없애 최적 성능을 낸다. FlatList의 getItemLayout과 같은 발상이다.
• getItemType (v2) — 아이템 유형을 분류하면 같은 타입끼리 더 효율적으로 재활용된다. (FlashList에도 있는 개념이다.)
• maintainVisibleContentPosition (기본값 true) — 위쪽 아이템이 추가·변경·리사이즈돼도 보이는 콘텐츠가 안 튄다. 내부적으로 ScrollView의 동명 prop을 사용하므로, Android에서 쓰려면 RN 0.72 이상이 필요하다.
• alignItemsAtEnd / maintainScrollAtEnd — inverted 없이 채팅 UI를 만드는 props다. LegendList는 inverted를 쓰지 않고 콘텐츠를 하단 정렬해 양방향 무한 스크롤을 매끄럽게 처리하는 걸 강점으로 내세운다.
• initialContainerPoolRatio (기본값 2) — 미리 잡아두는 컨테이너 풀의 비율이다. 고정 크기 아이템이면 1에 가깝게, 크기 변동이 크면 더 키우는 식으로 조절한다. 풀이 부족하면 컨테이너를 추가 할당하며 재렌더가 일어나 프레임이 잠깐 끊길 수 있다.

4. 한눈에 비교

5. 실무 선택 가이드

• FlatList — 추가 의존성 없이 가야 하거나, 리스트가 짧고 단순하면 충분하다. 대신 길고 무거운 리스트에서는 windowSize·maxToRenderPerBatch·initialNumToRender를 직접 튜닝해야 하고, 고정 높이면 getItemLayout을 더한다. 안드에서 리스트가 잘리거나 안 보이면 removeClippedSubviews(안드 기본 true)부터 의심한다.
• FlashList v2 — 신아키텍처를 쓰고 있다면 가장 추천할 만하다. 추정값 입력이 사라져 손이 거의 안 가면서 재활용으로 빠르다. 단, 구아키텍처면 쓸 수 없다는 점이 결정적 제약이다.
• LegendList v2 — 네이티브 의존성을 피하고 싶거나(웹/멀티플랫폼), 가변 높이 아이템·채팅 UI가 핵심이거나, 구아키텍처라서 FlashList v2를 못 쓰는 상황에서 강하다. 단 최고 성능을 내려면 recycleItems를 직접 켜야 하고, 그 경우 아이템 내부 state 처리에 주의해야 한다.

공통 원칙은 하나다. 어떤 리스트를 쓰든 keyExtractor를 제대로 주고, 아이템 컴포넌트를 React.memo 등으로 가볍게 유지하는 것이 모든 튜닝 노브보다 먼저다. 가상화 라이브러리는 "안 보이는 걸 안 그리게" 도와줄 뿐, 보이는 아이템 하나하나가 무거우면 어떤 리스트도 느려진다.

최적화는 어디서 시간이 쓰이는지 분해하는 데서 시작한다. 콜드 스타트는 크게 다음 구간으로 나뉜다.

1. 프로세스 생성 + 네이티브 초기화 — OS가 앱 프로세스를 띄우고 네이티브 런타임이 올라오는 구간이다. 앱이 직접 줄이기 가장 어렵지만, 링킹 방식이나 시작 시점 SDK 초기화로 늘어날 수는 있다.
2. JS 엔진 초기화 + 번들 로드/평가 — Hermes가 바이트코드를 로드하고 JS 번들을 평가하는 구간이다. 번들 크기와 top-level 실행 코드가 직접 영향을 준다.
3. 첫 렌더(TTI까지) — 루트 컴포넌트가 마운트되고 첫 화면이 인터랙션 가능해지는 구간이다.
4. 데이터 페치 + 화면 완성 — API 응답을 받아 실제 콘텐츠가 채워지는 구간이다.

전략은 "이 구간을 실제로 줄인다(actual)"와 "이 구간을 느리게 느끼지 않게 한다(perceived)" 두 축으로 나눠서 본다.

기준 버전: 이 글은 React Native 0.84 이상을 기준으로 한다. 0.82부터 Legacy Architecture는 더 이상 지원되지 않고, 0.84부터 Hermes V1이 기본 엔진이다.

1. 빌드/번들 레벨 최적화 (actual)

1) Hermes는 선택이 아니라 전제다

New Architecture에서는 Hermes가 사실상 유일한 선택지다. JSC는 0.80에서 코어 밖으로 분리되어 @react-native-community/javascriptcore 별도 패키지가 됐다. Hermes는 릴리즈 빌드에서 JS를 AOT로 바이트코드까지 컴파일해 두기 때문에, 런타임에 파싱·컴파일하는 비용이 사라지고 바이트코드는 필요한 시점에 온디맨드로 메모리에 올라간다.

0.84부터는 Hermes V1이 기본값이다. 이전 버전에서 올라온 프로젝트라면 opt-out 플래그(RCT_HERMES_V1_ENABLED=0, hermesV1Enabled=false)가 남아 있지 않은지 확인한다.

2) 번들 크기를 직접 줄인다

JS 번들 평가는 콜드 스타트의 큰 축이다. 번들이 작을수록 로드·평가가 빠르다.

• 소스맵 기반 번들 분석을 돌려 무엇이 번들을 차지하는지 본다. react-native-bundle-visualizer, 또는 --sourcemap-output으로 뽑은 소스맵을 source-map-explorer에 물려 거대한 의존성을 찾아낸다.
• moment.js → day.js, lodash 전체 import → lodash/get 식 개별 import로 무거운 라이브러리를 교체하거나 좁힌다. Metro는 기본적으로 트리셰이킹을 하지 않으므로, "번들러가 알아서 털어주겠지"를 전제하면 안 된다.
• 아이콘 폰트, JSON 사전 데이터, base64 인라인 이미지처럼 번들에 박혀 있는 큰 정적 리소스를 에셋으로 분리한다.

3) Inline Requires — 이미 켜져 있는지부터 확인한다

Metro의 inline requires는 모듈을 top-level에서 한 번에 평가하지 않고 실제로 호출되는 시점에 평가한다. 콜드 스타트 시점에 평가할 코드량이 줄어 TTI가 빨라진다.

다만 React Native CLI 프로젝트에서는 이미 기본 활성화되어 있다. require() 호출은 내 코드와 node_modules 양쪽에서 자동으로 인라인된다. 그러니 "켜자"가 아니라 "꺼져 있지 않은지 확인하자"가 맞다. (Expo는 기본 비활성이라 별도 설정이 필요하다.)

주의할 점은 ESM import 문은 자동 인라인 대상이 아니라는 것이다. import까지 인라인하려면 experimentalImportSupport를 함께 켜야 하고, 이건 모듈 평가 순서를 바꿀 수 있어 부수효과에 의존하는 코드에서 문제가 될 수 있다. 켜면 반드시 실기기에서 전체 회귀 테스트를 돌린다.

// metro.config.js
transformer: {
  getTransformOptions: async () => ({
    transform: {
      inlineRequires: true,
      experimentalImportSupport: true, // 도입 시 회귀 테스트 필수
    },
  }),
},

RAM 번들(indexedRamBundle)은 Hermes와 함께 쓸 수 없다. Hermes 바이트코드가 RAM 번들 포맷과 호환되지 않고, 애초에 Hermes가 같거나 더 나은 온디맨드 로딩을 제공한다. 오래된 최적화 글에서 자주 보이는 항목이니 그대로 따라 하지 않는다.

4) Android: R8, 앱 크기, Baseline Profile

• 릴리즈 빌드에서 R8(코드 축소·난독화)을 켜서 DEX 크기를 줄인다. 다만 이건 주로 앱 크기 최적화이고 콜드 스타트 개선폭은 제한적이다. 기대치를 정확히 잡는다.
• App Bundle(AAB)로 배포하면 Play가 ABI/밀도별로 알아서 분리해 준다. AAB를 쓰면서 enableSeparateBuildPerCPUArchitecture를 같이 켤 필요는 없다. APK 직접 배포일 때만 의미가 있다.
• Baseline Profile을 넣으면 첫 실행부터 핫패스가 AOT 컴파일되어 있어 초기 실행 구간에서 실질적인 이득이 있다. 앱 크기 최적화보다 콜드 스타트에는 이쪽이 효과가 크다.

5) iOS: 링킹 방식과 프레임워크 수

• use_frameworks! :linkage => :dynamic은 dyld가 로드해야 할 동적 프레임워크 수를 늘려 앱 시작 시간을 직접적으로 늘린다. 가능하면 static linkage를 쓴다.
• 0.84부터 React Native 코어는 프리컴파일된 .xcframework로 내려받는다. 이건 빌드 시간 개선이지 런타임 시작 시간 개선이 아니다. 혼동하지 않는다.

6) 불필요한 네이티브 모듈/SDK 제거

서드파티 SDK(분석, 광고, 푸시 등)는 앱 시작 시 자체 초기화 코드를 돌리는 경우가 많다. New Architecture의 TurboModule은 lazy init(처음 호출될 때 로드)이 기본 이점이지만, 라이브러리가 AppDelegate/Application.onCreate에서 강제 초기화하면 그 이점이 사라진다. 시작 시점에 꼭 필요하지 않은 SDK 초기화는 첫 화면 렌더 이후로 미룬다.

2. JS 실행 레벨 최적화

1) 진입 코드를 가볍게 한다

index.js와 루트 컴포넌트의 top-level에서 무거운 연산, 동기 스토리지 접근, 거대한 객체 생성을 하지 않는다. 여기서 하는 일은 전부 첫 렌더를 늦춘다. 특히 모듈 top-level의 부수효과(전역 인스턴스 생성, 리스너 등록)는 inline requires로도 피할 수 없는 경우가 많으니 함수 안으로 옮긴다.

2) 화면 단위 지연 로딩 — 무엇이 줄어드는지 정확히 알기

초기 진입에 필요 없는 화면·기능은 React.lazy + 동적 import()로 분리한다. 설정 화면, 결제 플로우, 무거운 차트 라이브러리가 대표적이다.

여기서 오해가 잦다. Metro는 기본적으로 코드 스플리팅을 하지 않는다. 동적 import()도 결국 같은 번들 안에 들어가므로, 줄어드는 건 다운로드/번들 크기가 아니라 콜드 스타트 시점의 평가 비용이다. 그것만으로도 TTI에는 충분히 의미가 있지만, "번들이 작아진다"고 기대하면 측정 결과와 어긋난다.

3) 무거운 작업은 첫 렌더 이후로

비핵심 초기화(로그 전송, 캐시 워밍, 백그라운드 동기화)를 첫 렌더 뒤로 미뤄 메인/JS 스레드를 비워 준다.

• React 19 기준으로는 startTransition, useDeferredValue가 우선 선택지다. Fabric의 우선순위 기반 렌더와 자연스럽게 맞물린다.
• InteractionManager.runAfterInteractions()는 여전히 동작하지만 애니메이션 핸들 기반이라 동시성 렌더와 항상 잘 맞지는 않는다. 화면 진입 애니메이션 이후로 미루는 용도로 한정해서 쓴다.

4) 폰트/리소스 비동기화

커스텀 폰트, 대형 에셋 로딩이 첫 렌더를 블록하지 않게 한다. 폰트가 로드되기 전에는 시스템 폰트로 렌더하고 로드 후 교체하는 식으로 진입을 막지 않는다. 단, 폰트 교체로 레이아웃이 크게 흔들린다면 메트릭이 비슷한 폴백 폰트를 지정해 시프트를 줄인다.

3. 스플래시 & 게이트 전략

1) 네이티브 스플래시로 빈 화면을 덮는다

JS 번들 로드·Hermes 초기화·첫 렌더까지의 구간은 사용자에게 흰 화면/검은 화면으로 보일 수 있다. react-native-bootsplash 같은 네이티브 스플래시로 이 구간을 자연스럽게 덮는다. 네이티브에서 즉시 뜨므로 JS가 준비되기 전부터 보인다. Android 12 이상에서는 시스템 SplashScreen API를 거치게 되어 있으므로, 자체 스플래시 액티비티를 따로 두면 스플래시가 두 번 보이는 문제가 생긴다.

2) 스플래시 종료 기준: "주요 API만"

홈의 모든 API를 기다리면 스플래시 종료가 가장 느린 요청·최악의 네트워크에 인질로 잡히고, 부가 API 하나의 실패/지연이 전체 진입을 막는 단일 실패점이 된다.

따라서 기준은 첫 화면 above-the-fold를 의미 있게 그리는 주요 API까지로 잡는다. 단, 반드시 아래 세트와 함께 쓴다.

• 타임아웃 가드: 주요 API에도 상한(예: 3~5초)을 둔다. 초과 시 캐시 데이터/에러·리트라이 화면으로 폴백해 스플래시 무한 대기를 막는다.
• 스켈레톤 UI: 부가 영역은 스플래시가 아니라 홈 화면 안에서 스켈레톤으로 로딩한다.
• 폴백 화면: 주요 API 실패 시 빈 홈이 아니라 명확한 재시도 UI를 보여준다.

const gate = Promise.race([
  fetchCriticalHomeData(),
  new Promise((_, reject) => setTimeout(() => reject(new TimeoutError()), 4000)),
]);

try {
  await gate;
} catch {
  // 캐시 렌더 또는 재시도 화면으로 폴백
} finally {
  await BootSplash.hide({ fade: true }); // 어떤 경로로든 반드시 내린다
}

예외는 금융 잔액 화면처럼 부분 렌더가 오정보로 오인될 수 있는 도메인뿐이다. 이때만 "전체 대기"가 정당하다.

3) 스플래시 시간을 페치 시간으로 쓴다

네이티브 스플래시가 떠 있는 동안, JS가 준비되는 즉시 주요 API를 prefetch한다. 스플래시 표시 시간과 네트워크 대기 시간을 겹쳐서, 사용자 입장에서 "기다리는 시간"을 하나로 합친다. 인증 토큰이 이미 로컬에 있다면 네비게이션 트리 마운트를 기다리지 말고 앱 진입 최상단에서 요청을 띄운다.

4. 데이터/네트워크 전략 (actual + perceived)

1) 캐시 우선 + Stale-While-Revalidate

TanStack Query, SWR, 또는 직접 구현으로 캐시된 데이터를 먼저 즉시 그린 뒤 백그라운드에서 갱신한다. 두 번째 이후 진입에서는 네트워크를 기다리지 않고 바로 화면이 채워지므로 체감 속도가 크게 좋아진다.

2) 영속 캐시로 "두 번째 콜드 스타트"를 빠르게

MMKV나 AsyncStorage에 마지막 데이터를 영속화해 둔다. 콜드 스타트여도 직전 세션의 데이터를 즉시 렌더하고 뒤에서 갱신하면, 실제 콜드 스타트인데도 웜 스타트처럼 느껴진다.

MMKV는 JSI 기반 동기 접근이라 진입 경로에서 await 왕복이 없다는 게 핵심 이점이다. 다만 v3부터는 New Architecture(Nitro Modules)를 전제로 하므로 버전과 아키텍처 대응 여부를 함께 확인한다. 반대로 캐시 복원 데이터가 크면 동기 파싱 비용이 그대로 첫 렌더를 막으므로, 화면에 당장 필요한 조각만 복원한다.

3) 요청 합치기(BFF/aggregation)

홈 진입에 5개 API가 따로 나간다면, 가능하면 서버에서 하나의 엔드포인트로 합쳐 받는다. 라운드트립 수와 워터폴이 줄어 주요 데이터 도착이 빨라진다. 서버 변경이 어렵다면 클라이언트에서 병렬(Promise.all)로 묶되, 주요/부가를 분리해 주요만 게이트로 둔다.

4) 워터폴 제거

"인증 → 프로필 → 홈 데이터"처럼 순차 의존이 길면 그만큼 진입이 늦다. 의존 없는 요청은 병렬화하고, 토큰 검증과 데이터 페치를 가능한 한 겹친다. 토큰 갱신이 필요한 경우에도 만료 전 선제 갱신으로 진입 경로에서 왕복이 추가되지 않게 한다.

5. 체감 성능(Perceived Performance) UX

실제 시간을 더 못 줄이는 구간에서 가장 비용 대비 효과가 큰 영역이다.

1) 스켈레톤 > 스피너

빈 화면에 스피너만 도는 것보다, 최종 레이아웃과 비슷한 스켈레톤을 보여주는 쪽이 더 빠르게 느껴지고 레이아웃 시프트도 줄인다. 사용자는 "곧 무엇이 어디에 올지" 예측하게 된다. 단, 스켈레톤과 실제 콘텐츠의 높이가 다르면 오히려 시프트가 커지므로 치수를 맞춘다.

2) 점진적 렌더 / 골든 패스 우선

화면 전체를 한 번에 채우려 하지 말고, 사용자가 가장 먼저 보는 영역부터 채운다. above-the-fold(헤더, 첫 카드)를 먼저 그리고, 아래쪽·개인화·추천은 뒤따라 채운다. React 19의 Suspense 경계를 영역 단위로 나눠 두면 이 구조를 그대로 표현할 수 있다.

3) 첫 화면은 리스트 가상화로

홈이 긴 리스트라면 가상화 리스트로 화면에 보이는 만큼만 렌더한다. 초기 렌더 비용이 줄어 TTI가 빨라진다. FlatList를 쓴다면 initialNumToRender를 첫 화면에 실제로 보이는 개수로 맞춘다(기본 10은 대개 과하다). New Architecture 전용으로 다시 쓰인 FlashList v2도 선택지이며, 이 경우 estimatedItemSize 같은 수동 튜닝 없이 동작한다.

4) 애니메이션으로 전환을 부드럽게

스플래시 → 홈 전환을 페이드/스케일로 부드럽게 처리하면, 동일한 시간이라도 끊김 없이 빠른 느낌을 준다. 단, 전환 애니메이션이 길어 실제 진입을 늦추지 않게 짧게(200~300ms) 둔다.

6. 측정 없이는 최적화도 없다

추측으로 최적화하지 않는다. 진입 경로를 계측한다.

• TTI(Time To Interactive) 를 직접 마킹한다. 앱 시작 시점부터 첫 화면이 인터랙션 가능해질 때까지를 측정한다. RN에 들어온 Web Performance API(performance.now(), PerformanceObserver, mark/measure)나 react-native-performance를 쓰면 JS 구간을 표준 방식으로 남길 수 있다.
• 네이티브 측 콜드 스타트 시간(Android reportFullyDrawn 및 Play Console의 시작 시간 지표, iOS Instruments App Launch / MetricKit)과 JS 측 마커를 함께 본다. 한쪽만 보면 원인 구간을 잘못 짚는다.
• Firebase Performance, Sentry, 또는 자체 로깅으로 실사용자(RUM) p50/p95/p99 를 본다. p50만 보면 꼬리 지연을 놓친다.
• 반드시 릴리즈 빌드에서 측정한다. 디버그 빌드는 Hermes 바이트코드 AOT 이점이 없고 Metro가 붙어 있어 숫자가 무의미하다.
• 최적화 전후를 같은 디바이스·같은 네트워크 조건에서 비교한다. 저사양 단말과 느린 네트워크를 반드시 포함한다.
• 첫 설치 직후 실행과 재실행을 구분해서 본다. Baseline Profile이나 캐시 효과 때문에 둘의 숫자가 크게 다르다.

7. 우선순위 체크리스트

비용 대비 효과 순으로 정리하면 대략 다음과 같다.

1. 릴리즈 빌드 기준으로 TTI·RUM 계측을 먼저 붙인다. 기준선 없이 시작하지 않는다.
2. Hermes(V1)가 켜져 있는지, inline requires가 꺼져 있지 않은지 확인한다.
3. 네이티브 스플래시 + "주요 API만 게이트 + 타임아웃 + 스켈레톤" 조합을 적용한다.
4. 캐시 우선(SWR) + 영속 캐시(MMKV)로 재진입을 웜 스타트처럼 만든다.
5. 진입 경로의 워터폴을 병렬화하고, 가능하면 주요 API를 하나로 합친다.
6. 비핵심 SDK·초기화를 첫 렌더 이후로 미룬다.
7. 화면 단위 lazy import로 콜드 스타트 시점의 평가량을 줄인다.
8. 번들 분석으로 무거운 의존성을 교체·분리한다.
9. Android Baseline Profile, iOS static linkage 등 플랫폼별 항목을 정리한다.

핵심 원칙은 하나다. 줄일 수 있는 시간은 실제로 줄이고(actual), 줄이기 어려운 시간은 느려 보이지 않게 만든다(perceived). 콜드 스타트 UX는 이 둘의 합이다.

물리적 iOS 기기에서 앱이 실행된 직후 Metro 번들러와의 연결이 끊어지는 현상은 기기가 Mac에서 실행 중인 Metro 서버(기본 포트 8081)와 통신하지 못할 때 발생한다.

시뮬레이터와 달리 물리적 기기는 USB 연결만으로는 디버그 서버와 통신할 수 없으며, 로컬 네트워크(Wi-Fi)를 통한 접근이 필요하다. 원인을 차근차근 파악해보자.

1. 동일한 Wi-Fi 네트워크 접속 확인

Mac과 iOS 기기가 정확히 동일한 Wi-Fi 네트워크에 연결되어 있어야한다. 네트워크 분리 기능이 활성화된 환경에서는 기기가 Mac의 로컬 IP를 찾을 수 없어 연결이 즉시 끊어진다.

2. iOS 로컬 네트워크 권한 활성화

iOS 14 이상 버전은 앱이 로컬 네트워크에 접근할 때 명시적인 권한을 요구한다. 권한이 거부된 상태라면 앱이 실행되더라도 Metro와의 통신이 차단된다.

• iOS 기기에서 설정 > 개인정보 보호 및 보안 > 로컬 네트워크로 이동한다.
• 개발 중인 앱의 항목을 찾아 스위치를 켜서(활성화) 통신을 허용한다.

3. 번들러 IP 주소 수동 지정

앱이 Mac의 IP 주소를 자동으로 인식하지 못하는 경우가 있다. 이 경우 개발자 메뉴에서 IP를 직접 지정해야 한다.

• Mac의 터미널에서 네트워크 설정(ifconfig 또는 시스템 설정)을 확인하여 Mac의 로컬 IP 주소(예: 192.168.x.x)를 기록한다.
• iOS 기기를 흔들어(Shake) React Native 개발자 메뉴(Developer Menu)를 호출한다.
• Configure Bundler를 선택한다.
• 기록한 Mac의 IP 주소와 포트를 입력한다. (입력 예시: 192.168.0.15:8081)
• 설정을 저장하고 앱을 다시 로드한다.

4. Metro 캐시 초기화 및 재빌드

기존의 잘못된 연결 정보나 캐시가 남아있어 연결을 방해할 수 있다.

• 실행 중인 Metro 터미널 프로세스를 모두 종료한다.
• 터미널에서 pnpm start --reset-cache 명령어를 실행하여 캐시를 초기화한 상태로 Metro를 시작한다.
• iOS 기기에서 실행 중인 앱을 스와이프하여 완전히 강제 종료한다.
• 새 터미널 탭을 열고 pnpm ios를 다시 실행하여 빌드 및 기기 연결을 다시 시도한다.

핵심 전제부터 짚는다. React Compiler는 위반을 만나면 빌드를 실패시키지 않고 해당 함수를 그대로 둔다. 즉 "skip"은 에러가 아니라 안전 후퇴(silent bailout)다. RC는 Rules of React 위반을 정적으로 감지하면, 그 컴포넌트/훅만 최적화에서 안전하게 제외하고 나머지는 계속 컴파일한다. 100% 최적화는 목표가 아니다.

문제는 이 후퇴가 명시적 신호 없이 일어난다는 점이다. 어떤 컴포넌트가 skip됐는지 모르고 지나갈 수 있다. 그래서 "무엇이 skip을 유발하는가"라는 패턴 카탈로그와, "skip됐는지 어떻게 확인하는가"라는 검증 도구를 함께 다뤄야 한다.

2. skip이 일어나는 메커니즘

1) panicThreshold 옵션

RC는 Rules of React 위반을 만났을 때의 처리 정책을 panicThreshold로 제어한다. 값은 'none' | 'critical_errors' | 'all_errors' 세 가지이며, 'none'이 기본값이자 공식 권장값이다.

['babel-plugin-react-compiler', {
  panicThreshold: 'none', // 기본값. 명시하지 않아도 동일하게 동작한다.
}]

'none'은 "위반 함수만 미컴파일 상태로 두고 나머지는 계속 컴파일"을 의미한다. 즉 "skip"의 정체가 곧 이 옵션의 기본 동작이다.

2) compilationMode 옵션과의 관계

대상 함수 자체의 선정은 compilationMode가 결정한다. skip 정책(panicThreshold)은 그 후에 작동한다. 기본값은 'infer'다.

주의: 'syntax'는 JSX 유무로 거르는 모드가 아니라 Flow 전용 문법을 대상으로 하는 모드다. TS/RN CLI 프로젝트라면 보통 기본값 'infer'를 그대로 둔다.

이 글이 다루는 케이스는 대상이지만 위반으로 skip 되는 상황이다.

3. skip을 유발하는 패턴 카탈로그

공식 Rules of React를 기준으로 정리한다. 모두 RC 분석을 막는 사유이고, eslint-plugin-react-hooks recommended preset이 빌드 전에 잡아낼 수 있는 항목이기도 하다.

1) Components and Hooks Must Be Pure

가장 빈번한 위반 카테고리이다. 기본적인 규칙이므로 잘 기억하자.

a. 렌더 중 props 변이

// ❌ skip 유발 — props는 immutable
const ListItem = ({ item }: { item: Item }) => {
  item.viewed = true;
  return <Text>{item.title}</Text>;
};

b. 렌더 중 state 변이

// ❌ skip 유발 — useState로 받은 객체를 직접 mutate
const Form = () => {
  const [data] = useState({ name: 'A' });
  data.name = 'B'; // setState 없이 mutate
  return <Text>{data.name}</Text>;
};

c. JSX에 넘긴 값을 그 뒤에 변이

// ❌ skip 유발 — JSX에 들어간 객체는 더 이상 mutate 금지
const View = () => {
  const data = { name: 'A' };
  const node = <Display data={data} />;
  data.name = 'B';
  return node;
};

d. 렌더 중 ref 읽기/쓰기

// ❌ skip 유발 — .current는 effect/이벤트 핸들러 안에서만
const View = () => {
  const ref = useRef(0);
  ref.current += 1;
  return <Text>{ref.current}</Text>;
};

e. 렌더 중 전역 변이

// ❌ skip 유발 — 모듈 스코프 변수에 대한 할당/변이
let counter = 0;

const Counter = () => {
  counter += 1;
  return <Text>{counter}</Text>;
};

f. 컴포넌트가 idempotent하지 않음

같은 입력에 같은 출력을 보장해야 한다. 렌더 출력이 매번 바뀌는 호출(Date.now(), Math.random() 등)을 렌더 중에 직접 쓰는 패턴은 메모이제이션 가정과 충돌한다. ESLint 규칙 purity가 알려진 비순수 함수 호출을 잡는다.

2) Rules of Hooks

a. 조건/루프/조기 반환 뒤에서 hook 호출

// ❌ skip 유발 — early return 뒤 hook
const Card = ({ enabled }: Props) => {
  if (!enabled) return null;
  const [v] = useState(0);
  return <Text>{v}</Text>;
};

// ❌ skip 유발 — 조건 안에서 hook
const Card = ({ enabled }: Props) => {
  if (enabled) {
    const [v] = useState(0);
  }
  return null;
};

b. 일반 함수에서 hook 호출

// ❌ skip 유발 — 이벤트 핸들러/일반 함수에서 hook 호출
const handler = () => {
  const v = useSomething();
};

c. use로 시작하지 않는 함수에서 hook 호출

훅 명명 규칙(use*)을 어기면 ESLint 규칙 rules-of-hooks가 잡고, RC도 hook으로 인식하지 못한다.

3) React Calls Components and Hooks

a. 컴포넌트를 일반 함수로 직접 호출

// ❌ skip 유발 — JSX가 아닌 직접 호출
const Page = () => {
  return <View>{Header({ title: 'x' })}</View>;
};

컴포넌트는 항상 <Header title="x" /> 형태로 사용해야 한다.

b. hook을 값으로 전달/저장

// ❌ skip 유발 — hook을 일반 값처럼 다룸
const run = (hook: () => number) => hook();
const Comp = () => run(useCounter);

4) RC가 호환하지 못하는 라이브러리 사용

특정 라이브러리는 내부 패턴이 RC의 메모이제이션 가정과 양립하지 않는다. ESLint 규칙 incompatible-library가 이를 식별한다(구체 목록은 버전마다 달라지므로 lint 결과로 확인). 단, 이 규칙은 기본 심각도가 warn이라 빌드를 막지는 않고 경고만 띄운다(4장 표 참조).

4. 사전 차단 — ESLint 규칙

RC의 진단은 빌드 타임에 조용히 skip되지만, eslint-plugin-react-hooks recommended preset은 이 위반들을 개발 중에 표면화시킨다. 아래는 공식 recommended preset에 포함된 규칙 전체와, 그 기본 심각도다. 대부분 error지만 세 개(exhaustive-deps, unsupported-syntax, incompatible-library)는 warn이라는 점이 실무적으로 중요하다 — 이 셋은 위반이 있어도 빌드를 막지 않고 경고만 낸다.

이 규칙들은 RC를 아직 도입하지 않은 상태에서도 켤 수 있다. RC 도입 직전 사전 정리 단계에서 가장 가성비가 좋다. 위반이 있는 코드 위에 RC를 켜봐야 skip만 늘어나기 때문이다.

5. "use no memo" 디렉티브 — 디버깅 도구

특정 컴포넌트가 RC와 함께 두면 동작이 깨지거나 의심스러울 때, 한시적으로 RC를 끄고 원인을 격리한다.

const Suspicious = () => {
  'use no memo'; // 이 함수만 컴파일 제외
  // ...
};

배치 규칙 (공식 문서 기준):

• 함수 본문 첫 줄 — 해당 함수만 컴파일 제외. (디렉티브는 import나 다른 코드보다 앞, 본문 맨 앞에 와야 하며 주석은 허용. 백틱이 아닌 따옴표로 작성.)
• 파일 최상단 — 그 파일의 모든 함수를 컴파일 제외(모듈 레벨).
• 함수 레벨이 모듈 레벨을 덮어쓴다. 그리고 이 디렉티브는 모든 compilationMode보다 우선한다('all' 모드에서도 해당 함수는 제외).

용도:

• 이슈 격리 — "use no memo"를 붙여 문제가 사라지면 → 해당 컴포넌트에 Rules of React 위반이 있다는 신호.
• 영구 사용 금지. 근본 위반을 고친 뒤 디렉티브를 제거하고 Memo ✨ 배지로 확인하는 것이 정상 흐름이다.

반대 디렉티브 "use memo" 는 compilationMode: 'annotation'에서 명시적으로 컴파일을 켜거나, 'infer' 모드의 추정을 강제로 덮어쓸 때 사용한다(점진 도입 시).

6. 사후 확인 — Memo ✨ 배지

React Native DevTools의 Component Inspector에서 컴포넌트 옆에 Memo ✨ 배지가 보이면 RC가 컴파일한 컴포넌트다. 배지가 없으면 skip된 것.

확인 흐름:

1. ESLint 진단을 모두 통과시킨다(특히 error 규칙. warn 항목도 RC 최적화를 막을 수 있으니 함께 점검).
2. 앱을 띄우고 DevTools로 화면 진입.
3. 의도한 컴포넌트에 배지가 붙었는지 확인.
4. 배지가 없는 컴포넌트는 3장 카탈로그 항목과 lint 결과를 다시 본다.

핵심 화면 — 리스트 renderItem, BottomSheet, 무거운 진입 화면 — 만큼은 배지 확인을 PR 체크리스트에 넣는 게 안전하다. RC가 자동으로 깔아주는 메모이제이션은 분석을 통과한 컴포넌트에서만 작동하기 때문이다.

한 줄 요약

RC의 skip은 에러가 아닌 조용한 안전 후퇴다(panicThreshold의 기본값이자 권장값인 'none'의 동작). 트리거는 본질적으로 Rules of React 위반 — 렌더 중 props/state/ref/전역 변이, 조건부 hook 호출, 컴포넌트를 일반 함수처럼 호출, hook을 값으로 전달 등. eslint-plugin-react-hooks recommended preset으로 빌드 전에 막고(단 exhaustive-deps·unsupported-syntax·incompatible-library는 warn), "use no memo" 로 격리 디버깅하고, DevTools Memo ✨ 배지로 사후 확인하는 3단 검증이 표준 운영 방식이다.

RC를 도입했을 때 수동 메모이제이션이 불필요해지는 라이브러리·기능들을 정리해보자. 결론부터 말하자면 본질은 모두 같다. RC가 인라인 객체·함수·배열을 표현식 단위로 자동 캐시하므로, 그 위에 손으로 깔던 useMemo / useCallback / React.memo가 의미를 잃는다. 그렇다면, 기존에 바텀시트 & 가상화 리스트 등 UI에 불필요한 애니메이션 재등록, 리렌더링을 막기 위해, 최적화를 위해 메모이제이션을 적용했는데, 이것들도 그럼 수동으로 지정하는 것이 필요가 없어지는지 살펴보자.

1. Reanimated worklet 재등록 문제와 메모이제이션

가장 중요한 논제이다. Reanimated의 worklet은 UI 스레드에서 도는 함수인데, 컴포넌트가 리렌더될 때마다 worklet이 새로 만들어지면, 그 worklet은 매 렌더마다 다시 등록(re-register)된다. 참조가 불안정하면 불필요한 재등록이 계속 쌓이고, 특히 리스트처럼 같은 컴포넌트가 수십 개 깔리는 화면에서 비용이 증폭된다.

1) 왜 재등록이 문제인가

worklet이나 제스처 객체는 "한 번 등록해두고 그 등록된 객체를 재사용"하는 것이 이상적이다. 그런데 매 렌더마다 새 함수/새 객체가 생기면, Reanimated/Gesture Handler 입장에서는 "새로운 것"으로 보여 다시 등록 및 재부착한다. 화면이 가벼우면 무시할 수 있지만, FlatList 아이템처럼 다수가 동시에 존재하면 누적 비용이 체감된다.

2) 참조 안정성을 보장해 해결하기

해법은 앞선 메모이제이션 논의와 정확히 같다. worklet/제스처의 참조를 고정하면, 캡처한 값이 실제로 바뀔 때만 재등록된다. 공식 Performance 가이드가 명시하는 두 지점은 다음과 같다.

1. useFrameCallback — 콜백을 useCallback으로 감싼다.

useFrameCallback(
  useCallback(
    () => {
      'worklet';
      // ...
    },
    [
      /* deps */
    ],
  ),
);

이렇게 하면 프레임 콜백이 매 렌더마다 재생성·재등록되지 않는다.

2. Gesture 객체 — useMemo로 감싼다.

const pan = useMemo(
  () =>
    Gesture.Pan()
      .onStart(() => {})
      .onEnd(() => {}),
  [
    /* deps */
  ],
);

제스처가 매 렌더마다 다시 부착되는 것을 막는다. 공식 문서는 이 처리가 FlatList 아이템에서 특히 중요하다고 못 박는다.

핵심은 의존성 배열을 정확히 채우는 것이다. deps가 비어 있으면 값이 바뀌어도 worklet이 갱신되지 않고(스테일), deps가 과하면 불필요한 재등록이 돌아온다. "캡처하는 값이 바뀔 때만 재등록"이 목표다.

3) React Compiler를 켜면 이게 자동화된다

여기가 React Compiler와 Reanimated가 만나는 지점이다. 공식 Performance 가이드는 두 항목 모두에 대해 다음을 명시한다.

• "React Compiler를 사용 중이라면, 프레임 콜백은 자동으로 메모이제이션된다."
• "React Compiler를 사용 중이라면, 제스처 객체는 자동으로 메모이제이션된다."

즉 위의 useCallback/useMemo를 손으로 깔던 일을 컴파일러가 대신 해준다. 단, 컴파일러가 해당 컴포넌트를 분석·최적화할 수 있을 때의 이야기다. 분석 불가로 건너뛴 컴포넌트라면 자동 메모이제이션이 적용되지 않으므로, 그런 경우엔 수동 useCallback/useMemo가 여전히 필요하다. (DevTools의 Memo ✨ 배지로 확인할 것.)

4) shared value는 .value 대신 get() / set() 을 사용

React Compiler를 켤 때 Reanimated에서 반드시 지켜야 하는 규칙이 있다. 공식 useSharedValue 문서가 직접 명시한다.

React Compiler와 함께 쓸 때는 value 속성을 직접 읽거나 쓰지 말고, get/set 메서드를 사용하라. 이것이 React Compiler 표준에 부합하는 대체 API다.

const sv = useSharedValue(100);

// ✅ .value 대신 get()
const animatedStyle = useAnimatedStyle(() => ({ width: sv.get() * 100 });

const handlePress = () => {
  sv.set(v => v + 1); // ✅ .value = ... 대신 set()
};

이유는 명확하다. shared value의 읽기/쓰기는 외부 가변 저장소에 대한 부수효과(side effect)다. .value에 대한 단순 속성 접근을 컴파일러의 정적 분석이 잘못 해석하면 메모이제이션이 어긋날 수 있다. get()/set()은 이를 함수 호출로 명시해 컴파일러가 안전하게 다루도록 한다.

5) useAnimatedStyle / useDerivedValue는 별개

흔한 오해 하나를 정리한다. useAnimatedStyle이나 useDerivedValue에 넘기는 worklet은 useCallback으로 감쌀 대상이 아니다. 이 훅들은 Reanimated Babel 플러그인이 worklet으로 자동 변환(workletize)하고, 훅 내부에서 의존성 추적과 매퍼 등록을 관리한다. 따라서 위 2)에서 말한 "수동 재등록 방지(useCallback/useMemo)"가 직접 필요한 대상은 useFrameCallback의 콜백과 Gesture 객체다. 모든 worklet을 일률적으로 useCallback으로 감싸야 한다고 오해하지 말 것.

6) 렌더 중에 shared value를 읽거나 쓰지 않는다

마지막 규칙. 컴포넌트 렌더 중에 sv.value(또는 get/set)에 접근하지 않는다. 렌더 중 접근은 부수효과이고 Rules of React 위반이다. 읽기/쓰기는 렌더 중 실행되지 않는 콜백 — useAnimatedStyle, useEffect, 이벤트 핸들러 등 — 안에서만 해야 한다.

또한 JS 스레드에서 sv.value를 읽는 것 자체를 피하라는 가이드도 있다. JS 스레드에서 값을 읽으면 UI 스레드와 동기화될 때까지 JS 스레드가 블록되며, UI 스레드가 바쁘거나 반복 읽기가 있으면 그 대기 시간이 무시 못 할 수준이 될 수 있다. 값 읽기는 worklet 내부(UI 스레드)에서 하는 것이 원칙이다.

2. 외부 라이브러리 props와 자동 메모이제이션

Reanimated 외에도 외부 라이브러리에 prop으로 넘기는 인라인 객체·함수·배열은 전통적으로 수동 메모이제이션의 1순위 대상이었다. @gorhom/bottom-sheet의 snapPoints/onChange/onDismiss, react-native-tab-view의 renderScene, 차트 라이브러리의 config 등이 모두 같은 결이다. 라이브러리 내부 React.memo/useEffect deps가 참조 비교에 의존하기 때문에, 부모가 매 렌더마다 새 참조를 만들면 라이브러리 측 최적화가 무력화되거나 부수효과가 반복 실행된다.

1) RC가 켜져 있으면 자동 메모이제이션

React Compiler는 정확히 이 케이스를 노린다. 부모 컴포넌트가 분석 통과한 경우, JSX에 박힌 인라인 값이 표현식 단위로 캐시된다.

// RC ON, 부모가 분석 통과한 경우 — 아래 3개 props 모두 자동 메모이제이션
<BottomSheet
  snapPoints={['25%', '50%']} // 배열 리터럴 → 캐시
  onChange={idx => setIndex(idx)} // 함수 리터럴 → 캐시
  onDismiss={() => closeSheet()} // 함수 리터럴 → 캐시
/>

useMemo / useCallback을 손으로 까는 것과 의미상 동치이고, 표현식 단위라 더 잘게 쪼개 캐시한다. react-compiler.md 의 3번 이점("참조 안정성의 자동 확보")이 외부 라이브러리 prop 경계에서 발현되는 지점이다.

2) 자동이 안 되는 경우 — 여전히 수동

다음 상황에서는 RC가 손대지 못한다.

• 부모 컴포넌트가 RC 분석에서 skip — Rules of React 위반, 비표준 hook 패턴 등으로 컴파일러가 포기한 경우. DevTools의 Memo ✨ 배지가 없는 컴포넌트가 여기 해당.
• deps 체인이 끊긴 경우 — 부모가 받은 prop·context 값이 이미 매 렌더 새 참조면, 그 값을 의존성으로 잡는 RC 캐시도 매번 무효화된다. 위쪽 컴포넌트 중 하나가 skip이면 그 아래로 전염된다.

이 경우에는 기존처럼 useMemo / useCallback을 명시적으로 깔아야 한다.

3) 모듈 스코프 상수는 여전히 best

RC 유무와 무관하게 가장 안전한 방법은 컴포넌트 밖으로 상수를 들어내는 것이다.

const SNAP_POINTS = ['25%', '50%'] as const; // 모듈 최상단

const Sheet = () => <BottomSheet snapPoints={SNAP_POINTS} {...rest} />;

처음부터 한 번만 만들어지는 참조이므로 RC가 분석 가능/불가능 어느 쪽이든 항상 안정적이다. 컴포넌트 prop·state에 의존하지 않는 값(고정 snapPoints, 정적 config 객체 등)이라면 이 형태가 최선.

4) 정리

"RC 켰으니 외부 라이브러리 prop은 무조건 자동" 이 아니라, Memo ✨ 배지로 적용 여부를 확인하는 절차가 새로운 검증 의무로 들어온다.

3. 가상화 리스트 (renderItem / 아이템 memo()) 와 RC

FlatList / FlashList / LegendList 같은 가상화 리스트는 전통적으로 두 가지 메모이제이션이 필수였다.

1. renderItem 을 useCallback 으로 감싸기 — 리스트 내부 effect 재실행과 인라인 함수의 새 참조 문제 방지
2. 리스트 아이템 컴포넌트에 memo() 적용 — 동일 데이터 셀의 재렌더 방지

RC를 켜면 둘 다 자동화된다. 다만 결이 약간 달라 별도로 짚는다.

참고: 라이브러리 버전에 따라 권장 패턴이 다를 수 있다. 특히 FlashList는 v2에서 내부 최적화 정책과 권장 props가 일부 바뀌었으니, 세부 권장은 사용하는 라이브러리 버전의 공식 문서를 함께 확인한다. 아래 설명은 "참조 안정성이 왜 중요한가"라는 일반 원리에 대한 것이다.

1) renderItem 의 useCallback — 2번과 동일한 결

2번에서 본 "외부 라이브러리에 prop으로 넘기는 인라인 함수" 케이스와 정확히 같다. 부모가 분석 통과한 경우 RC가 표현식 단위로 캐시한다.

// RC ON, 부모가 분석 통과한 경우 — useCallback 불필요
<FlashList
  data={items}
  renderItem={({ item }) => <ItemCard item={item} onPress={handlePress} />}
  keyExtractor={keyExtractor}
/>

renderItem 인라인 화살표가 자동 캐시되므로 리스트 내부 effect 의존성이 안정된다.

2) 리스트 아이템의 memo() — 공식 문서가 직접 답을 준다

React.memo 공식 문서의 "Do I still need React.memo if I use React Compiler?" 섹션이 명시한다.

"When you enable React Compiler, you typically don't need React.memo anymore. The compiler automatically optimizes component re-rendering for you."

그리고 한 발 더 들어가서:

"The compiler's optimization is actually more comprehensive than React.memo. It also memoizes intermediate values and expensive computations within your components, similar to combining React.memo with useMemo throughout your component tree."

즉 RC의 메모이제이션은 React.memo + useMemo를 컴포넌트 트리 전체에 깐 것보다 포괄적이라는 것이 공식 입장이다. 가상화 리스트의 셀 재사용 환경에서도:

• 셀이 같은 데이터로 유지되는 경우 → RC 캐시 hit → JSX 재사용
• 셀이 새 데이터로 재활용되는 경우 → 새 props로 캐시 miss → 정상 렌더 (memo도 동일)

결론: 분석 통과한 아이템 컴포넌트라면 memo() 래퍼는 redundant.

3) 그럼 다 빼도 되는가 — 공식 권장은 "기존 코드는 두고, 신규 코드만 RC에 맡겨라"

이 단서는 React.memo 페이지가 아니라 React Compiler 1.0 발표 글(react.dev/blog)에 나온다. 원문은 신규 코드 → 기존 코드 순서로 다음과 같이 권장한다.

"For new code, we recommend relying on the compiler for memoization and using useMemo/useCallback where needed to achieve precise control. For existing code, we recommend either leaving existing memoization in place (removing it can change compilation output) or carefully testing before removing the memoization."

핵심은 "제거가 컴파일 출력을 바꿀 수 있다" 는 공식 경고 그대로. 정리 단계에서도 회귀 테스트 없이 일괄 제거하지 않는다.

4) memo() 가 여전히 escape hatch로 유용한 경우

공식 문서가 escape hatch로서의 가치를 부정하지 않는다. 가상화 리스트 맥락에서 유지·추가가 정당화되는 케이스:

• 부모가 RC 분석 skip — 부모가 안정 참조를 보장하지 못하면 자식의 RC 캐시도 매번 무효화된다. memo()로 명시적 prop 비교 게이트를 만들어 두면 그 무효화가 그 자식에서 멈춘다.
• 명시적 제어가 필요한 고비용 셀 — 차트·지도 마커·복잡한 이미지 비교 등. RC의 dep 추적이 보수적이라 불필요한 cache miss가 생기는 경우 memo() + areEqual로 비교 함수를 명시.
• 외부 라이브러리 셀 컴포넌트 — 라이브러리가 제공하는 컴포넌트(내부 RC 미적용)는 외부에서 한 번 memo()로 감싸 두는 편이 안전.

5) keyExtractor / overrideItemType 은 별개

이 둘은 RC 도입과 무관하다. 컴포넌트 외부 위치인 모듈 스코프 상수로 빼는 게 좋다. RC가 메모이제이션할 대상이 아니라 애초에 안정 참조가 보장되는 형태로 작성하는 항목이다.

// ✅ RC 유무와 무관하게 항상 이렇게
const keyExtractor = (item: Item) => item.id;
const getOverrideItemType = (item: FeedItem) => item.type;

한 줄 요약

react-compiler.md 의 RC는 "메모이제이션을 언제 거느냐"를 자동화한다. Reanimated worklet 재등록·외부 라이브러리 인라인 props·가상화 리스트의 renderItem 과 아이템 memo() 가 모두 본질적으로 참조 안정성 문제이고, 컴파일러는 (분석 가능한 컴포넌트에 한해) 이 세 영역 모두를 자동으로 처리한다 — React.memo 공식 문서가 "RC를 켜면 React.memo가 보통 필요 없고, 그 최적화는 memo + useMemo 조합보다 더 포괄적"이라고 명시한다. 다만 Reanimated 쪽은 get()/set() API 사용과 렌더 중 접근 금지 규칙을 지켜야 하고, 기존 코드의 memo/useCallback/useMemo 제거는 회귀 테스트 후 점진적으로(RC 1.0 발표 글의 권장), Memo ✨ 배지로 분석 통과 여부 확인이 새 검증 의무로 들어온다.

React Compiler(이하 RC)는 빌드 타임에 코드를 분석해 메모이제이션을 자동으로 삽입하는 컴파일러다. 지금까지 개발자가 손으로 깔던 React.memo / useMemo / useCallback을, 컴파일러가 데이터 흐름과 가변성(mutability)을 분석해 적절한 위치에 자동으로 넣어준다. 런타임 라이브러리가 아니라 빌드 단계의 변환 도구이고, Rules of React를 따르는 코드라면 코드를 다시 쓸 필요 없이 적용된다.

2025년 10월 7일 1.0 정식 버전이 출시되었고, React와 React Native 양쪽을 지원한다.

1) RC가 실제로 절약하는 것 — JS 스레드의 재실행·재조정

가장 먼저 바로잡아야 할 오해는 "RC가 네이티브 렌더링이나 화면 갱신을 줄여준다"는 그림이다. 아니다. RC가 메모이제이션으로 절약하는 대상은 컴포넌트 함수의 재실행과 그 서브트리의 재조정(reconciliation) 이며, 둘 다 순수하게 JS 스레드에서 일어나는 작업이다.

React의 동작을 단계로 나누면 분명해진다. 상태·props 변화로 컴포넌트 함수가 재실행되고(렌더 단계), 새 트리와 이전 트리를 diff해 변경분을 추리고(재조정), 변경분만 호스트에 반영한다(커밋 단계). 출력이 이전과 같으면 재조정 단계에서 "변경 없음"으로 걸러져 커밋(네이티브 갱신)은 어차피 일어나지 않는다 — 메모이제이션 여부와 무관하게.

따라서 RC가 막아주는 것은 "출력이 같은데도 굳이 컴포넌트를 재실행하고 그 자식들을 재조정하는" JS 스레드 낭비다. 이 구분이 RC를 이해하는 핵심이다.

2) 어떻게 동작하는가 — 표현식 단위 캐시

RC는 컴포넌트를 컴파일하면서, 렌더 중 생성되는 각 값·함수가 어떤 입력에 의존하는지를 표현식 단위로 추적한다. 그리고 값마다 독립된 캐시 슬롯과 독립된 의존성 비교를 배치한다. (산출물에 등장하는 _c 헬퍼는 내부 구현 디테일이며 공식 API가 아님)

// 원본
function Component({ x, y }) {
  const a = expensiveA(x); // x에만 의존
  const b = expensiveB(y); // y에만 의존
  return <Child a={a} b={b} />;
}

// RC가 생성하는 코드 (개념도)
function Component({ x, y }) {
  const $ = _c(5); // 캐시 슬롯 배열

  let a;
  if ($[0] !== x) {
    // a는 x가 바뀔 때만 재계산
    a = expensiveA(x);
    $[0] = x;
    $[1] = a;
  } else {
    a = $[1];
  }

  let b;
  if ($[2] !== y) {
    // b는 y가 바뀔 때만 재계산 — a와 독립
    b = expensiveB(y);
    $[2] = y;
    $[3] = b;
  } else {
    b = $[3];
  }

  // <Child a={a} b={b} /> JSX도 a·b가 그대로면 이전 엘리먼트를 재사용
  // ...
}

x만 바뀌면 a만 다시 계산하고 b는 캐시 값을 그대로 쓴다. JSX 엘리먼트 자체도 같은 방식으로 캐시되어, props가 그대로면 이전에 만든 엘리먼트를 재사용한다 — 이것이 React.memo가 하던 "props 안 바뀌면 자식 리렌더 스킵"과 동일한 효과다.

2. 수동 메모이제이션보다 정밀한 이유

수동 useMemo는 블록 단위다. 콜백이 반환하는 값을 통째로 캐시하고, deps 중 하나만 바뀌어도 콜백 전체가 다시 돈다. 위 예시를 useMemo 하나로 묶으면 x만 바뀌어도 expensiveB(y)까지 재실행된다.

RC는 이를 표현식 단위로 쪼개므로, 같은 정밀도를 손으로 내려면 값마다 useMemo를 따로 걸어야 하며 값이 늘수록 비현실적이다. "표현식 단위로 캐시한다"는 말의 뜻은 각 값이 자기 의존성에만 반응하는 것이며 값마다 독립된 캐시 슬롯과 독립된 의존성 비교를 둔다는 것이다.

게다가 RC는 조건부(분기 안에서의) 메모이제이션처럼 수동으로는 표현하기 어려운 최적화도 한다. 공식 문서가 "RC는 useMemo/useCallback/React.memo보다 더 정밀하고 granular하게 메모이제이션한다"고 말하는 근거가 이것이다.

3. Rules of React에 의존

RC가 안전하게 동작하는 전제는 코드가 Rules of React를 지키는 것이다(렌더 순수성, 렌더 중 props/state/ref/전역 변이 금지, 훅 규칙 등). 컴파일러는 이 규칙 위반을 정적으로 감지하면 그 컴포넌트만 최적화에서 skip 하고 나머지는 계속 컴파일한다.

여기서 중요한 성질이 있는데, 바로 이 skip은 에러가 아니라 조용한 안전 후퇴다. 기본 동작은 치명적이지 않은 위반을 빌드를 깨지 않고 skip하는 것이며, 모든 위반을 무중단 skip 처리하려면 panicThreshold: 'none'을 명시(공식 docs의 프로덕션 권장 설정)한다. 어쨌든 어떤 컴포넌트가 최적화에서 빠졌는지 명시적 신호 없이 지나갈 수 있으므로, 두 가지 도구가 책임을 나눠 갖는다.

• eslint-plugin-react-hooks recommended/recommended-latest 프리셋 — RC 1.0부터 별도 eslint-plugin-react-compiler는 deprecated이고, 검증 규칙이 이쪽으로 통합되었다. 역할은 컴파일러가 못 잡은 Rules of React 위반을 빌드 전에 표면화하는 것이다(RC를 켜지 않아도 켤 수 있다).
• ✨ 배지 — React(Native) DevTools의 Component Inspector에서 실제로 컴파일된 컴포넌트에 ✨ 배지가 붙는다. 적용 여부 확인은 이쪽 책임이다 — 배지가 없으면 skip된 것.

즉 "RC를 켰으니 무조건 다 최적화된다"가 아니라, 린트로는 사전 위반 검출, DevTools 배지로는 적용 여부 확인이라는 절차가 따라붙는다. RC가 안전하게 적용하기 위해 지켜야 하는 rules는 다다음 글에서 살펴볼 예정이다.

4. React 19 / React Native와의 관계

RC는 React 19를 네이티브로 지원하며, RN은 0.78부터 React 19 런타임을 채택했다(RN 자체 버전은 여전히 0.x다). React 17/18에서도 동작시킬 수 있는데, 그땐 두 가지가 추가로 필요하다.

• react-compiler-runtime 패키지 설치
• compiler config에 target: '17' | '18' 명시 (기본 타깃은 '19')

RN에서는 Metro가 Babel을 쓰므로 babel-plugin-react-compiler로 적용한다. 이 플러그인은 다른 Babel 플러그인들보다 먼저 실행되어야 한다 — babel.config.js의 plugins 배열에서 반드시 첫 번째 위치에 둬야 변환이 깨지지 않는다(공식 docs에서 강조하는 제약).

New Architecture로 네이티브 커밋 비용이 낮아졌어도 컴포넌트 함수 실행과 재조정은 여전히 JS 스레드에 남으므로, RC의 역할은 아키텍처 전환과 무관하게 유지된다.

5. RC가 바꾸지 않는 것

마지막으로, RC가 무엇을 안 바꾸는지가 그 정체를 가장 잘 드러낸다. RC는 메모이제이션의 비용·이득 모델 자체를 바꾸지 않는다. 절약되는 대상은 여전히 JS 스레드의 재실행·재조정이고, 그 가치가 RN의 단일 JS 스레드 구조에서 더 크다는 점도 그대로다. RC가 바꾼 것은 오직 적용 방식이다 — 사람이 어디에 memo를 걸지 판단하던 일을, 컴파일러가 더 정밀하게 자동으로 한다.

정리

React Compiler는 빌드 타임에 데이터 흐름을 분석해 표현식 단위로 메모이제이션을 자동 삽입하는 컴파일러다. 절약하는 대상은 네이티브 렌더링이 아니라 JS 스레드의 컴포넌트 재실행·재조정이고, 수동 useMemo보다 잘게·조건부로 최적화한다.

동작 전제는 Rules of React 준수이며, 위반 컴포넌트는 빌드를 깨지 않고 조용히 skip한다. 그래서 eslint-plugin-react-hooks로 사전 위반을 검출하고 DevTools의 ✨ 배지로 실제 적용 여부를 확인하는 절차가 따라온다. RN에 도입할 땐 babel-plugin-react-compiler를 Babel plugins 배열의 첫 번째로 두고, React 17/18에서는 react-compiler-runtime + target 옵션을 명시한다. "이론은 동일하고 적용만 자동화된다"가 핵심이다.