Grace Notes

React Navigation 심화 — 컴포넌트 트리 밖에서 안전하게 화면 전환하기

Grace Noh — Mon, 8 Jun 2026 16:46:30 +0900

React Navigation을 쓰다 보면 useNavigation()이 닿지 않는 곳에서 화면을 옮겨야 할 때가 온다. 딥링크 핸들러, 푸시 알림 콜백, 외부 SDK 콜백, 전역 인터셉터 같은 "컴포넌트 트리 바깥"이다. navigationRef를 쓰면 되지만, 막상 해보면 빈 화면·흰 화면 같은 타이밍 버그가 줄줄이 튀어나온다. 이 글은 트리 밖 화면 전환을 실제로 안정적으로 만들기까지 밟은 과정과, 그 사이에 만난 버그들의 정리다.

문제 — useNavigation이 닿지 않는 곳

화면 전환은 보통 컴포넌트 안에서 useNavigation() 훅으로 한다. 그런데 React 컴포넌트가 아닌 곳에서 전환을 트리거해야 하는 경우가 의외로 많다.

딥링크 핸들러 — linking.getInitialURL / subscribe는 모듈 스코프 함수다.
푸시 알림 탭 — 백그라운드 핸들러는 트리 밖에서 실행된다.
외부 SDK / 전역 콜백 — 결제, 분석, 소켓 이벤트 등.
axios 인터셉터 — 401 응답에서 로그인 화면으로 보내기.

이런 곳에선 훅을 쓸 수 없다. 공식 해법은 NavigationContainer에 ref를 달아 전역에서 접근하는 것이다.

// App.tsx
import { createNavigationContainerRef } from '@react-navigation/native';
export const navigationRef = createNavigationContainerRef();

<NavigationContainer ref={navigationRef}>
  {/* ... */}
</NavigationContainer>

// 트리 밖 어디서든
import { navigationRef } from './App';

if (navigationRef.isReady()) {
  navigationRef.navigate('SomeScreen');
}

여기까지는 문서에도 나온다. 문제는 "단순 navigate가 아니라 네비게이터 그룹을 통째로 바꿔야 할 때", 그리고 "트리 밖 ref와 React 생명주기가 어긋날 때" 시작된다.

1. 즉시 navigate가 불가능한 경우 — 플래그 + watcher 패턴

우리 앱은 user.role에 따라 루트 네비게이터 그룹이 통째로 갈린다. 일반 사용자 그룹과 별도 그룹(예: 관리자 그룹)이 조건부로 렌더된다.

function RootNavigator() {
  const { data: user } = useGetUser();
  return (
    <Stack.Navigator>
      {user?.role === 'ADMIN' ? (
        <Stack.Screen name="AdminNav" component={AdminNavigator} />
      ) : (
        <Stack.Screen name="Home" component={Home} />
      )}
    </Stack.Navigator>
  );
}

문제는 트리 밖에서 "지금 관리자 그룹으로 보내!"를 호출하는 순간, AdminNav는 아직 트리에 존재하지 않는다. 그룹 전환은 user.role이 바뀌고 → 리렌더가 일어나야 비로소 마운트되기 때문이다. 이 시점에 바로 navigate('AdminNav')를 하면 "해당 라우트가 없다"며 실패한다.

그래서 직접 이동 대신 의도(플래그)만 남기고, 트리 안의 watcher가 적절한 타이밍에 소비하게 했다.

// pendingEntry.ts — 모듈 스코프 플래그
let pending = false;
export const setPending = (v: boolean) => { pending = v; };
export const consumePending = () => {
  const v = pending;
  pending = false;   // 1회성 소비
  return v;
};

// 트리 밖: 상태를 바꾸고 의도만 남긴다
function handleExternalTrigger() {
  // ...role 을 바꾸는 작업(세션 갱신 등)...
  setPending(true);   // 직접 navigate 하지 않는다
}

// 트리 안 watcher: 그룹이 마운트된 "다음" 프레임에 소비
useEffect(() => {
  if (user === undefined) return;          // 역할 미확정이면 대기
  if (user.role !== 'ADMIN') return;       // 아직 그룹 미마운트면 대기
  if (!consumePending()) return;

  if (navigationRef.isReady()) {
    navigationRef.resetRoot({ index: 0, routes: [{ name: 'AdminNav' }] });
  } else {
    pendingResetRef.current = true;         // 준비 전이면 onReady 로 미룬다
  }
}, [user]);

핵심: 조건부 렌더링과 즉시 navigate는 타이밍이 어긋난다. "상태를 바꿔 그룹을 마운트시킨 뒤, 마운트된 다음 프레임에 이동"이라는 2단계로 끊으면 레이스가 사라진다. resetRoot를 쓴 이유는 단순 이동이 아니라 스택을 갈아끼워 뒤로가기로 돌아오지 못하게 하기 위함이다.

2. user가 바뀌지 않는 진입 경로 — listener 보강

위 watcher는 [user] 의존성으로 돈다. 즉 user 값이 바뀔 때만 재실행된다. 그런데 진입 경로에 따라선 user가 아예 바뀌지 않는 경우가 있다.

예를 들어 이미 비로그인 상태(user가 이미 그 값)인 화면에 머무는 중에 외부 트리거가 들어오면, user는 그대로라 effect가 다시 돌지 않는다. 플래그만 세워지고 아무도 소비하지 않아 화면이 고착된다.

해결은 플래그 set 자체를 구독 가능한 이벤트로 만드는 것이다.

// pendingEntry.ts
let listener: (() => void) | null = null;

export const setPending = (v: boolean) => {
  pending = v;
  if (v) listener?.();   // set(true) 시 즉시 통지 → user 변화에 의존하지 않음
};
export const subscribePending = (cb: () => void) => {
  listener = cb;
  return () => { if (listener === cb) listener = null; };
};

// 트리 안: user 변화 외에 "플래그 set" 도 직접 구독
useEffect(() => subscribePending(processPending), []);

진입 경로가 여러 개면 신호도 여러 개 필요하다. "상태 변화에 묻어가는 신호"([user] effect)와 "상태와 무관한 직접 신호"(listener)를 함께 둬야 모든 경로가 빠짐없이 처리된다. watcher 하나로 다 되겠지 하면 꼭 한 경로가 샌다.

3. 가장 지독한 버그 — Activity 재생성과 죽은 ref

여기서부터가 진짜 함정이다. HOC나 트리 밖 코드에서 resetRoot를 쓰려고, onReady에서 컨테이너의 live ref를 모듈 스코프 브릿지에 주입해 뒀다고 하자.

<NavigationContainer
  ref={navigationRef}
  onReady={() => setNavigationRef(navigationRef.current)}  // 브릿지에 주입
>

이게 Android의 "활동을 유지하지 않음" 설정이나 메모리 회수로 Activity가 재생성될 때 터진다. JS 프로세스(컨텍스트)는 살아 있어서 모듈 스코프의 navigationRef가 이미 파괴된 컨테이너를 가리킨 채 남는다. 리마운트된 화면이 그 ref를 "준비됨(non-null)"으로 오인하고 죽은 컨테이너에 resetRoot를 흘려보내면 — 아무 일도 안 일어나고 빈 화면이 된다.

해결은 의외로 단순하다. 컨테이너가 언마운트될 때 브릿지를 비운다.

useEffect(() => {
  return () => setNavigationRef(null);   // 언마운트 시 죽은 ref 정리
}, []);

이렇게 하면 리마운트된 코드가 ref를 다시 null에서 출발해(콜드 스타트와 동일) onReady를 정상적으로 재구독한다.

교훈: 모듈 스코프(React 밖)에 둔 ref는 컴포넌트 생명주기와 자동으로 동기화되지 않는다. 마운트 시 주입 / 언마운트 시 정리를 한 쌍으로 직접 관리해야 한다. 안 그러면 "살아있어 보이는 시체 ref"에 당한다.

4. Fast Refresh가 삼킨 per-screen reset

개발 중에만 재현되던 흰 화면도 있었다. 어떤 화면을 감싼 가드 HOC에서, 특정 조건이면 다른 그룹으로 보내려고 per-screen navigation.dispatch(reset)을 썼다.

// ❌ Fast Refresh 상황에서 이 dispatch 가 무시되는 경우가 있었다
navigation.dispatch(CommonActions.reset({
  index: 0, routes: [{ name: 'OtherNav' }],
}));

Fast Refresh로 컴포넌트가 갈아끼워지는 타이밍에 이 per-screen dispatch가 삼켜져서, 리다이렉트 대상이 원래 화면에 그대로 머무는 흰 화면이 났다. 해결은 per-screen navigation 대신 항상 동작하는 컨테이너 live ref의 resetRoot로 바꾸는 것이었다.

// ✅ 컨테이너 ref 의 resetRoot 는 항상 동작
const ref = getNavigationRef();
if (ref) {
  ref.resetRoot({ index: 0, routes: [{ name: 'OtherNav' }] });
}

추가로, 가드의 effect는 부모 NavigationContainer의 onReady보다 먼저 커밋된다(자식 effect가 부모보다 먼저 실행). 그래서 첫 렌더에 ref가 아직 null일 수 있는데, 이걸 그냥 두면 리다이렉트가 안 일어나 고착된다. ref 주입 시점을 구독해 준비되면 effect를 재실행하게 했다.

const [isNavReady, setIsNavReady] = useState(() => getNavigationRef() != null);

useEffect(() => {
  if (isNavReady) return;
  const unsub = subscribeNavigationRef(() => setIsNavReady(true));
  // 초기 useState 평가와 구독 등록 사이 갭에서 놓친 주입을 보정
  if (getNavigationRef() != null) setIsNavReady(true);
  return unsub;
}, [isNavReady]);

5. 보너스 — 딥링크 경로 판별은 부분 일치로 하지 마라

트리 밖 화면 전환은 딥링크에서 자주 일어나는데, 여기서도 작은 함정을 하나 밟았다. 특정 경로(admin 같은)를 판별하려고 처음엔 endsWith를 썼다.

// ❌ superadmin, foo/admin 까지 오탐
if (url.endsWith('admin')) { ... }

superadmin이나 something/admin 같은 URL이 전부 매칭됐다. prefix를 떼어낸 나머지 경로가 정확히 일치하는지로 바꿔야 한다.

// ✅ prefix 제거 후 완전 일치
const PREFIXES = ['myapp://', 'https://myapp.example.com'];
const getPathAfterPrefix = (url: string) => {
  const prefix = PREFIXES.find((p) => url.startsWith(p));
  const rest = prefix ? url.slice(prefix.length) : url;
  return rest.split('#')[0].split('?')[0].replace(/^\/+|\/+$/g, '');
};
const isAdminPath = (url: string) => getPathAfterPrefix(url) === 'admin';

판별에 쓰는 prefix 배열은 linking.prefixes와 같은 상수를 공유하게 해서 둘이 어긋나지 않도록 했다.

정리

트리 밖 화면 전환의 어려움은 결국 "React 밖에서 시작해 React 안에서 끝나는 흐름"의 타이밍을 맞추는 일이다. 정리하면:

즉시 navigate가 안 되면 플래그+watcher로 끊어라. 조건부 렌더로 마운트될 그룹은, 마운트된 다음 프레임에 이동시킨다.
진입 경로가 여럿이면 신호도 여럿이다. 상태 변화에 묻어가는 신호([user] effect)와 직접 신호(listener)를 함께 둬라.
모듈 스코프 ref는 생명주기와 어긋난다. 마운트 시 주입 / 언마운트 시 정리를 한 쌍으로 관리하라. Activity 재생성의 "좀비 ref"를 조심.
그룹 전환엔 per-screen reset보다 컨테이너 resetRoot. Fast Refresh에서 per-screen dispatch가 삼켜질 수 있다.
ref 준비 시점을 구독하라. 자식 effect는 부모 onReady보다 먼저 커밋된다.
딥링크 경로는 부분 일치로 판별하지 마라. prefix 제거 후 완전 일치.

이 패턴들은 처음부터 설계로 떠오르지 않는다. 빈 화면·흰 화면 버그를 하나씩 잡아가며 "아, 여기서 React 밖과 안이 어긋나는구나"를 깨달은 흔적에 가깝다. 같은 곳에서 헤매는 누군가에게 지름길이 되면 좋겠다.

useEvent 패턴 — 부모 리렌더링이 자식 effect를 폭주시키는 문제 해결하기

Grace Noh — Mon, 8 Jun 2026 12:54:28 +0900

리액트로 외부 라이브러리나 SDK를 붙이다 보면 한 번쯤 마주치는 함정이 있다. 부모에서 콜백을 prop으로 넘겼을 뿐인데, 부모가 리렌더링될 때마다 자식의 useEffect가 통째로 다시 실행되는 현상이다. 이 글에서는 그 원인을 짚고, useEvent라는 한 줄짜리 훅으로 깔끔하게 해결하는 방법을 정리한다.

어떤 문제인가

