Reanimated에서 자주 발생하는 실수와 성능 최적화

이번 글에서 살펴볼 내용

• Reanimated에서 가장 흔하게 발생하는 7가지 실수와 각각의 문제가 발생하는 내부적인 이유

• Reanimated를 제대로 활용하기 위해 필요한 성능에 대한 사고방식

• 애니메이션이 끊기거나 버벅일 때 어떻게 원인을 찾아야 하는지

• useAnimatedStyle의 동작 규칙과 내부에서 할 수 있는 것과 할 수 없는 것

• 이번 시리즈 전체에서 기억해야 할 핵심 내용 정리

실수 1. Worklet 내부에서 React State를 읽는 경우

// ❌ 문제가 되는 코드
const [isExpanded, setIsExpanded] = useState(false);
const height = useSharedValue(0);

const style = useAnimatedStyle(() => {
  // `isExpanded`는 React state에서 가져온 값
  // Worklet이 마지막으로 등록될 당시의 값을 Closure로 캡처합니다.
  // State가 빠르게 변경되면 오래된 값을 사용할 수 있습니다.
  return {
    height: isExpanded ? height.value : 0,
  };
});

// ✅ 올바른 패턴
const isExpanded = useSharedValue(false);

const style = useAnimatedStyle(() => {
  // SharedValue는 항상 최신 값을 동기적으로 읽을 수 있습니다.
  return {
    height: isExpanded.value ? height.value : 0,
  };
});

// 이벤트 핸들러에서
const handlePress = () => {
  isExpanded.value = !isExpanded.value;
};

실수 2. runOnJS를 호출하고 동기적인 결과를 기대하는 경우

// ❌ 동작하지 않는 코드 — runOnJS는 비동기입니다.
function onGestureEnd(event) {
  'worklet';

  let shouldDismiss = false;

  runOnJS((result) => {
    shouldDismiss = result; // 나중에 실행됩니다.
  })(evaluateDismissLogic(event.velocityY));

  if (shouldDismiss) {
    // 첫 실행에서는 항상 false
    offset.value = withSpring(DISMISS_TARGET);
  }
}

// ✅ 올바른 패턴
const shouldDismiss = useSharedValue(false);

function onGestureEnd(event) {
  'worklet';

  // UI Thread에서 바로 판단합니다.
  const willDismiss =
    Math.abs(event.velocityY) > VELOCITY_THRESHOLD ||
    offset.value > POSITION_THRESHOLD;

  if (willDismiss) {
    offset.value = withSpring(DISMISS_TARGET);

    // 애니메이션에 직접 영향을 주지 않는 부수 작업이라면
    // runOnJS를 사용해도 괜찮습니다.
    runOnJS(onDismissAnimationStart)();
  } else {
    offset.value = withSpring(0);
  }
}

실수 3. Layout 속성을 애니메이션하는 경우

// ❌ 부드럽게 애니메이션되지 않을 수 있습니다.
const style = useAnimatedStyle(() => ({
  width: interpolate(progress.value, [0, 1], [100, 200]),
  height: interpolate(progress.value, [0, 1], [50, 100]),
  marginTop: progress.value * 20,
}));

// ✅ scaleX를 사용해 width 변화처럼 보이게 만들기
const style = useAnimatedStyle(() => ({
  transform: [
    { scaleX: interpolate(progress.value, [0, 1], [0.5, 1]) }
  ],
}));

// ✅ translateX / translateY를 사용해 위치 변화 표현하기
const style = useAnimatedStyle(() => ({
  transform: [
    { translateY: interpolate(progress.value, [0, 1], [-20, 0]) }
  ],
}));

실수 4. 컴포넌트가 제거될 때 애니메이션을 취소하지 않는 경우

// ❌ 빠르게 unmount되는 상황에서 문제가 될 수 있습니다.
useEffect(() => {
  progress.value = withSpring(1, {}, () => {
    // 애니메이션이 끝나면 실행됩니다.
    runOnJS(setIsVisible)(true);
  });
}, []);