리액트에서 자식 컴포넌트(특히 외부 라이브러리)에 콜백을 prop으로 넘길 때, 자식이 그 콜백을 useEffect의 deps 배열에 잡고 있으면 문제가 생긴다. 부모가 리렌더링될 때마다 새 콜백 reference가 만들어지고, 그 reference 변화가 자식의 effect를 매번 재실행시킨다.

// 자식 (외부 라이브러리라고 가정)
function ThirdPartyWidget({ onResult }) {
  useEffect(() => {
    const handle = expensiveSetup(onResult);   // 무거운 초기화
    return () => handle.cleanup();
  }, [onResult]);   // ← 콜백 reference가 바뀔 때마다 setup/cleanup 반복
  // ...
}

// 부모
function Parent() {
  const { user } = useAuth();

  const onResult = async (result) => {
    // user 같은 값을 클로저로 캡처해서 써야 한다
    await sendResult({ ...result, userId: user.id });
  };

  return <ThirdPartyWidget onResult={onResult} />;
  // ↑ 매 렌더마다 새 함수 → 자식 effect가 무한히 재트리거
}

핵심 딜레마는 이렇다. 콜백은 항상 최신 user를 봐야 하므로 매 렌더에 다시 만들어지는 게 자연스럽다. 그런데 그러면 reference가 매번 바뀌어서 자식 effect가 폭주한다. "최신 클로저"와 "안정적인 reference"를 동시에 원하는 것이다.

기존 해결책과 그 한계

방법 1 — useCallback(fn, [deps])

const onResult = useCallback(async (result) => {
  await sendResult({ ...result, userId: user.id });
}, [user.id]);

❌ deps에 들어간 값이 바뀌면 결국 reference가 바뀐다 → 자식 effect 재실행은 못 막는다.
❌ deps를 빠뜨리면 stale closure 버그. 옛날 값을 캡처한 함수가 호출된다.

deps 누락은 react-hooks/exhaustive-deps ESLint 규칙이 잡아주긴 하지만, 그 규칙을 따를수록 reference가 더 자주 바뀌는 모순에 빠진다.

방법 2 — useCallback(fn, []) + 값마다 useRef

reference를 영구히 고정하고 싶으니 deps를 비운다. 대신 최신값이 필요한 변수들을 ref로 따로 들고 있는다.

const userLatest = useRef(user);
userLatest.current = user;
const dataLatest = useRef(data);
dataLatest.current = data;
// ... 캡처할 값마다 이 두 줄을 반복

const onResult = useCallback(async (result) => {
  await sendResult({ ...result, userId: userLatest.current.id });
}, []);

✅ reference는 영구 안정. 자식 effect를 재트리거하지 않는다.
✅ stale closure도 없다. ref를 통해 항상 최신값을 읽는다.
❌ 보일러플레이트가 너무 많다. 캡처할 값을 추가/제거할 때마다 ref를 손봐야 한다.
❌ 새 변수를 쓰기 시작했는데 ref 등록을 깜빡하면 그 변수만 조용히 stale해진다. 가장 찾기 어려운 종류의 버그다.

동작은 완벽하지만 사람이 실수하기 좋은 구조다. 이걸 한 줄로 줄이는 게 useEvent다.

해결: useEvent 훅

아이디어는 단순하다. 변수마다 ref를 만드는 대신, 콜백 함수 자체를 하나의 ref에 저장한다. 그리고 그 ref를 호출하기만 하는 안정적인 wrapper를 바깥에 노출한다.

// hooks/useEvent.ts
import { useCallback, useLayoutEffect, useRef } from 'react';

export function useEvent<TArgs extends unknown[], TReturn>(
  fn: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn {
  const ref = useRef(fn);

  useLayoutEffect(() => {
    ref.current = fn;   // 매 렌더 직후 최신 fn으로 갱신
  });

  return useCallback((...args: TArgs) => ref.current(...args), []);
  //     ↑ 영구히 동일한 reference. 내부에서 최신 fn을 호출.
}

사용

import { useEvent } from './hooks/useEvent';

const onResult = useEvent(async (result: Result) => {
  // user, data 등을 그냥 평범하게 클로저로 접근 — 항상 최신값
  await sendResult({ ...result, userId: user.id });
});

한 줄. ref 보일러플레이트가 전부 사라진다. 함수 안에서는 평소처럼 부모 스코프 변수를 쓰면 되고, 바깥으로 나가는 reference는 컴포넌트 수명 내내 고정된다.

동작 원리

세 가지 사실이 맞물려 돌아간다.

컴포넌트 lifetime 동안 동일 reference
useCallback(..., [])이 한 번 만든 wrapper 함수를 영원히 재사용한다. 이 wrapper가 자식 effect의 deps에 들어가도 절대 바뀌지 않으니 effect를 재실행시키지 않는다.
호출 시점에는 항상 최신 클로저
useLayoutEffect가 매 렌더 직후 ref.current를 최신 fn으로 덮어쓴다. wrapper가 호출되면 ref.current(...)를 통해 가장 최신 함수를 부른다. 그 함수 안에서는 평범하게 부모 스코프의 변수에 접근하므로 항상 최신값이 보인다.
useEffect가 아니라 useLayoutEffect인 이유useEvent에서 굳이 useLayoutEffect를 쓰는 이유는 타이밍 안전성 때문이다.
- useEffect는 commit 이후 비동기라, ref가 갱신되기 전에 wrapper가 호출되는 짧은 윈도우가 존재한다 → 그 사이에 호출되면 옛 fn이 실행될 수 있다.
- useLayoutEffect는 commit 직후 동기라 그 윈도우가 없다 → wrapper가 호출되는 시점에는 항상 최신 fn이 보장된다.

useLayoutEffect란?
useEffect와 거의 같지만 실행 타이밍이 다른 훅이다. 리액트가 DOM을 업데이트(commit)한 직후, 브라우저가 화면을 그리기(paint) 전에 동기적으로 실행된다. useEffect는 반대로 브라우저가 그린 뒤에 비동기로 실행된다.

단계	render	commit (DOM 업데이트)	useLayoutEffect	paint (브라우저 그리기)	useEffect
타이밍	동기	동기	동기, paint 직전	비동기	paint 이후

보통은 useEffect가 디폴트다 — paint를 막지 않아 더 빠르다. useLayoutEffect는 DOM 측정/조작이 paint 전에 끝나야 하는 경우(레이아웃 깜빡임 방지)에 쓴다.

한눈에 비교

방식	코드량	stale 위험	자식 재트리거
평범한 함수	적음	없음	있음
useCallback([deps])	보통	deps 누락 시 있음	deps 변화 시 있음
useCallback([]) + 값마다 useRef	많음	ref 빠뜨리면 있음	없음
useEvent	한 줄	없음	없음

리액트 공식 API: useEffectEvent (React 19.2)

사실 리액트 팀도 똑같은 컨셉을 정식 API로 내놓았다. 이름은 useEffectEvent, React 19.2부터 안정 API다. (초기 RFC에서는 useEvent라는 이름이었는데, "Effect 안에서 호출하는 게 주된 용도"라는 의미를 분명히 하려고 useEffectEvent로 바뀌었다.)

기본 사용

import { useEffectEvent } from 'react';

function ChatRoom({ roomId, theme }) {
  const onConnected = useEffectEvent(() => {
    showNotification('Connected!', theme);   // theme 항상 최신
  });

  useEffect(() => {
    const conn = createConnection(roomId);
    conn.on('connected', () => onConnected());
    conn.connect();
    return () => conn.disconnect();
  }, [roomId]);   // ← theme도, onConnected도 deps에 안 넣어도 된다
}

핵심 특성

항상 최신 props/state 캡처 — userland useEvent와 동일하다.
deps 배열에 넣지 않아야 한다 — 오히려 넣으면 ESLint가 경고한다.
Effect 내부 호출이 권장 패턴 — 자식 컴포넌트에 prop으로 직접 넘기는 건 제약이 있을 수 있다.
렌더 중 호출 금지 — 컴포넌트 render body에서 직접 부르면 안 된다.

그렇다면 userland useEvent는 이제 필요 없을까?

useEffectEvent는 본래 effect 내부에서 호출하는 non-reactive 이벤트 핸들러를 추출하기 위해 설계됐다. 이 글에서 다룬 "외부 컴포넌트에 콜백 prop으로 직접 넘기는" 케이스는 결이 조금 다르다.

사용처	userland useEvent	공식 useEffectEvent
useEffect 내부 호출	✅ 동작	✅ 권장
자식 컴포넌트 prop	✅ 동작	⚠️ 동작하지만 ESLint 경고
이벤트 핸들러 prop (onClick 등)	✅ 동작	⚠️ 동작하지만 권장 안 함
외부 SDK / setTimeout 콜백	✅ 동작	⚠️ 동작은 함

즉 React 19.2 이상이라면 effect 내부에서 호출하는 케이스는 공식 useEffectEvent로 옮기는 게 좋다. 반면 외부 라이브러리에 콜백 prop으로 넘기는 케이스는 userland useEvent가 여전히 유용하다. 의미적으로 "effect 전용"이라는 시그널이 없는 게 오히려 자연스럽고, ESLint 경고도 피할 수 있다. 두 API가 같은 패턴을 공유하므로, 나중에 권장 방식이 바뀌더라도 마이그레이션이 매끄럽다.

어디에 쓰면 좋은가

외부 컴포넌트에 콜백을 넘기는데 그 콜백이 자식의 effect deps에 들어가는 경우
WebView 메시지 핸들러, 외부 SDK 콜백, 차트/지도 라이브러리의 이벤트 핸들러 등
결과 전송처럼 "최신 상태를 캡처해야 하지만 reference는 고정돼야 하는" 비동기 콜백

반대로 일반적인 이벤트 핸들러(버튼 onClick/onPress 등)는 굳이 쓸 필요 없다. 리액트가 알아서 처리해주는 영역이라 과한 추상화가 된다.

실전 적용 예시

외부 위젯 컴포넌트가 onResult prop을 effect deps로 잡고 있어서, 부모의 data·locale·deviceInfo 같은 값이 바뀔 때마다 결과 전송이 반복 트리거되는 문제가 있었다고 하자.

Before — 값마다 useRef

const sendResultLatest = useRef(sendResult);
sendResultLatest.current = sendResult;
const routineIdLatest = useRef(data?.routineId);
routineIdLatest.current = data?.routineId;
const localeLatest = useRef(locale);
localeLatest.current = locale;

const onResult = useCallback(async (result) => {
  const body = {
    routineId: routineIdLatest.current ?? 0,
    preferredLang: localeLatest.current,
    deviceId: deviceInfo?.deviceId,   // ← ref 등록을 빠뜨림! stale closure
    // ...
  };
  await sendResultLatest.current(body);
}, []);

deviceInfo만 ref로 감싸는 걸 깜빡했고, 그 결과 이 필드만 옛날 값으로 전송되는 버그가 숨어 있다. 코드만 봐서는 눈에 잘 띄지 않는다.

After — useEvent

const onResult = useEvent(async (result: Result) => {
  const body = {
    routineId: data?.routineId ?? 0,
    preferredLang: locale,
    deviceId: deviceInfo?.deviceId,   // ← 자동으로 최신값
    // ...
  };
  await sendResult(body);
});

코드량은 절반 이하로 줄고, 어떤 변수를 추가하든 자동으로 최신값을 본다. stale closure가 구조적으로 발생할 수 없다.

마치며

useEvent는 "최신 클로저"와 "안정적인 reference"라는, 평소엔 양립하기 어려운 두 요구를 한 줄로 충족시킨다. 외부 라이브러리를 자주 붙이는 코드베이스라면 공용 훅으로 하나 만들어두는 것을 추천한다. React 19.2 이상이라면 effect 내부 호출은 공식 useEffectEvent로, 콜백 prop 전달은 useEvent로 — 두 패턴을 상황에 맞게 함께 쓰면 된다.

참고 링크

React 공식 문서: useEffectEvent
"Separating Events from Effects" 가이드: https://react.dev/learn/separating-events-from-effects
원본 RFC: https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md

iOS 빌드 인프라, 어디서 돌릴까 — 6가지 옵션 비교와 self-hosted runner 구축기

Grace Noh — Fri, 5 Jun 2026 13:41:41 +0900

React Native 모노레포의 iOS 빌드를 어디서 돌릴지 고민하며 6가지 인프라 옵션을 비교했고, 최종적으로 사내 Mac에 GitHub Actions self-hosted runner를 붙였습니다. 옵션별 비교, 우리가 self-hosted를 고른 이유, 그리고 self-hosted 특유의 함정(코드 서명·키체인)을 어떻게 넘었는지 공유합니다.

들어가며

저희 팀은 여러 개의 React Native 앱을 하나의 Nx 모노레포에서 운영하고 있습니다. 빌드/배포 파이프라인은 GitHub Actions 위에 올라가 있고, Git 태그를 푸시하면 해당 앱이 Stage/Prod로 빌드되는 구조입니다. Android는 Linux runner에서 잘 돌아갑니다. 문제는 항상 iOS였습니다.

iOS 빌드는 macOS에서만 가능합니다. Xcode가 macOS 전용이기 때문에 Linux runner를 아무리 늘려도 IPA 하나 만들 수 없습니다. 그래서 "iOS 빌드를 어디서 돌릴 것인가"는 단순한 CI 설정 문제가 아니라, macOS 컴퓨팅 자원을 어떻게 확보할 것인가라는 인프라 의사결정이 됩니다.

이 글에서는 ① iOS 빌드 인프라 6가지 옵션을 비교하고, ② 저희가 사내 Mac + self-hosted runner를 선택한 이유, ③ 그리고 self-hosted를 실제로 굴리면서 마주친 코드 서명·키체인 문제를 어떻게 해결했는지를 다룹니다.

iOS 빌드는 왜 인프라 문제가 되는가

GitHub Actions에서 Linux runner는 분당 약 $0.006, Windows는 $0.010 수준입니다. 그런데 macOS runner는 분당 $0.06 안팎으로 한 자릿수 배 비쌉니다. macOS는 Apple 하드웨어에서만 합법적으로 실행할 수 있어서, 클라우드 사업자 입장에서도 "Mac 하드웨어를 사서 빌려주는" 구조라 단가가 높을 수밖에 없습니다.

여기에 두 가지 제약이 더 붙습니다.

분당 과금 구조: iOS 빌드는 Pod 설치, 네이티브 컴파일, 코드 서명, 아카이브까지 한 번에 15~25분이 쉽게 걸립니다. 빌드 횟수가 늘수록 비용이 선형으로 증가합니다.
Apple의 라이선스 제약: 일부 클라우드 Mac은 macOS 라이선스 약관 때문에 24시간 최소 대여 같은 제약이 있습니다. "필요할 때 1시간만" 쓰는 게 불가능한 경우가 있습니다.

즉, iOS 빌드 인프라는 "싸고, 빠르고, 관리 안 해도 되는" 세 가지를 동시에 만족하기 어렵습니다. 그래서 팀의 빌드 빈도와 관리 여력에 따라 정답이 달라집니다. 먼저 선택지를 펼쳐 보겠습니다.

아래 비용은 저희가 리서치하던 시점 기준의 대략적인 수치입니다. 가격 정책은 자주 바뀌므로 정확한 금액은 각 서비스 공식 페이지를 확인하세요.

옵션 비교

1. GitHub Actions macOS Runner

GitHub이 호스팅하는 macOS runner. 기존 워크플로우에서 runs-on만 바꾸면 되는 가장 손쉬운 선택지입니다.

항목	내용
가격	표준(3~4 core) ~$0.062/분, xlarge(M2 Pro) ~$0.10/분
설정 난이도	낮음 (runs-on: macos-15 한 줄)
관리 부담	없음
빌드 제한	분당 과금 (private repo는 무료 tier 미포함)

장점: 인프라 관리가 전혀 필요 없고, 기존 GitHub Actions 워크플로우를 그대로 쓸 수 있습니다. 더 빠른 머신이 필요하면 runs-on만 xlarge로 바꾸면 됩니다.
단점: 분당 과금이라 빌드가 많아지면 비용이 가파르게 오릅니다. 빌드 캐시 용량 제한(10GB)이 있고, 머신 환경을 커스텀하기 어렵습니다.
월 예상: 20분 빌드 × 30회 = 600분 → 표준 ~$37, xlarge ~$61.

2. Codemagic

React Native·Flutter를 공식 지원하는 모바일 전용 CI/CD. 코드 서명과 스토어 업로드를 자동으로 관리해 줍니다.

항목	내용
가격(무료)	M2 머신 500분/월, 동시 빌드 1개
가격(종량제)	M2 ~$0.095/분
가격(정액)	~$333/월(무제한)
설정 난이도	중간 (codemagic.yaml)

장점: 무료 500분이면 소규모 팀엔 충분합니다. Fastlane 연동, 코드 서명 자동 관리, TestFlight 자동 업로드 등 모바일에 특화돼 있습니다.
단점: GitHub Actions와 별도의 CI를 이중 운영하게 됩니다. 기존 워크플로우를 마이그레이션해야 합니다.

3. EAS Build (Expo)

Expo의 빌드 서비스. bare workflow(순수 RN)도 지원합니다.

항목	내용
가격(무료)	iOS 15빌드/월
가격(유료)	Starter $19/월, Production $199/월
설정 난이도	중간 (eas.json + Expo CLI)

장점: RN에 특화돼 빌드 설정이 단순하고, EAS Update(OTA)와 통합됩니다.
단점: bare를 지원하지만 결국 Expo 생태계(eas-cli)에 종속됩니다. 무료 15빌드는 금방 소진되고, 빌드 큐 대기가 발생합니다. 기존 Fastlane 설정과 충돌할 수 있습니다.

4. MacStadium

전용 Mac 하드웨어를 월 단위로 대여하는 호스팅 서비스.

항목	내용
가격	M2 8GB ~$109/월 ~ M4 Pro ~$299/월
설정 난이도	높음 (서버 세팅·CI 연동 직접 구성)
빌드 제한	무제한

장점: 전용 하드웨어라 성능이 안정적이고 빌드가 무제한입니다. self-hosted runner로 붙일 수 있습니다.
단점: 월 고정 비용이 들고, OS·Xcode 업데이트 같은 머신 관리는 직접 해야 합니다. 빌드가 적으면 비효율적입니다.

5. AWS EC2 Mac

AWS가 제공하는 클라우드 Mac(Dedicated Host).

항목	내용
가격	mac2.metal ~$6.5/hr
최소 대여	24시간 (Dedicated Host 제약)
설정 난이도	높음

장점: AWS 인프라(VPC, IAM)와 통합됩니다.
단점: 24시간 최소 과금이 치명적입니다. 1시간만 써도 24시간분(약 $156)이 청구됩니다. 인스턴스를 stop해도 Dedicated Host를 release하기 전까지 과금이 계속됩니다.
결론: 간헐적인 CI 빌드 용도로는 부적합합니다.

6. Self-hosted Mac (사내 Mac)

사내에 Mac mini를 두고, GitHub Actions self-hosted runner를 설치해 빌드를 받는 방식.

항목 내용

항목	내용
가격	하드웨어 구매 비용만 (Mac mini M4 ~80만 원대)
설정 난이도	중간 (runner 설치 + 서비스 등록)
관리 부담	높음 (물리적 관리, OS/Xcode 업데이트)
빌드 제한	무제한

장점: 한 번 사두면 빌드 횟수·시간 추가 비용이 없습니다(전기료 제외). 스펙을 자유롭게 고를 수 있습니다.
단점: 전원·네트워크·OS 업데이트 같은 물리적 관리가 필요하고, 장애 시 빌드가 멈춥니다.

비교 요약

옵션	월 예상 비용	설정 난이도	관리 부담	빌드 제한
GitHub Actions 표준	~$37	낮음	없음	분당 과금
GitHub Actions xlarge	~$61	낮음	없음	분당 과금
Codemagic 무료	$0	중간	없음	500분/월
Codemagic 종량제	~$57	중간	없음	분당 과금
EAS Build 무료	$0	중간	없음	15빌드/월
MacStadium	$109~	높음	중간	무제한
Self-hosted Mac	$0 (하드웨어 별도)	중간	높음	무제한
AWS EC2 Mac	$4,680~	높음	높음	무제한

우리의 선택: Self-hosted runner

저희 상황을 정리하면 이랬습니다.

앱이 여러 개라 빌드 빈도가 꾸준히 높다. Stage QA 빌드, Prod 심사 빌드가 앱별로 쌓이면 월 수십 회를 쉽게 넘긴다.
이미 GitHub Actions를 메인 파이프라인으로 쓰고 있다. 별도 CI(Codemagic/EAS)를 이중 운영하고 싶지 않았다.
기존에 Fastlane 기반 코드 서명·TestFlight 업로드가 구성돼 있어, 이걸 그대로 가져가고 싶었다.
사무실에 상시 켜둘 수 있는 Mac이 확보돼 있었다.

분당 과금 옵션은 빌드가 늘수록 비용이 우상향합니다. 반면 self-hosted는 빌드를 아무리 많이 돌려도 추가 비용이 0입니다. 빌드 빈도가 높고 GitHub Actions를 이미 쓰는 팀에게는, 사내 Mac을 self-hosted runner로 붙이는 게 비용·일관성 양쪽에서 가장 합리적이었습니다.

핵심은 CI 파이프라인을 갈아엎지 않는다는 점입니다. 워크플로우에서 iOS 빌드 잡의 runs-on만 self-hosted로 바꾸면, 나머지 로직(태그 파싱, Doppler, Fastlane)은 그대로 재사용됩니다.

jobs:
  build:
    name: iOS (${{ inputs.app_dir }})
    runs-on: self-hosted   # macos runner → 사내 Mac
    steps:
      - uses: actions/checkout@v4
      # ... 이하 동일

하이브리드 구성 — macOS가 필요한 잡만 self-hosted로

self-hosted라고 해서 모든 잡을 Mac에서 돌릴 필요는 없습니다. 오히려 그러면 안 됩니다. Lint·타입체크·테스트·태그 파싱처럼 macOS가 필요 없는 작업까지 한 대뿐인 Mac에 몰아넣으면,

그게 곧 병목이 됩니다.

그래서 저희는 잡 단위로 runner를 나눴습니다.

잡	runner	이유
PR 체크(Lint/Typecheck/Test)	ubuntu-latest	macOS 불필요. GitHub 무료/저가 Linux
태그 파싱	ubuntu-latest	단순 셸 스크립트
Android 빌드	ubuntu-latest	JVM 빌드, Linux로 충분
iOS 빌드	self-hosted	Xcode 필요 → 사내 Mac만 가능

Linux로 충분한 작업은 전부 GitHub의 저렴한 Linux runner에 맡기고, macOS가 반드시 필요한 iOS 빌드 잡 하나만 사내 Mac으로 보냅니다. self-hosted Mac의 부하를 최소화하면서, macOS 자원이 꼭 필요한 곳에만 쓰는 구성입니다.

iOS 빌드 잡은 재사용 워크플로우(workflow_call)로 빼두고, Stage/Prod 워크플로우가 파라미터만 바꿔 호출합니다. self-hosted 전환 후에도 호출부는 그대로입니다.

# stage.yml — 태그를 파싱해 iOS/Android 빌드를 분기 호출
build-ios:
  needs: parse-tag
  if: needs.parse-tag.outputs.build_ios == 'true'
  uses: ./.github/workflows/_build-ios.yml   # 재사용 워크플로우
  with:
    app_dir: ${{ needs.parse-tag.outputs.app_dir }}
    lane: beta
    version: ${{ needs.parse-tag.outputs.version }}

self-hosted의 진짜 난관 — "환경이 영속적이다"

호스팅 runner와 self-hosted의 본질적 차이는 상태의 영속성입니다.

GitHub 호스팅 macOS runner는 매 빌드마다 깨끗한 새 가상머신에서 시작합니다. Xcode도, 키체인도, Ruby도 매번 초기 상태입니다. 반면 사내 Mac은 항상 같은 머신입니다. 지난 빌드의 흔적이 남아 있고, 로그인 키체인은 잠겨 있고, Ruby는 시스템 버전이 아니라 우리가 깔아둔 버전을 써야 합니다.

이 차이에서 self-hosted 특유의 문제들이 나옵니다. 하나씩 보겠습니다.

1. 코드 서명과 키체인 잠금 — 가장 큰 함정

self-hosted iOS 빌드에서 십중팔구 처음 막히는 지점입니다.

iOS 아카이브에는 배포 인증서로 코드 서명이 필요하고, 그 인증서의 개인 키는 macOS 키체인에 들어 있습니다. 그런데 GitHub Actions runner는 서비스(데몬)로 백그라운드 실행되기 때문에, 로그인 세션의 키체인이 잠긴 상태입니다. 이대로 codesign을 호출하면 인증서 키에 접근하지 못해 빌드가 실패합니다. 호스팅 runner에서는 매번 임시 키체인을 새로 만들어 쓰기 때문에 겪지 않는 문제입니다.

해결은 빌드 직전에 키체인을 잠금 해제하고, 코드 서명 도구가 프롬프트 없이 키에 접근하도록 권한을 여는 것입니다.

- name: Unlock keychain
  run: |
    KEYCHAIN_PW=$(doppler secrets get KEYCHAIN_PASSWORD --plain ...)
    # 로그인 키체인 잠금 해제
    security unlock-keychain -p "$KEYCHAIN_PW" \
      "$HOME/Library/Keychains/login.keychain-db"
    # codesign이 비대화식으로 키에 접근하도록 partition list 설정
    security set-key-partition-list -S apple-tool:,apple: -s \
      -k "$KEYCHAIN_PW" "$HOME/Library/Keychains/login.keychain-db"

set-key-partition-list가 핵심입니다. 이게 없으면 빌드 중 "키체인 접근을 허용하시겠습니까?" 같은 GUI 프롬프트가 떠서 CI가 무한 대기에 빠집니다. 사람이 없는 빌드 머신에서는 절대 응답되지 않습니다.

Fastlane 레인 안에서도 한 번 더 명시적으로 잠금을 풉니다.

lane :beta do
  api_key = app_store_connect_api_key(
    key_id: ENV["ASC_KEY_ID"], issuer_id: ENV["ASC_ISSUER_ID"],
    key_filepath: ENV["ASC_KEY_FILE"]
  )

  clear_derived_data                       # ← 영속 환경 정리(아래 참고)
  get_provisioning_profile(api_key: api_key)
  update_code_signing_settings(            # 자동 서명 끄고 수동 서명 고정
    use_automatic_signing: false,
    code_sign_identity: "iPhone Distribution",
    profile_name: lane_context[SharedValues::SIGH_NAME]
  )
  unlock_keychain(                         # 빌드 직전 재확인
    path: File.expand_path("~/Library/Keychains/login.keychain-db"),
    password: ENV["KEYCHAIN_PASSWORD"]
  )
  build_app(workspace: "...", scheme: "...", export_method: "app-store")
  upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: true)