// ✅ unmount 시 애니메이션 취소
useEffect(() => {
  let mounted = true;

  progress.value = withSpring(1, {}, () => {
    if (mounted) {
      runOnJS(setIsVisible)(true);
    }
  });

  return () => {
    mounted = false;
    cancelAnimation(progress);
  };
}, []);

실수 5. 조건문이나 반복문 안에서 useSharedValue를 생성하는 경우

// ❌ 잘못된 사용
function MyComponent({ isAnimated }) {
  if (isAnimated) {
    const progress = useSharedValue(0);
  }
}

// ✅ 항상 최상위에서 생성
function MyComponent({ isAnimated }) {
  const progress = useSharedValue(0);

  // Hook 호출 여부가 아니라
  // 애니메이션 로직에서 isAnimated를 사용합니다.
}

실수 6. useAnimatedStyle의 규칙을 무시하는 경우

// ❌ useAnimatedStyle의 규칙을 위반하는 코드
const style = useAnimatedStyle(() => {
  console.log('frame!'); // 부수 효과 — 개발 환경에서는 초당 60번 실행될 수 있음

  runOnJS(logProgress)(progress.value); // 여기서 사용하면 안 됩니다.

  if (progress.value > 0.5) {
    someRef.current = true; // Worklet에서 Ref를 변경하는 것은 위험합니다.
  }

  // 특정 조건에서 return이 없음
  if (someCondition) {
    return { opacity: 1 };
  }

  // undefined가 반환되어 UI Thread 런타임에서 문제를 일으킬 수 있음
});

// ✅ 깔끔한 useAnimatedStyle
const style = useAnimatedStyle(() => {
  const p = progress.value;

  return {
    opacity: interpolate(p,[0, 1],[0, 1],Extrapolate.CLAMP),
    transform: [
      {
        scale: interpolate(p,[0, 1],[0.8, 1],Extrapolate.CLAM),
      },
    ],
  };
});

실수 7. DerivedValue를 지나치게 많이 만드는 경우

// ❌ 불필요하게 깊은 DerivedValue 체인
const a = useDerivedValue(() => progress.value * 2);
const b = useDerivedValue(() => a.value + 10);
const c = useDerivedValue(() => b.value * 0.5);
const d = useDerivedValue(() => c.value - 5);

// ✅ 하나의 계산으로 합치기
const result = useDerivedValue(() => {
  const p = progress.value;

  return (p * 2 + 10) * 0.5 - 5;
});

애니메이션이 끊길 때 원인을 찾는 방법

애니메이션이 끊기는 현상이 항상 발생하는가?
│
├── 항상 발생한다
│   ├── Layout 속성을 애니메이션하고 있는가?
│   │   └── width / height / margin 등
│   │
│   ├── 기존 Animated API에서 useNativeDriver를 사용하고 있는가?
│   │
│   └── Style Worklet에서 무거운 계산을 수행하고 있는가?
│
└── 특정 상황에서만 발생한다
    ├── 애니메이션 중에 React가 다시 렌더링되고 있는가?
    │   ├── State 업데이트나 네트워크 이벤트와 함께 문제가 발생하는가?
    │   └── 해결: 애니메이션 상태를 SharedValue로 이동하고
    │            React의 리렌더링과 분리한다.
    │
    ├── JS Thread가 과부하 상태인가?
    │   ├── 도구: Flipper > Performance > JS Thread CPU
    │   └── 해결: 중요하지 않은 JS 작업을 지연시키고
    │            애니메이션 실행을 Worklet으로 이동한다.
    │
    └── UI Thread가 과부하 상태인가?
        ├── 도구: Flipper > Performance > UI Thread CPU
        └── 해결: Worklet을 단순화하고
                 DerivedValue 체인의 깊이를 줄이며
                 useAnimatedStyle 내부의 무거운 작업을 확인한다.