end

인증서·프로비저닝은 App Store Connect API 키로 처리합니다. 키 파일은 GitHub Secrets에 base64로 넣어두고 빌드 시 디코드해 사용하므로, 머신에 자격증명을 영구 보관하지 않습니다.

2. 환경 격리 — 지난 빌드의 잔재 지우기

같은 머신을 재사용하니 이전 빌드의 DerivedData, Pods 캐시가 남아 유령 같은 빌드 실패를 만들 수 있습니다. 그래서 빌드 시작 시 clear_derived_data로 파생 데이터를 비우고, Pods는 명시적 캐시 키로만 관리합니다.

- name: Restore Pods cache
  uses: actions/cache@v4
  with:
    path: apps/${{ inputs.app_dir }}/ios/Pods
    key: pods-${{ runner.os }}-${{ hashFiles('.../Podfile.lock') }}
    restore-keys: pods-${{ runner.os }}-

Podfile.lock 해시를 키로 쓰기 때문에, 의존성이 바뀌지 않았으면 캐시를 재사용해 pod install을 건너뛰고, 바뀌면 자동으로 새로 받습니다. 영속 머신에서도 캐시가 결정적으로 동작합니다.

3. 런타임 PATH — 시스템 Ruby를 쓰지 않기

Fastlane/CocoaPods는 Ruby 위에서 돕니다. macOS 시스템 Ruby를 직접 쓰면 권한·버전 문제가 잦아, 저희는 rbenv로 깐 Ruby를 씁니다. 그런데 runner를 서비스로 띄우면 로그인 셸의 PATH 설정(.zshrc 등)을 타지 않아, rbenv가 PATH에 없습니다. 그래서 잡 안에서 직접 PATH를 넣어 줍니다.

- name: Setup rbenv PATH
  run: |
    echo "$HOME/.rbenv/shims" >> $GITHUB_PATH
    echo "$HOME/.rbenv/bin" >> $GITHUB_PATH

호스팅 runner였다면 신경 쓸 일이 없지만, 영속 머신에서는 "내 셸에선 되는데 CI에선 안 되는" 전형적인 PATH 함정입니다.

4. 시크릿 관리 — 머신에 값을 박아두지 않기

self-hosted라고 환경변수를 머신 .env에 박아두면, 그게 곧 관리 사각지대가 됩니다. 저희는 Doppler로 시크릿을 중앙 관리하고, 빌드 시점에 필요한 값만 내려받아 .env를 생성합니다. Firebase 설정(GoogleService-Info.plist), Sentry 토큰, 카카오 키 등 민감 파일도 전부 Doppler에서 주입합니다.

- name: Pull env from Doppler
  run: |
    doppler secrets download --no-file --format=env \
      --project ${{ inputs.doppler_project }} \
      --config ${{ inputs.doppler_config }} \
      --token "$DOPPLER_TOKEN" > .env

이렇게 하면 머신이 바뀌거나 runner를 새로 깔아도, 자격증명은 머신이 아니라 Doppler에 산다는 원칙이 유지됩니다.

runner 등록과 자동 복구

runner 설치 자체는 어렵지 않습니다.

mkdir actions-runner && cd actions-runner
curl -o runner.tar.gz -L https://github.com/actions/runner/releases/download/vX.Y.Z/actions-runner-osx-arm64-X.Y.Z.tar.gz
tar xzf runner.tar.gz
./config.sh --url https://github.com/ORG/REPO --token 

# launchd 서비스로 등록 → 재부팅 시 자동 시작
./svc.sh install
./svc.sh start

svc.sh install로 launchd 서비스 등록을 해두는 게 중요합니다. 사내 Mac은 정전·재부팅을 피할 수 없는데, 서비스로 등록해두면 부팅 후 runner가 자동으로 다시 붙습니다. 추가로 macOS 시스템 설정 → 에너지 → "정전 후 자동으로 시작" 을 켜두면, 전원만 복구되면 사람 개입 없이 빌드 머신이 살아납니다. 원격 관리는 SSH와 화면 공유(VNC)로 하고, 고정 IP 또는 VPN을 함께 둡니다.

운영하며 느낀 트레이드오프

self-hosted는 만능이 아닙니다. 비용을 관리 부담과 맞바꾸는 선택입니다.

좋았던 점

빌드 횟수가 늘어도 비용이 그대로다. 분당 과금의 심리적 압박이 사라졌다.
기존 GitHub Actions·Fastlane 자산을 100% 재사용했다. runs-on만 바꿨다.
머신을 우리가 통제하니 Xcode 버전, 캐시, 도구 체인을 원하는 대로 고정할 수 있다.

감수해야 하는 점

단일 장애점(SPOF): Mac 한 대가 멈추면 iOS 빌드가 전부 멈춘다. 빌드가 잦은 팀이라면 예비 머신이나 호스팅 runner로의 폴백 전략을 고려해야 한다.
물리·OS 관리: Xcode 업데이트, 디스크 정리, 인증서 갱신을 누군가는 챙겨야 한다.
동시성: 머신이 한 대면 빌드는 직렬화된다. 여러 앱을 동시에 빌드하려면 머신을 늘리거나 호스팅 runner를 섞어야 한다.

그래서 저희는 하이브리드가 정답이라고 봤습니다. Linux로 되는 일은 GitHub Linux runner에, macOS가 꼭 필요한 iOS 빌드만 사내 Mac에. 필요하면 언제든 runs-on을 macos-15로 되돌려 호스팅 runner로 폴백할 수 있다는 점이, self-hosted를 마음 편히 운영하는 안전판이 됩니다.

마치며

iOS 빌드 인프라에는 "무조건 이게 정답"인 옵션이 없습니다. 빌드 빈도가 낮으면 Codemagic·EAS 무료 tier나 GitHub 호스팅 runner가 관리 부담 없이 가장 편하고, 빌드가 잦고 이미 GitHub Actions를 쓰고 있다면 사내 Mac + self-hosted runner가 비용·일관성에서 유리합니다. 반대로 AWS EC2 Mac처럼 과금 구조가 CI에 맞지 않는 옵션은 후보에서 빠르게 지웠습니다.

self-hosted를 고른다면, 진짜 난이도는 runner 설치가 아니라 "환경이 영속적"이라는 데서 오는 코드 서명·키체인·PATH 문제에 있습니다. 이 글이 그 함정을 미리 피하는 데 도움이 되길 바랍니다.

Yarn Berry PnP 마이그레이션 — node_modules를 없앤 이유와 과정

Grace Noh — Fri, 17 Apr 2026 12:54:54 +0900

Nx 웹 모노레포에서 Yarn v1(Classic)을 Yarn v4(Berry) + PnP로 전환한 과정을 공유합니다. 왜 전환했는지, PnP가 뭔지, 마이그레이션 중 어떤 문제를 만났는지를 다룹니다.

들어가며

저희 팀은 Nx 기반 웹 모노레포를 Yarn v1(Classic)으로 운영하고 있었습니다. 큰 문제 없이 잘 돌아가고 있었는데, 마이그레이션 과정에서 axios, lodash, qs, uuid, react-router 같은 패키지가 package.json에 선언되지 않았는데도 사용되고 있었다는 사실을 발견했습니다.

이런 현상이 왜 발생하는지, 그리고 이를 해결하기 위해 Yarn Berry의 PnP(Plug'n'Play)로 전환한 과정을 정리합니다.

Yarn v1의 node_modules, 뭐가 문제인가

호이스팅과 유령 의존성

npm v3 이전에는 각 패키지가 자신의 node_modules/ 안에 의존성을 중첩으로 설치했습니다. 같은 패키지가 여러 번 설치되는 비효율이 있었고, 이를 해결하기 위해 npm v3과 Yarn v1은 호이스팅(hoisting) 을 도입했습니다.

호이스팅은 여러 패키지가 동일한 의존성을 사용할 때, 해당 의존성을 프로젝트 루트의 node_modules/에 한 번만 설치하는 방식입니다.

# 호이스팅 전 — 중복 설치
node_modules/
├── package-A/
│   └── node_modules/
│       └── lodash@4.17.21/    ← 복사본 1
├── package-B/
│   └── node_modules/
│       └── lodash@4.17.21/    ← 복사본 2

# 호이스팅 후 — 루트에 한 번만 설치
node_modules/
├── lodash@4.17.21/            ← 한 번만 설치
├── package-A/
├── package-B/

중복 설치 문제는 해결되었지만, 부작용이 생겼습니다. 직접 의존하지 않는 패키지를 import할 수 있게 된 것입니다. 이를 유령 의존성(Phantom Dependency) 이라 부릅니다.

// package.json에 lodash가 없는데도 동작함
// → 다른 패키지의 의존성이 호이스팅되어 루트에 있기 때문
import _ from 'lodash';

이게 왜 문제일까요?

호이스팅해준 패키지가 lodash 의존을 제거하면 → 우리 코드가 갑자기 깨짐
호이스팅해준 패키지가 lodash 버전을 바꾸면 → 의도하지 않은 버전이 사용됨
package.json만 보고는 어떤 패키지를 실제로 사용하는지 파악 불가

실제로 이번 마이그레이션에서 발견된 유령 의존성은 다음과 같습니다:

패키지	상황
axios	다른 패키지의 의존성으로 호이스팅되어 사용 중이었음
lodash	동일
qs	동일
uuid	동일
react-router	react-router-dom의 내부 의존성으로 호이스팅
@toast-ui/editor	@toast-ui/react-editor의 내부 의존성으로 호이스팅

이 패키지들은 언제든 예고 없이 사라지거나 버전이 바뀔 수 있었습니다. 지금까지 문제가 없었던 건 운이 좋았을 뿐입니다.

PnP(Plug'n'Play)란

Yarn Berry(v2+)가 도입한 의존성 해석 방식입니다. 핵심은 node_modules/를 생성하지 않는 것입니다.

node_modules 방식

node_modules/
├── react/           ← 실제 파일이 수만 개 복사됨
├── lodash/
├── axios/
└── ...

Node.js가 require('react')를 만나면 node_modules/ 디렉토리를 탐색하여 파일을 찾습니다. 파일이 수만 개이므로 설치도 느리고, 디스크도 많이 차지합니다.

PnP 방식

.pnp.cjs             ← 패키지 위치 매핑 파일
.yarn/cache/
├── react-npm-19.0.0-abc123.zip
├── lodash-npm-4.17.21-def456.zip
└── ...               ← 의존성이 zip으로 압축 저장

PnP에서는 .pnp.cjs 파일이 "이 패키지는 이 zip 파일 안에 있어"라고 Node.js에 직접 알려줍니다. 디렉토리 탐색이 필요 없습니다.

.pnp.cjs 안의 실제 매핑은 이렇게 생겼습니다:

["react", [
  ["npm:19.0.0", {
    "packageLocation": "./.yarn/cache/react-npm-19.0.0-abc123.zip/node_modules/react/",
    "packageDependencies": [
      ["react", "npm:19.0.0"],
      ["loose-envify", "npm:1.4.0"],
      ["object-assign", "npm:4.1.1"]
    ],
    "linkType": "HARD"
  }]
]],

PnP vs node_modules 비교

항목	node_modules	PnP
설치 속도	느림 (파일 수만 개 복사)	빠름 (zip 캐시 활용)
디스크 사용량	큼 (중복 설치)	작음 (zip 압축)
유령 의존성	가능 (호이스팅)	차단 (선언된 것만 접근 가능)
의존성 정확성	느슨함	엄격함

PnP는 각 패키지가 자신의 package.json에 선언한 의존성만 접근할 수 있도록 강제합니다. 선언하지 않은 패키지를 import하면 즉시 에러가 발생합니다. 유령 의존성을 원천 차단하는 것입니다.

Zero-Install

PnP의 추가 이점으로, .yarn/cache/와 .pnp.cjs를 git에 포함하면 clone 후 install 없이 바로 실행할 수 있습니다. 이를 Zero-Install이라 부릅니다.

오프라인 상태에서도 프로젝트 실행 가능
브랜치 전환 시 yarn install 불필요
의존성도 git으로 버전 관리 가능

.gitignore 설정

Zero-Install 사용 시:

.yarn/*
!.yarn/cache
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

Zero-Install 미사용 시:

.pnp.*
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

마이그레이션 과정

Before / After

항목	Before	After
Yarn 버전	v1.22.21	v4.13.0
모듈 해석	node_modules (hoisting)	PnP (Plug'n'Play)
의존성 저장	node_modules/ 폴더	.yarn/cache/ (zip 파일)
lockfile 형식	yarn.lock v1	yarn.lock v8

1. .yarnrc.yml 설정

nodeLinker: pnp

packageExtensions:
  "@toast-ui/editor@*":
    dependencies:
      prosemirror-transform: "*"

nodeLinker: pnp — 의존성 해석 방식을 PnP로 설정합니다. 사용 가능한 옵션:

pnp — PnP 모드. node_modules 없이 .yarn/cache의 zip 파일을 직접 참조
pnpm — pnpm 스타일의 심볼릭 링크 기반 node_modules 생성
node-modules — 기존 Yarn v1과 동일한 방식 (호환성 모드)

packageExtensions — 서드파티 패키지의 누락된 의존성을 보충합니다.

PnP는 각 패키지가 선언한 의존성만 접근을 허용하는데, 일부 서드파티 패키지는 내부적으로 사용하는 의존성을 package.json에 선언하지 않은 경우가 있습니다. 기존 node_modules 방식에서는 호이스팅 덕분에 우연히 접근이 되었지만, PnP에서는 에러가 발생합니다.

위 설정은 @toast-ui/editor가 prosemirror-transform을 내부적으로 사용하지만 자체 package.json에 선언하지 않은 것을 보충해줍니다. 이런 경우는 대부분 서드파티 패키지의 문제이며, 직접 작성하는 코드에서는 yarn add로 명시적으로 추가하면 됩니다.

2. 유령 의존성 해소

PnP로 전환하면 그동안 호이스팅으로 사용되던 미선언 패키지가 전부 에러를 뱉습니다. 하나씩 찾아서 명시적으로 추가했습니다.

yarn add axios lodash qs uuid react-router @toast-ui/editor
yarn add -D @types/lodash @types/qs @types/uuid

3. 미사용 패키지 정리

마이그레이션 과정에서 코드에서 사용하지 않는 패키지도 발견되었습니다. 이 기회에 정리했습니다.

패키지	비고
@prisma/client, prisma	코드에서 미사용
bcrypt, @types/bcrypt	코드에서 미사용
mysql2	코드에서 미사용
jsonwebtoken, @types/jsonwebtoken	코드에서 미사용
reflect-metadata	코드에서 미사용
register-service-worker	코드에서 미사용

이런 패키지들이 남아있었던 것도 node_modules 방식의 느슨함 때문입니다. 선언만 되어있고 실제로 사용하지 않아도 에러가 발생하지 않으니 방치된 것입니다.

4. VS Code SDK 설정

PnP에서 TypeScript가 정상 동작하려면 VS Code가 .yarn/cache/ 안의 zip 파일에서 타입 정보를 찾을 수 있어야 합니다. 기본적으로 VS Code는 node_modules/에서 TypeScript를 찾기 때문에 별도 설정이 필요합니다.

yarn dlx @yarnpkg/sdks vscode

실행하면 .yarn/sdks/ 폴더에 VS Code용 설정 파일이 생성됩니다. 이후 VS Code에서 Ctrl+Shift+P → "TypeScript: Select TypeScript Version" → "Use Workspace Version" 을 선택하면 됩니다.

이 설정은 레포에 포함되므로 한 번만 실행하면 됩니다. 다만 새로 clone한 개발자는 "Use Workspace Version" 선택을 잊지 않도록 안내가 필요합니다.

CI/CD 변경사항

항목	Before	After
설치 명령	yarn install --frozen-lockfile	yarn install --immutable
캐시 대상	node_modules/	.yarn/cache/
캐시 키	yarn.lock 해시	yarn.lock 해시 (동일)

변경 폭이 크지 않습니다. 설치 명령의 플래그 이름이 바뀌고, 캐시 대상 디렉토리만 바뀝니다.

개발자 가이드

달라진 점

항목	Yarn Classic	Yarn Berry
설치 후 생성	node_modules/ 폴더	.pnp.cjs + .yarn/cache/
lockfile 옵션	--frozen-lockfile	--immutable
패키지 실행	npx 또는 yarn	yarn dlx 또는 yarn

패키지 설치는 동일

yarn install     # 의존성 설치
yarn add axios   # 패키지 추가
yarn add -D jest # devDependency 추가

주의: 새 패키지 import 시

PnP는 package.json에 선언된 의존성만 접근을 허용합니다. 다른 패키지의 하위 의존성을 직접 import하면 에러가 발생합니다.

// ❌ 'qs'가 package.json에 없으면 에러
import qs from 'qs';

// ✅ 해결: yarn add qs 로 명시적 추가 후 import
import qs from 'qs';

node_modules 방식에서는 호이스팅 덕분에 우연히 동작하던 코드가 PnP에서는 에러를 뱉습니다. "다른 사람 코드에서는 되는데 내 코드에서만 안 돼요" 같은 상황이 사라집니다. 모든 의존성이 명시적이기 때문입니다.

왜 앱 프로젝트에서는 PnP를 안 쓰나

저희 팀은 웹 모노레포에서는 Yarn Berry PnP를, React Native 앱 모노레포에서는 pnpm을 사용합니다. PnP를 앱에서 쓰지 않는 이유는 React Native의 네이티브 빌드 도구가 node_modules/를 직접 탐색하기 때문입니다.

Metro 번들러: node_modules/를 탐색하여 JS 모듈을 resolve. PnP의 가상 경로를 이해하지 못함
CocoaPods / Gradle: node_modules/react-native/... 실제 경로로 네이티브 코드를 찾음
react-native CLI: autolinking에서 node_modules/ 안의 네이티브 모듈을 스캔

웹 프로젝트는 이런 제약이 없으므로 PnP의 이점을 최대한 활용할 수 있습니다.

마치며

Yarn Berry PnP 마이그레이션의 본질은 "선언하지 않은 건 쓸 수 없다" 라는 원칙을 강제하는 것입니다.

정리하면:

유령 의존성 원천 차단 — package.json에 선언한 것만 접근 가능
설치 속도 향상 — zip 캐시 활용, 파일 복사 없음
디스크 절약 — 의존성이 zip으로 압축 저장
Zero-Install 가능 — clone 후 install 불필요

마이그레이션 자체는 어렵지 않았습니다. .yarnrc.yml 설정, 유령 의존성 명시적 추가, VS Code SDK 설정이 전부입니다. 오히려 마이그레이션 과정에서 "이 패키지가 왜 선언 없이 쓰이고 있었지?"를 발견하는 것이 가장 큰 수확이었습니다. 지금까지 동작했던 게 호이스팅이라는 우연 덕분이었다는 것을 알게 되니까요.

node_modules/를 없애는 게 목적이 아니라, 의존성을 정확하게 관리하는 것이 목적입니다. PnP는 그 수단입니다.

웹 모노레포 CI/CD 개편기 — 라벨 배포에서 태그 배포로

Grace Noh — Fri, 17 Apr 2026 12:48:19 +0900

Nx 웹 모노레포에서 PR 라벨 기반 배포를 걷어내고, Git 태그 + Doppler로 배포 파이프라인을 재설계한 과정을 공유합니다.

들어가며

저희 팀은 Nx 기반 웹 모노레포에서 여러 앱을 운영하고 있습니다. 관리자 페이지, 백오피스, 로그인 페이지, 웹뷰 등 성격이 다른 앱들이 하나의 레포에 들어 있고, 각각 독립적으로 빌드/배포됩니다.

초기에는 PR 라벨로 배포를 트리거하고, 환경변수는 GitHub Secrets에 앱별로 등록하는 방식이었습니다. 앱이 2~3개일 때는 문제가 없었지만, 앱과 환경이 늘어나면서 관리가 어려워졌습니다.

이 글에서는 기존 방식의 문제점, 태그 기반 배포로의 전환, Doppler를 활용한 환경변수 관리, 그리고 최종 CI/CD 파이프라인 구조를 다룹니다.

기존 방식의 문제점

PR 라벨 기반 배포

기존에는 PR에 라벨을 붙여서 어떤 앱을 어떤 환경에 배포할지 결정했습니다.

PR에 "deploy:care-admin:dev" 라벨 → 머지 시 care-admin dev 배포
PR에 "deploy:care-admin:prod" 라벨 → 머지 시 care-admin prod 배포

앱이 적을 때는 괜찮았지만, 앱 × 환경 조합이 늘어나면서 문제가 생겼습니다.

문제 상황

라벨 조합 폭발	앱 7개 × 환경 2~4개 = 라벨 20개 이상. 어떤 라벨을 붙여야 하는지 헷갈림
실수 위험	라벨을 잘못 붙이면 의도하지 않은 앱/환경에 배포. 라벨을 빼먹으면 배포 누락
배포 시점 제어 불가	PR 머지 = 배포. "코드는 머지하되 배포는 나중에"가 불가능
이력 추적 어려움	"이 앱이 마지막으로 언제 배포됐지?" → PR 라벨을 하나하나 뒤져야 함

GitHub Secrets 직접 관리

앱별 환경변수(S3 버킷, CloudFront Distribution ID 등)를 GitHub Secrets에 개별 등록했습니다.

AWS_S3_BUCKET_CARE_ADMIN_DEV
AWS_S3_BUCKET_CARE_ADMIN_PROD
AWS_CLOUDFRONT_ID_CARE_ADMIN_DEV
AWS_CLOUDFRONT_ID_CARE_ADMIN_PROD
AWS_S3_BUCKET_BACKOFFICE_DEV
AWS_S3_BUCKET_BACKOFFICE_PROD
...

문제 상황

Secrets 수 폭발	앱 추가 시마다 S3 버킷, CloudFront ID, 기타 설정을 수동 등록
이중 관리	로컬 개발용 .env와 CI Secrets를 따로 관리. 값이 달라져도 모름
가시성 부족	GitHub Secrets는 값을 볼 수 없음. "이 값이 맞나?" 확인 불가

개편 방향

두 가지를 바꿨습니다.

배포 트리거: PR 라벨 → Git 태그
환경변수 관리: GitHub Secrets 직접 관리 → Doppler

태그 기반 배포

태그 네이밍 컨벤션

{앱이름}/{환경}/YYYY.MM.DD[.N]

날짜 기반 버전을 사용합니다. SemVer가 필요한 라이브러리가 아니라 배포 단위의 웹 앱이기 때문입니다.
같은 날 여러 번 배포 시 suffix를 붙입니다: .1, .2, ...

태그 설명

care-admin/dev/2026.04.17	care-admin을 dev 환경에 배포
care-admin/prod/2026.04.17	care-admin을 prod 환경에 배포
care-admin/prod/2026.04.17.1	같은 날 prod 재배포
rehab-manager/dev/2026.04.17	rehab-manager를 dev 환경에 배포

배포 방법

# CLI
git tag care-admin/dev/2026.04.17
git push origin care-admin/dev/2026.04.17

GitHub GUI로도 가능합니다. Releases → Draft a new release → 태그 이름 입력 → Create new tag → Publish release.

라벨 대비 장점

PR 라벨 Git 태그

배포 시점	PR 머지 시 (제어 불가)	태그 push 시 (원하는 시점)
이력 추적	PR 라벨 뒤지기	git tag -l "care-admin/prod/*"
실수 가능성	라벨 선택 실수	태그 이름이 곧 배포 대상이라 명확
롤백	이전 PR 찾아서 재배포	이전 태그의 커밋에서 새 태그 생성

Doppler로 환경변수 관리

Doppler는 환경변수를 중앙에서 관리하는 서비스입니다. 앱별, 환경별로 config를 만들어두면 로컬 개발과 CI 양쪽에서 동일한 환경변수를 사용할 수 있습니다.

기존 vs 개편

Before: 앱별 S3 버킷, CloudFront ID 등을 GitHub Secrets에 개별 등록

# 워크플로우에서 Secrets를 하나하나 꺼내서 주입
env:
  S3_BUCKET: ${{ secrets.AWS_S3_BUCKET_CARE_ADMIN_DEV }}
  CLOUDFRONT_ID: ${{ secrets.AWS_CLOUDFRONT_ID_CARE_ADMIN_DEV }}
  VITE_API_URL: ${{ secrets.VITE_API_URL_CARE_ADMIN_DEV }}

After: Doppler config 이름 하나만 넘기면 환경변수가 자동 주입

# 워크플로우에서 doppler run으로 실행하면 끝
- run: doppler run --project ipixel-admin --config dev_care_manager -- bash scripts/deploy.sh

GitHub Secrets에 남는 것

Doppler 도입 후 GitHub Secrets에는 인프라 인증 정보만 남깁니다.

Secret 용도

DOPPLER_TOKEN_*	앱/환경별 Doppler 접근 토큰
AWS_ACCESS_KEY_ID	AWS 인증
AWS_SECRET_ACCESS_KEY	AWS 인증
AWS_REGION	AWS 리전

앱별 S3 버킷, CloudFront ID, API URL 등은 전부 Doppler에서 관리합니다. 앱이 추가되어도 GitHub Secrets에 등록할 건 Doppler 토큰 하나뿐입니다.

로컬 개발에서의 사용

# 앱별 .env 파일 다운로드
nx run care-admin:doppler   # → .env 파일 생성

CI에서는 doppler run으로 환경변수를 직접 주입하므로 .env 파일이 필요 없습니다.

CI/CD 파이프라인 구조

워크플로우 파일

파일 역할

workspace-ci.yml	PR 시 nx affected --target=build로 영향받은 앱만 빌드 검증
workspace-cd.yml	태그 push 트리거. 태그 prefix로 앱/환경을 분기하여 cd.yml 호출
cd.yml	재사용 워크플로우. 실제 빌드 + 배포 실행

핵심은 workspace-cd.yml과 cd.yml의 분리입니다. workspace-cd.yml은 태그를 파싱해서 "어떤 앱을, 어떤 환경으로" 배포할지 결정하고, 실제 빌드/배포 로직은 cd.yml에 위임합니다.

cd.yml — 재사용 워크플로우

# cd.yml (재사용 워크플로우)
inputs:
  script-path     # 실행할 배포 스크립트 경로
  doppler-config  # Doppler config 이름

secrets:
  DOPPLER_TOKEN
  AWS_ACCESS_KEY_ID
  AWS_SECRET_ACCESS_KEY
  AWS_REGION

모든 앱의 배포가 동일한 흐름을 따릅니다:

코드 체크아웃
→ Doppler CLI 설치
→ node_modules 캐시 복원
→ AWS 인증
→ doppler run으로 환경변수 주입 + 배포 스크립트 실행

배포 스크립트 프로세스

각 앱의 배포 스크립트(scripts/deploy_*.sh)는 동일한 구조입니다:

#!/bin/bash
set -e

# 1. 의존성 설치
yarn install --immutable

# 2. 빌드 (Nx 캐시 스킵 — CI에서는 항상 fresh 빌드)
yarn build:care-dev --skip-nx-cache

# 3. 기존 파일 삭제 + 빌드 결과물 업로드
aws s3 rm s3://$S3_BUCKET --recursive
aws s3 sync dist/ s3://$S3_BUCKET --delete

# 4. index.html에 no-cache 메타데이터 설정
aws s3 cp s3://$S3_BUCKET/index.html s3://$S3_BUCKET/index.html \
  --metadata-directive REPLACE --cache-control "no-cache"

# 5. CloudFront 캐시 무효화
aws cloudfront create-invalidation \
  --distribution-id $CLOUDFRONT_ID --paths "/*"

S3_BUCKET, CLOUDFRONT_ID 등의 환경변수는 스크립트에 하드코딩하지 않습니다. doppler run이 Doppler config에서 가져와 자동으로 주입해줍니다. 덕분에 하나의 스크립트 구조로 모든 앱/환경을 처리할 수 있습니다.

set -e가 적용되어 있어서 빌드가 실패하면 S3 업로드 없이 즉시 중단됩니다.

CI 흐름 (PR)

PR이 main으로 열리면:

PR → nx affected --target=build → 변경된 앱만 빌드 검증

전체 앱을 빌드하지 않고 nx affected로 변경된 앱만 검증합니다.

CD 흐름 (배포)

태그가 push되면:

태그 push
→ workspace-cd.yml: 태그 prefix로 앱/환경 분기
→ cd.yml: Doppler config + 배포 스크립트 전달
→ doppler run으로 환경변수 주입 + 스크립트 실행
→ S3 업로드 + CloudFront 캐시 무효화

전체 구성 요약

항목 Before After

배포 트리거	PR 라벨	Git 태그 (앱/환경/날짜)
환경변수 관리	GitHub Secrets (앱별 개별 등록)	Doppler (중앙 관리)
CI 검증	전체 빌드	nx affected (변경된 앱만)
배포 워크플로우	앱별 개별 워크플로우	workspace-cd.yml + cd.yml 재사용 구조
롤백	이전 PR 찾아서 재배포	이전 태그 커밋에서 새 태그 생성

인프라 구성

항목 기술

호스팅	AWS S3 (정적 파일)
CDN	AWS CloudFront
환경변수	Doppler
빌드 도구	Nx + Vite
패키지 매니저	Yarn Berry (PnP)
CI/CD	GitHub Actions

주의사항

macOS 대소문자: macOS는 파일명 대소문자를 구분하지 않지만, CI(Linux)에서는 구분합니다. import 경로의 대소문자를 정확히 맞춰야 CI에서 빌드가 깨지지 않습니다.
빌드 실패 시 안전장치: 모든 배포 스크립트에 set -e가 적용되어 있어, 빌드가 실패하면 S3 업로드 없이 즉시 중단됩니다.
롤백 방법: 이전 태그의 커밋에서 새 태그를 생성하여 재배포하면 됩니다. 별도의 롤백 메커니즘은 필요 없습니다.

마치며

정리하면 이번 개편에서 바꾼 건 두 가지입니다.

배포 트리거를 PR 라벨에서 Git 태그로 — 배포 시점을 명시적으로 제어하고, 태그 자체가 배포 이력이 됩니다.
환경변수를 GitHub Secrets에서 Doppler로 — 로컬/CI 환경변수를 한 곳에서 관리하고, 앱 추가 시 Secrets 수동 등록 작업을 없앴습니다.

특별히 복잡한 기술을 도입한 것은 아닙니다. 태그 네이밍 컨벤션을 정하고, 재사용 워크플로우로 중복을 제거하고, 환경변수 관리를 외부 서비스로 위임한 것뿐입니다. 하지만 이 세 가지만으로도 "이 앱 어디에 배포된 거지?", "이 환경변수 값이 맞나?" 같은 질문이 사라졌습니다.

모노레포에서 앱이 늘어날수록 CI/CD 관리 비용은 빠르게 증가합니다. 비슷한 고민을 하고 계시다면, 태그 컨벤션 하나 정하는 것부터 시작해보시길 추천드립니다.

React Native 모노레포에서 앱 빌드 및 배포 전략 설계하기

Grace Noh — Fri, 17 Apr 2026 12:45:29 +0900

들어가며

저희 팀은 4개의 React Native 앱을 운영하고 있습니다. 처음에는 각각 독립된 레포지토리로 관리했지만, 앱이 늘어나면서 공통 코드 중복, 의존성 파편화, CI/CD 파이프라인 중복 등의 문제가 반복되었습니다. 이를 해결하기 위해 Nx + pnpm 기반 모노레포로 통합했고, 이 글에서는 통합 이후 빌드 타입 분리, 브랜치 전략, 태그 기반 배포, CodePush 운영 방식을 어떻게 설계했는지 다룹니다.

모노레포 자체의 마이그레이션 과정은 이 글의 범위를 벗어나므로, 빌드와 배포 전략에 집중합니다.

서버 환경 구성

제약 조건

설계에 앞서 몇 가지 제약 조건이 있었습니다.

서버팀 요구사항: 테스트 데이터가 Prod DB에 올라가면 안 됨 → Stage 서버 사용 필수
내부 테스트(QA)와 심사 제출이 별도의 빌드로 이루어져야 함
스토어 심사 제출은 수동으로 진행 (CI에서 빌드까지만)

환경 정의

환경 용도 비고

Dev	로컬 개발	개발자 로컬에서만 사용
Stage	내부 테스트 (QA, 기능 검증)	테스트 데이터 격리
Prod	스토어 릴리즈 / 심사 제출	실 운영 데이터

환경이 3개인 이유는 단순합니다. 로컬 개발 환경과 QA 환경에서 Prod 데이터를 건드리면 안 되고, QA에서 검증된 코드만 Prod 빌드로 만들어야 하기 때문입니다.

빌드 타입과 배포 트랙

빌드 타입 서버 엔드포인트 배포 대상 트리거 시점 배포 방식

Dev	Dev	로컬 실행	개발 중 상시	-
Stage	Stage	내부 테스트 업로드	QA / 기능 검증 시	CI 자동
Prod	Prod	스토어 심사 제출	릴리즈 확정 시	CI 빌드 → 수동 심사 제출

여기서 한 가지 자주 받는 질문이 있습니다.

"Stage에서 테스트한 빌드를 그대로 스토어에 올리면 안 되나요?"

안 됩니다. Stage 빌드와 Prod 빌드는 서버 엔드포인트가 다릅니다. Stage 빌드는 Stage 서버를 바라보고, Prod 빌드는 Prod 서버를 바라봅니다. 동일한 바이너리를 재사용할 수 없으므로 빌드가 2번 발생하는 것은 정상적인 플로우입니다.

브랜치 전략

왜 Trunk-based가 아닌가

모노레포에서 Trunk-based Development(main 단일 브랜치)를 쓰면 Stage/Prod 빌드 분리가 까다로워집니다. main에 머지하는 순간 Prod 배포가 트리거되면, 아직 QA가 끝나지 않은 코드도 함께 나갈 수 있기 때문입니다.

그래서 develop 브랜치를 두고, Stage/Prod 배포 시점을 분리하는 전략을 선택했습니다.

브랜치 종류

브랜치 분기 기준 머지 대상 용도

main	-	-	Prod 릴리즈된 안정 코드
develop	main	-	개발 통합 브랜치
feat/*	develop	develop	새 기능 개발
fix/*	develop	develop	일반 버그 수정
hotfix/*	main	main + develop	Prod 긴급 수정 (CodePush 포함)

브랜치 플로우

시나리오별 상세

1. 기능 개발 / 버그 수정

develop에서 분기 → 개발 → develop에 머지 → Stage 태그

develop에서 분기하고 develop으로만 머지합니다. 머지 후 Stage 태그를 찍어 내부 테스트 빌드를 트리거합니다.

2. QA 완료 후 릴리즈

develop → main 머지 → Prod 태그 → CI 빌드 → 수동 심사 제출

Stage 테스트 완료 후 develop을 main에 머지합니다. main 머지 시점에 Prod 태그를 찍어 빌드를 트리거하고, CI가 빌드 산출물(AAB/IPA)을 생성하면 수동으로 스토어에 심사 제출합니다.

3. Prod 긴급 수정 (hotfix)

main에서 분기 → 수정 → main에 머지 → CodePush 태그
                     → develop에도 머지 (동기화)

main에서 분기하는 이유는 Prod 코드 기준으로 수정해야 하기 때문입니다. main + develop 양쪽에 머지해야 합니다. develop에 안 넣으면 다음 릴리즈에서 수정이 빠집니다.

태그 기반 배포 전략

왜 브랜치가 아니라 태그인가

모노레포에서 앱별 독립 배포를 할 때, 브랜치 기반은 동작하지 않습니다.

브랜치는 레포 전체에 걸리기 때문에 앱별로 독립적인 릴리즈가 불가능합니다. 예를 들어 App A는 아직 Stage 테스트 중인데 App B는 심사를 올려야 하는 상황에서, 하나의 release 브랜치로는 이를 분리할 수 없습니다.

태그는 앱 이름을 포함하므로 앱별로 독립적인 빌드 트리거가 가능합니다.

브랜치 기반 태그 기반

앱별 독립 릴리즈	❌ 불가	✅ 가능
브랜치 수	앱 × 환경만큼 증가	develop, main 정도만 유지
빌드 타입 결정	브랜치로 결정	태그 패턴으로 결정

태그 컨벤션

{앱 이름}/{빌드 타입}/{버전}

app-a/stage/1.0.0         → App A Stage 빌드 → 내부 테스트
app-a/prod/1.0.0          → App A Prod 빌드 → 심사 제출
app-a/codepush/1.0.0-cp.1 → App A CodePush → OTA 배포
app-b/stage/2.1.0         → App B Stage 빌드 → 내부 테스트

이 패턴 하나로 어떤 앱을, 어떤 빌드 타입으로, 어떤 버전으로 배포하는지가 결정됩니다.

CodePush (OTA 업데이트)

네이티브 빌드 vs CodePush

네이티브 빌드 CodePush

배포 대상	바이너리 전체 (네이티브 + JS)	JS 번들 + 에셋만
심사 필요	✅ 필요	❌ 불필요
배포 속도	심사 대기 (1~3일)	즉시 반영
적용 범위	네이티브 코드 변경 포함	JS/에셋 변경만 가능

적용 범위: Prod 빌드에서만 사용

CodePush는 스토어에 릴리즈된 Prod 바이너리에 대한 핫픽스/긴급 패치 용도로만 사용합니다. Stage 환경에서는 CodePush를 사용하지 않고, 내부 테스트는 항상 네이티브 빌드로 진행합니다.

Stage에서 CodePush를 쓰지 않는 이유:

Stage는 내부 테스트용이라 네이티브 빌드를 다시 올리면 됨 (심사 대기 없음)
CodePush 환경을 Stage/Prod 이중으로 관리하면 복잡도만 증가
CodePush의 핵심 가치는 심사 없이 Prod 사용자에게 즉시 배포하는 것

CodePush 판단 기준

긴급 수정이 발생했을 때, CodePush로 배포할 수 있는지 판단하는 기준입니다.

하나라도 "Yes"이면 네이티브 빌드가 필요합니다. 모두 "No"일 때만 CodePush로 즉시 배포할 수 있습니다.

CI/CD 파이프라인

태그 → 빌드 → 배포 흐름

GitHub Actions 설정 예시

태그 패턴으로 앱과 빌드 타입을 파싱하는 방식입니다.

on:
  push:
    tags:
      - 'app-a/**'
      - 'app-b/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 태그에서 앱/빌드타입/버전 파싱
        run: |
          TAG=${GITHUB_REF#refs/tags/}
          APP=$(echo $TAG | cut -d'/' -f1)
          BUILD_TYPE=$(echo $TAG | cut -d'/' -f2)   # stage, prod, codepush
          VERSION=$(echo $TAG | cut -d'/' -f3)

      # Stage 빌드
      - name: Stage 빌드 → 내부 테스트 업로드
        if: contains(github.ref, '/stage/')
        run: # Stage 엔드포인트로 빌드 후 App Distribution / TestFlight 업로드

      # Prod 빌드
      - name: Prod 빌드 → 산출물 저장
        if: contains(github.ref, '/prod/')
        run: # Prod 엔드포인트로 빌드 후 산출물(AAB/IPA) 저장 (심사 제출은 수동)

      # CodePush (Prod만)
      - name: CodePush → Prod
        if: contains(github.ref, '/codepush/')
        run: # appcenter codepush release --deployment-name Production

전체 배포 플로우 요약

네이티브 빌드 경로 (일반 개발)

로컬에서 Dev 서버로 개발
PR → 코드 리뷰 → develop 머지
Stage 태그 → 자동 Stage 빌드 → 내부 테스트 업로드
QA 완료 → develop을 main에 머지
Prod 태그 → 자동 Prod 빌드 → 산출물 저장 → 수동으로 심사 제출

CodePush 경로 (Prod 핫픽스)

스토어 릴리즈 후 Prod에서 긴급 이슈 발견 (JS/에셋 수준)
main에서 hotfix/* 브랜치 분기 → 수정
main + develop 양쪽에 머지
CodePush 태그 → Prod 키로 CodePush 릴리즈 → 점진적 롤아웃

마치며

이 전략의 핵심은 태그 컨벤션 하나로 앱, 빌드 타입, 버전을 결정한다는 점입니다. 모노레포에서 여러 앱을 운영하면 배포 복잡도가 급격히 올라가는데, 태그 기반 배포는 이를 단순하고 예측 가능한 구조로 만들어줍니다.

정리하면:

서버 환경은 3개 (Dev / Stage / Prod), Stage와 Prod는 별도 빌드
브랜치는 2개 (develop + main), 배포 시점은 태그로 제어
태그 패턴 하나로 앱별 독립 배포 (앱/빌드타입/버전)
CodePush는 Prod 핫픽스 전용, JS/에셋 변경만 가능할 때 사용

이 구조로 전환한 뒤 "어떤 앱이 어떤 상태인지" 파악하는 것이 훨씬 명확해졌고, 배포 실수도 줄어들었습니다. 비슷한 고민을 하고 계신 팀에 도움이 되었으면 합니다.

실행 컨텍스트(Execution Context) 완벽 이해

Grace Noh — Sat, 18 Oct 2025 14:18:47 +0900

자바스크립트를 조금 깊게 공부하다 보면
“실행 컨텍스트(Execution Context)” 라는 용어가 꼭 등장합니다.

이 개념은 스코프(Scope), 클로저(Closure), this 바인딩 같은
자바스크립트의 핵심 원리를 이해하기 위한 기초 중의 기초예요.

실행 컨텍스트란?

“자바스크립트 코드가 실행되는 환경”

조금 더 구체적으로 말하자면,
자바스크립트 엔진이 코드를 실행할 때
변수, 함수, this, 스코프 정보 등을 관리하기 위한 객체입니다.

즉, 어떤 코드가 “어디서, 어떤 환경에서, 어떤 변수들을 가지고 실행되는가”
를 결정하는 일종의 실행 박스라고 보면 됩니다.

⚙️ 실행 컨텍스트의 종류

종류	설명
전역 컨텍스트 (Global Context)	코드가 처음 실행될 때 단 한 번 생성. 전역 변수, 함수 선언이 등록됨.
함수 컨텍스트 (Function Context)	함수가 호출될 때마다 새로 생성. 함수 내 지역 변수, 매개변수, 내부 함수 등이 등록됨.
Eval 컨텍스트 (Eval Context)	eval() 실행 시 만들어지지만, 실제 코드에서는 거의 사용하지 않음.

실행 컨텍스트의 내부 구성

하나의 실행 컨텍스트는 다음 세 가지로 이루어져 있습니다

Variable Environment (변수 환경)
- var로 선언된 변수와 함수 선언을 저장합니다.
- 코드가 실행되기 전에 미리 메모리에 등록됩니다. ( 호이스팅)
Lexical Environment (렉시컬 환경)
- let, const로 선언된 변수나 함수 표현식이 저장됩니다.
- 외부 환경 참조(Outer Environment Reference)를 포함하고 있어
  스코프 체인을 형성합니다.
This Binding (this 바인딩)
- 실행 컨텍스트가 “어떤 객체를 this로 바라볼지” 결정합니다.
  - 전역 실행 시: window(브라우저) or global(Node.js)
  - 함수 호출 시: 호출한 주체(객체)에 따라 다름
  - 생성자 함수 실행 시: 새로 만들어진 인스턴스

실행 컨텍스트의 생성과 동작 과정

함수가 호출될 때 실행 컨텍스트는 아래 순서로 동작합니다

1️⃣ 생성 단계 (Creation Phase)

새 실행 컨텍스트가 만들어짐
변수와 함수 선언이 메모리에 등록 (호이스팅)
this 바인딩 결정

이 단계에서는 변수들이 초기화는 되어 있지만 값은 undefined 상태예요.

2️⃣ 실행 단계 (Execution Phase)

코드가 한 줄씩 실행되며 실제 값이 할당되고 로직이 수행됩니다.

실행 컨텍스트 스택 (Call Stack)

자바스크립트 엔진은 실행 컨텍스트를 스택(Stack) 구조로 관리합니다.
가장 위에 있는 컨텍스트가 “현재 실행 중인 코드”입니다.

function a() {
  console.log('A');
  b();
}
function b() {
  console.log('B');
}
a();

실행 순서:

전역 컨텍스트 생성 (Global)
a() 호출 → a 컨텍스트 push
b() 호출 → b 컨텍스트 push
b() 종료 → pop
a() 종료 → pop
프로그램 종료 → Global 컨텍스트 pop

이런 구조 덕분에
자바스크립트는 함수 실행 순서를 추적하고,
비동기 처리나 에러 스택 트레이스 등을 효율적으로 관리할 수 있습니다.

예시로 이해하기

const x = 1;

function foo() {
  let y = 2;

  function bar() {
    console.log(x + y);
  }

  bar();
}

foo(); // 3

실행 흐름 살펴보기

1️⃣ 전역 실행 컨텍스트 생성

전역 변수 x와 함수 foo가 등록됩니다.
x는 const로 선언되었기 때문에 TDZ(Temporal Dead Zone) 를 거쳐
실제 코드 실행 시 값이 할당됩니다.
함수 foo는 선언 자체가 호이스팅되어 메모리에 등록됩니다.

2️⃣ foo() 호출 → 새로운 함수 실행 컨텍스트 생성

foo의 렉시컬 환경이 만들어지고, 지역 변수 y와 내부 함수 bar가 등록됩니다.
y는 let으로 선언되었기 때문에 블록 스코프 내에서만 유효합니다.

3️⃣ bar() 호출 → 또 하나의 실행 컨텍스트 생성

bar 내부에서는 x와 y를 찾습니다.
x는 전역 스코프(outer environment reference)에서,
y는 foo의 렉시컬 환경에서 발견됩니다.

4️⃣ console.log(x + y) 실행

탐색 순서: bar → foo → 전역(Global)
최종 결과: 1 + 2 = 3

✨ 마무리 요약

구분내용

정의	코드 실행에 필요한 정보를 담은 환경
종류	전역, 함수, eval
구성 요소	Variable Env, Lexical Env, this
동작 순서	생성(호이스팅) → 실행(코드 수행)
관리 방식	스택(Call Stack) 구조로 관리

결국, 실행 컨텍스트를 이해하면
자바스크립트의 스코프, 호이스팅, 클로저, this가 한눈에 연결됩니다.

즉, 실행 컨텍스트는 자바스크립트 엔진의 “두뇌”라고 할 수 있습니다.

브라우저 렌더링 최적화: Reflow와 Repaint 완벽 이해

Grace Noh — Sat, 18 Oct 2025 14:11:56 +0900

웹 성능을 이야기할 때 꼭 등장하는 단어가 있습니다.
바로 Reflow(리플로우) 와 Repaint(리페인트) 입니다.
이 두 개념은 브라우저가 화면을 그리는 과정의 핵심이며,
렌더링 성능 최적화의 출발점이기도 합니다.

Reflow란? (Layout 단계)

Reflow는 브라우저가 요소의 크기나 위치를 다시 계산하는 과정이에요.
즉, DOM 구조나 CSS 속성 중 레이아웃에 영향을 주는 변화가 있을 때 발생합니다.

예를 들어, 다음과 같은 상황이 Reflow를 유발합니다:

요소의 width, height, margin, padding 변경
새로운 DOM 요소 추가 / 제거
display 속성 변경
폰트 크기 변경
창 크기 조절(리사이즈)

Reflow는 화면의 구조를 완전히 다시 계산해야 하므로
비용이 크고, 성능 저하의 주요 원인이 됩니다.
특히 부모 요소의 레이아웃 변경은 자식 요소 전체에 영향을 주어
연쇄적으로 Reflow가 발생할 수 있습니다.

Repaint란? (Painting 단계)

Repaint는 요소의 크기나 위치는 그대로지만, 외형이 바뀔 때 발생합니다.
즉, 시각적인 스타일(appearance)만 다시 그리는 과정이에요.

다음과 같은 변경이 Repaint를 일으킵니다:

color, background-color, border-color 변경
visibility 토글
box-shadow, outline 등 시각적 속성 변경

Repaint는 Reflow보다는 가볍지만,
잦은 스타일 변경이나 애니메이션에서는 여전히 성능에 영향을 줄 수 있습니다.

⚖️ Reflow vs Repaint 한눈에 비교

구분	Reflow	Repaint
발생 조건	레이아웃(위치, 크기) 변경	외형(색상, 그림자 등) 변경
렌더링 단계	Layout 단계	Paint 단계
성능 비용	높음 ⚠️	중간 정도
예시	width, display, font-size	color, background, visibility

성능 최적화 팁

1️⃣ Reflow 최소화

DOM 접근/변경은 한 번에 묶어서 처리 (documentFragment 사용)
layout 관련 속성(offsetWidth, clientHeight)을 반복해서 읽지 않기
CSS 애니메이션은 transform, opacity 중심으로 구성해 GPU 가속 활용

2️⃣ Repaint 최소화

시각적 변화가 잦은 요소는
will-change: opacity, transform 속성으로 GPU 레이어 분리
보이지 않게 할 때 display:none 대신
opacity: 0 + pointer-events: none 사용 (Reflow 방지)

✨ 마무리 요약

Reflow는 “레이아웃 재계산”으로, 가장 비싼 연산이다.
Repaint는 “시각적 변경”으로, 상대적으로 덜 비싸다.
둘 다 빈번하게 일어나면 성능 저하의 주요 원인이 된다.
가능한 한 DOM 변경을 묶고, GPU 가속 가능한 속성을 사용하자.

결국 핵심은 “언제 브라우저가 다시 그려지는가”를 이해하는 것.
이 원리를 이해하면, 자연스럽게 성능 좋은 UI 코드를 작성할 수 있습니다.

클로저(Closure) 완벽 정리 — 자바스크립트 개발자라면 반드시 알아야 할 핵심 개념

Grace Noh — Sun, 12 Oct 2025 12:04:02 +0900

클로저(Closure)는 자바스크립트의 핵심 개념 중 하나로, 함수가 선언될 때의 환경(스코프)을 기억하는 함수를 말합니다.

1. 기본 개념

자바스크립트에서는 함수가 선언될 때의 스코프(lexical scope) 를 기억합니다.
이때, 내부 함수(inner function) 가 자신을 둘러싼 외부 함수(outer function) 의 변수에 접근할 수 있을 때,
그 관계를 유지한 채로 외부 함수가 종료된 이후에도 접근 가능한 구조 — 이것이 바로 클로저입니다.

2. 예시 코드로 이해하기

function makeCounter() {
  let count = 0; // 외부 함수의 지역 변수

  return function() { // 내부 함수 (클로저)
    count++;
    return count;
  };
}

const counter = makeCounter();

console.log(counter()); // 1
console.log(counter()); // 2
console.log(counter()); // 3

무슨 일이 일어나고 있을까?

makeCounter()가 실행되면 지역 변수 count가 생성됩니다.
내부 함수가 return되며, 이 함수는 count에 접근할 수 있는 권한을 가진 채 밖으로 나갑니다.
makeCounter()의 실행은 끝났지만, 내부 함수가 count를 참조 중이기 때문에 GC(가비지 컬렉터) 가 그 변수를 제거하지 않습니다.
그 결과, counter()를 호출할 때마다 count 값이 유지되고 증가합니다.

3. 클로저의 특징 요약

항목	설명
정의	함수가 선언될 당시의 스코프를 기억하여, 외부 함수의 변수에 접근할 수 있는 내부 함수
형태	함수 안의 함수
생성 시점	함수가 선언될 때(정의 시점)
소멸 시점	외부 함수가 끝나도 내부 함수가 참조 중이면 메모리에서 유지
주요 효과	데이터 은닉, 상태 유지, 모듈화 가능

4. 클로저의 대표적인 활용 예시

✅ (1) 데이터 은닉 / 캡슐화

function createAccount() {
  let balance = 0;

  return {
    deposit(amount) {
      balance += amount;
    },
    getBalance() {
      return balance;
    }
  };
}

const account = createAccount();
account.deposit(1000);
console.log(account.getBalance()); // 1000

→ 외부에서는 balance를 직접 수정할 수 없고, 오직 deposit() / getBalance()로만 접근 가능.

✅ (2) 이벤트 핸들러에서 상태 유지

function createClickCounter(button) {
  let count = 0;

  button.addEventListener('click', function() {
    count++;
    console.log(`Clicked ${count} times`);
  });
}

→ 각 버튼마다 클릭 횟수를 “기억”하는 클로저를 가짐.

✅ (3) React에서의 예시 (useState와 비슷한 원리)

function useCounter() {
  let count = 0;

  function increment() {
    count++;
    console.log(count);
  }

  return [() => count, increment];
}

const [getCount, increment] = useCounter();
increment(); // 1
increment(); // 2
console.log(getCount()); // 2

⚠️ 5. 주의할 점

문제	설명
메모리 누수	클로저가 너무 많은 변수를 오래 참조하면 메모리 점유가 계속 유지될 수 있음
의도치 않은 값 공유	반복문 안에서 var를 사용하면 모든 클로저가 같은 변수를 참조하게 됨
해결법	let 사용 또는 즉시실행함수(IIFE)로 스코프 분리

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 1000); // 3 3 3
}

for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 1000); // 0 1 2
}

⚛️ 6. React / TypeScript 실전 예제

React에서는 클로저가 매우 자주 사용됩니다.
특히 useEffect, useState, 이벤트 핸들러, 비동기 로직에서요.

✅ 예제 1: useEffect와 클로저

export default function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const interval = setInterval(() => {
      console.log("count:", count); // ⚠️ 클로저 발생
    }, 1000);

    return () => clearInterval(interval);
  }, []);

  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

여기서 무슨 일이 일어날까?

useEffect는 mount 시점에 한 번만 실행됩니다 ([]).
따라서 setInterval 안의 함수는 초기 렌더링 당시의 count를 기억하는 클로저를 만듭니다.
이후 버튼을 눌러도 count가 증가해도,
console.log("count:", count)는 0만 계속 찍습니다!

이건 바로 클로저의 “환경을 기억하는 성질” 때문이에요.

✅ 해결 방법

현재의 count 값이 필요하다면 함수형 업데이트나 ref를 이용해야 합니다.

useEffect(() => {
  const interval = setInterval(() => {
    setCount(c => {
      console.log("count:", c);
      return c + 1;
    });
  }, 1000);
  return () => clearInterval(interval);
}, []);

이렇게 하면 setCount의 인자 (c)가 매번 최신 상태를 전달받기 때문에 클로저 문제를 피할 수 있습니다.

✅ 예제 2: 이벤트 핸들러에서 상태 유지

import { useState } from "react";

export default function ToggleButton() {
  const [isOn, setIsOn] = useState(false);

  function handleClick() {
    // handleClick이 선언될 때의 스코프를 기억함 (클로저)
    console.log("현재 상태:", isOn);
    setIsOn(!isOn);
  }

  return <button onClick={handleClick}>{isOn ? "ON" : "OFF"}</button>;
}

동작 설명

handleClick 함수는 렌더링될 때마다 새롭게 만들어집니다.
하지만 이벤트 핸들러 내부의 isOn은 그 함수가 생성된 당시의 state 값을 기억합니다.
React는 매 렌더마다 새로운 클로저를 만들기 때문에,
이벤트가 트리거될 때 현재 렌더의 상태값을 참조하게 됩니다.

즉, React는 클로저를 매 렌더마다 새로 만들어서 “이전 상태 유지” 대신 “현재 상태 반영”을 합니다.

✅ 예제 3: 비동기 요청에서 클로저 주의하기

useEffect(() => {
  let isMounted = true;

  async function fetchData() {
    const res = await fetch("/api/data");
    const data = await res.json();

    if (isMounted) {
      setData(data);
    }
  }

  fetchData();

  return () => {
    isMounted = false;
  };
}, []);

⚠️ 왜 이렇게 하냐면:

fetchData가 실행되는 동안 컴포넌트가 언마운트되면 setData()를 호출하면 에러가 납니다.
isMounted 변수가 “현재 컴포넌트가 살아 있는지”를 클로저로 기억하고,
cleanup에서 false로 바꿔주는 패턴이에요.

⚛️ 7. 클로저, 그리고 useCallback / useMemo / 비동기 버그의 진짜 이유

1️⃣ 클로저와 React의 관계

React 컴포넌트는 렌더링될 때마다 함수가 새로 호출됩니다.
즉, 컴포넌트 내부의 모든 변수, 함수, state 참조가 매 렌더마다 새롭게 만들어집니다.

→ 따라서 “이전 렌더의 변수나 state를 참조하는 클로저”가 발생할 수 있어요.
React의 모든 훅은 사실상 “클로저 위에서 작동하는 구조”입니다.

⚙️ 2️⃣ useCallback / useMemo에서 클로저가 중요한 이유

(1) useCallback은 함수를 “메모이제이션”한다

const handleClick = useCallback(() => {
  console.log(count);
}, []);

❌ 문제:

[] 의존성 배열이 비어 있으면 count의 초기값만 기억한 클로저가 유지됩니다.
즉, 이후 count가 바뀌어도 handleClick은 옛날 count를 콘솔에 찍습니다.

✅ 해결:

의존성 배열에 count를 넣어야, React가 새로운 count를 클로저에 캡처한 새 함수를 만들어줍니다.

const handleClick = useCallback(() => {
  console.log(count);
}, [count]);

즉,

useCallback은 클로저의 “스냅샷”을 저장하는 훅,
deps는 “이 클로저를 언제 새로 만들어야 하는가”를 React에게 알려주는 장치예요.

⚙️ (2) useMemo도 똑같이 클로저를 기억한다

const doubled = useMemo(() => {
  console.log('memoized');
  return count * 2;
}, []);

[]로 두면 처음 count만 기억하고, 이후 변경돼도 다시 계산하지 않아요.
[count]를 넣으면 새 count로 다시 계산합니다.

useMemo의 콜백도 결국 클로저입니다.
React는 “의존성 배열을 기준으로 클로저를 새로 만들지 말지”를 결정하죠.

⚠️ 3️⃣ stale closure(오래된 클로저) 문제

개념

Stale Closure란, 오래된 변수 값을 기억하는 클로저 때문에
최신 state나 props를 읽지 못하는 버그를 말합니다.

예제: setTimeout 안에서 발생하는 stale closure

function Timer() {
  const [count, setCount] = useState(0);

  const start = () => {
    setTimeout(() => {
      console.log("Count:", count); // ❌ 항상 오래된 count!
    }, 2000);
  };

  return (
    <>
      <p>{count}</p>
      <button onClick={() => setCount(c => c + 1)}>+1</button>
      <button onClick={start}>Start</button>
    </>
  );
}

원인:

start 함수는 렌더링 시점의 count를 기억하는 클로저를 만듭니다.
2초 후 콜백 실행 시점엔 이미 여러 번 렌더링이 일어났을 수 있지만,
setTimeout 내부 클로저는 여전히 **“start 버튼을 눌렀던 순간의 count”**만 가지고 있습니다.

4️⃣ stale closure 방지 패턴 정리

✅ (1) 최신 값을 가져오려면 함수형 업데이트 사용

setCount(c => c + 1);

→ 이 패턴은 React가 내부적으로 최신 state를 전달해주기 때문에,
클로저에 오래된 state가 남아 있어도 안전합니다.

✅ (2) useRef로 최신 값을 추적하기

function Timer() {
  const [count, setCount] = useState(0);
  const countRef = useRef(count);

  useEffect(() => {
    countRef.current = count; // 항상 최신값으로 갱신
  }, [count]);

  const start = () => {
    setTimeout(() => {
      console.log("Count:", countRef.current); // ✅ 항상 최신값
    }, 2000);
  };

  return (
    <>
      <p>{count}</p>
      <button onClick={() => setCount(c => c + 1)}>+1</button>
      <button onClick={start}>Start</button>
    </>
  );
}

useRef는 렌더링과 무관하게 변수를 지속적으로 유지하므로, stale closure를 방지할 수 있습니다.

✅ (3) useEvent (React 19+ or useCallbackRef 패턴)

React 19부터 공식적으로 useEvent 훅이 추가됩니다.
이는 “항상 최신 클로저를 보장”하는 훅입니다.

import { useEvent } from "react";

function Timer() {
  const [count, setCount] = useState(0);

  const onTimeout = useEvent(() => {
    console.log("Count:", count); // ✅ 항상 최신 count
  });

  const start = () => setTimeout(onTimeout, 2000);

  return <button onClick={() => setCount(c => c + 1)}>+1</button>;
}

⚡️ useEvent는 렌더링 시점을 새로 캡처하지 않고, 내부적으로 최신 클로저를 유지합니다.

✅ (4) 커스텀 훅으로 안전한 비동기 로직 관리하기

function useSafeAsync(callback: () => void, deps: any[]) {
  const callbackRef = useRef(callback);

  useEffect(() => {
    callbackRef.current = callback;
  }, [callback]);

  return useCallback((...args: any[]) => {
    callbackRef.current(...args);
  }, []);
}

사용 예시:

const safeLog = useSafeAsync(() => console.log(count), [count]);

→ 이렇게 하면, 오래된 클로저가 아닌 항상 최신 상태를 참조하는 함수를 반환합니다.

요약 정리

클로저는 단순히 “함수 안의 함수”가 아니라,
함수가 선언될 당시의 스코프를 기억하는 함수예요.

이를 통해 함수 외부에서 접근할 수 없는 변수를 안전하게 유지하고,
필요할 때마다 그 값을 참조하거나 수정할 수 있죠.

즉, 클로저는

상태를 기억하는 함수,
데이터를 은닉하는 도구,
그리고 React의 useCallback / useMemo 같은 훅에서 핵심적으로 작동하는 메커니즘이에요.

하지만 너무 많은 변수를 참조하면 메모리 누수가 생길 수 있으니,
의도를 명확히 하고 꼭 필요한 경우에만 사용하는 습관이 중요합니다.

결국,

클로저를 이해한다는 건 자바스크립트의 “함수”와 “스코프”를 진짜로 이해한다는 뜻이에요.

[RN] 에러일지 - iOS17에서 App Crash 생기는 이유

Grace Noh — Wed, 24 Sep 2025 22:19:30 +0900

iOS 17 이상에서 UIGraphicsBeginImageContext()를 시도할 때, 이미지 사이즈가 (0, 0)인 경우 강제종료될 수 있으므로 UIGraphicsImageRenderer를 쓰는 것이 권장된다.

문제 패키지: react-native-fast-image, react-native-linear-gradient
react-native-linear-gradient v2.6.2 → v.2.8.3 upgrade
react-native-fast-image 는 현재 문제 메서드가 deprecated 되서는 안되는 환경 문제 이슈로 patch-package 사용해서 수정.
iOS 내부에서 UIGraphicsBeginImageContext() 사용된 함수 수정