성능을 이해하기 위한 핵심 사고방식

1. JS Thread 비용을 0에 가깝게 만든다

2. SharedValue를 경계로 생각한다

• UI → JS: runOnJS — 비동기

• JS → UI: JS에서 SharedValue에 값을 작성 — JSI를 통한 동기적인 접근

3. Worklet은 Closure가 아니라 함수라고 생각한다

4. Layout이 아니라 Transform을 애니메이션한다

이걸 Layout 변경(width, height, margin)이 아니라 Transform(scale, translate)으로 표현할 수 있을까?

5. Spring은 duration이 아니라 물리적인 종료 조건으로 조절한다

Reanimated 핵심 정리

SharedValue
  - C++에 존재하며 JSI를 통해 JS Thread와 UI Thread에서 접근 가능
  - 읽기와 쓰기는 동기적으로 이루어지며 Mutex로 보호됨
  - 값이 변경되면 등록된 Animation Worklet에 알림
  - React 리렌더링을 발생시키지 않음


useAnimatedStyle
  - UI Thread에서 Worklet으로 실행됨
  - 구독하고 있는 값이 변경되면 실행
  - 반드시 Style 객체를 반환하는 순수 함수여야 함
  - 부수 효과나 runOnJS 호출을 수행하면 안 됨
  - 결과는 React Reconciler를 거치지 않고 Native View에 직접 적용


useDerivedValue
  - UI Thread에서 동작하는 반응형 계산
  - 참조하고 있는 SharedValue를 구독하고 값이 변경되면 다시 실행
  - 결과 역시 SharedValue
  - 다른 DerivedValue와 연결해서 사용할 수 있음
  - React의 개입 없이 동작


withSpring / withTiming / withDecay
  - 매 프레임 다음 값을 계산하는 Animation Driver
  - withSpring: 감쇠 조화 진동 모델을 사용하는 물리 기반 애니메이션
  - withTiming: Easing을 이용해 일정 시간 동안 값을 변화
  - withDecay: 속도를 기반으로 점차 감속
  - cancelAnimation(sv): 실행 중인 Animation Driver를 즉시 중단


runOnJS(fn)(args)
  - fn을 Main JS Thread에서 실행하도록 스케줄링
  - 비동기적으로 동작하므로 JS 측 값을 동기적으로 읽는 용도로 사용할 수 없음
  - State 업데이트, Callback, Analytics, Haptic 등에 사용


runOnUI(fn)(args)
  - fn을 UI Thread 런타임에서 실행하도록 스케줄링
  - JS 측에서는 비동기적으로 실행 요청
  - UI Thread에서 실행될 때는 해당 런타임에서 동기적으로 실행


useAnimatedReaction(selector, handler)
  - selector의 결과가 변경되면 UI Thread에서 handler 실행
  - 서로 다른 SharedValue 간의 반응이나 조건부 애니메이션 실행에 사용
  - JS 측 부수 효과가 필요하다면 handler 내부에서 runOnJS 사용


Animatable Properties
  - opacity
  - transform (translate, scale, rotate, skew)
  - 그 외의 Layout 속성은 Layout 계산이 필요하므로 Layout Animation 사용


성능 확인 기준
  - UI Thread FPS 하락 → Worklet이 너무 무거운지 확인
  - JS Thread FPS 하락 + 애니메이션 정상 → React / JS 코드가 느린 것
  - 두 Thread 모두 하락 → Layout 재계산을 발생시키는 애니메이션이나
                              전체적인 CPU 부하 확인

마무리하며

원문

React Native Reanimated Internals, Part 4: Common Mistakes, Performance Mental Models, and the…

The most humbling part of deeply understanding a library is realising how many subtle mistakes you’ve been making in confidence.

https://medium.com/@debdut.saha.1/react-native-reanimated-internals-part-4-common-mistakes-performance-mental-models-and-the-be83c9276b5b