'worklet';

참고: runOnJS와 runOnUI는 현재 deprecated되었으며, scheduleOnRN과 scheduleOnUI가 이를 대체합니다. 다만 기존 문서와 예제에서 runOnJS와 runOnUI가 여전히 널리 사용되고 있는 만큼, 이 글에서도 개념 설명을 위해 기존 명칭을 그대로 사용하겠습니다.

이번 글에서 살펴볼 내용

• 'worklet' 지시문이 Reanimated의 Babel 플러그인에서 실제로 어떤 변환을 일으키는지

• Worklet이 어떻게 직렬화되어 UI Thread 런타임으로 전달되는지

• Reanimated의 C++ 레이어는 무엇을 관리하고, 왜 필요한지

• runOnUI와 runOnJS는 어떻게 런타임 사이를 이동하는지

• Worklet의 Closure가 일반적인 JavaScript Closure와 다르게 동작하는 이유

'worklet'은 실제로 무엇을 하는가

"이 함수를 UI Thread 런타임에서 실행할 수 있는 형태로 변환해 주세요."

function calculateOffset(progress) {
  'worklet';
  return progress * 200 - 100;
}

• 함수의 소스 코드를 추출합니다. 실제 함수 본문의 코드를 가져옵니다.

• 클로져를 캡처합니다. 외부 스코프에서 참조하는 변수들을 찾아 직렬화합니다.

• __workletHash를 생성합니다. 소스 코드를 기반으로 해당 Worklet을 식별하기 위한 고유한 값을 생성합니다.

• __initData 객체를 추가합니다. 소스 코드 문자열, 캡처한 Closure 값, 각종 메타데이터를 담습니다.

function calculateOffset(progress) {
  'worklet';
  return progress * 200 - 100;
}

calculateOffset.__closure = {}; // 이 경우 캡처한 외부 변수가 없음
calculateOffset.__workletHash = 1234567;

calculateOffset.__initData = {
  code: `function calculateOffset(progress){return progress*200-100;}`,
  location: 'MyComponent.js:3',
};

Reanimated C++ 레이어: 전체 동작을 조율하는 오케스트레이터

┌────────────────────────────────────────────────────┐
│                  Main JS Thread                    │
│  ┌──────────────────────────────────────────────┐  │
│  │ Reanimated JS (worklet factory, API layer)   │  │
│  └─────────────────────┬────────────────────────┘  │
└────────────────────────┼───────────────────────────┘
                         │ JSI bindings
┌────────────────────────▼───────────────────────────┐
│             C++ Core (NativeReanimated)            │
│  - SharedValue storage & synchronisation           │
│  - Worklet runtime management                      │
│  - Animation frame scheduling                      │
│    (Choreographer / CADisplayLink)                 │
│  - View prop updater                               │
│    (direct native prop mutation)                   │
│  - Event handler registration                      │
└────────────────────────┬───────────────────────────┘
                         │ JSI bindings
┌────────────────────────▼───────────────────────────┐
│                UI Thread JS Runtime                │
│  ┌──────────────────────────────────────────────┐  │
│  │ Evaluated worklets (animation logic)         │  │
│  │ useAnimatedStyle callbacks                   │  │
│  │ gesture handlers                             │  │
│  └──────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────┘

• SharedValue 저장소를 관리합니다. 두 런타임에서 접근할 수 있는 애니메이션 값을 저장하고 동기화합니다.

• 애니메이션 콜백을 스케줄링합니다. Android에서는 Choreographer, iOS에서는 CADisplayLink와 연결하여 렌더링 과정에서 각 프레임마다 Worklet이 실행되도록 합니다.

• UI Thread Runtime을 관리합니다. JavaScript 엔진 인스턴스를 생성하고 Worklet 코드를 평가하며, Worklet이 JSI를 통해 SharedValue를 읽고 쓰거나 Native 메서드를 호출할 수 있도록 연결합니다.

• View Prop Updater를 관리합니다. opacity, transform 등의 Native View 속성을 React의 Reconciler를 거치지 않고 직접 변경할 수 있는 경로를 제공합니다.

runOnUI와 runOnJS: Runtime 경계를 넘나들기

// runOnUI: main thread → UI thread
function triggerHaptic() {
  'worklet';
  // This runs on the UI thread
  runOnJS(fireHapticFeedback)(); // schedule back to main thread
}

function fireHapticFeedback() {
  // This is a regular function — runs on main JS thread
  HapticFeedback.trigger('impactLight');
}

// From your component:
runOnUI(triggerHaptic)();

// ❌ 흔히 하는 오해
function onGestureUpdate(event) {
  'worklet';

  let currentState;

  runOnJS((s) => {
    currentState = s;
  })(someReactState);

  // currentState는 여전히 undefined
  // runOnJS는 비동기적으로 실행되기 때문입니다.
  if (currentState === 'locked') return;
}

// ✅ 올바른 방법
const isLocked = useSharedValue(false);

function onGestureUpdate(event) {
  'worklet';

  if (isLocked.value) return; // SharedValue 읽기는 동기적으로 수행됩니다.

  // ... handle gesture
}

Worklet의 Closure: Snapshot 문제

function MyComponent({ threshold }) {
  const offset = useSharedValue(0);

  // ❌ 주의해야 할 패턴
  const style = useAnimatedStyle(() => {
    // threshold는 Closure로 캡처됩니다.
    // 하지만 UI Thread Runtime에는 어떤 threshold 값이 전달되어 있을까요?

    return {
      transform: [
        {
          translateX: offset.value > threshold ? 100 : 0,
        },
      ],
    };
  });

  // threshold prop이 변경되더라도
  // UI Thread의 Worklet은 다시 등록되기 전까지
  // 이전 threshold 값을 가지고 있습니다.
}

// ✅ 자주 변경되는 값을 위한 안전한 패턴
const thresholdShared = useSharedValue(threshold);

// Prop과 SharedValue를 동기화
useEffect(() => {
  thresholdShared.value = threshold;
}, [threshold]);

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

Worklet은 매 프레임 어떻게 실행되는가

// 매 프레임의 실행 과정
Android Choreographer / iOS CADisplayLink 실행
        │
        ▼
Reanimated C++ 프레임 콜백
        │
        ▼
활성화된 애니메이션이 있는 SharedValue 각각에 대해:
  │
  ├── 애니메이션 시계에 따라 SharedValue 업데이트
  │    (spring, timing 등)
  │
  ▼
useAnimatedStyle이 등록된 각 컴포넌트에 대해:
  │
  ├── UI Thread Runtime에서 Style Worklet 실행
  │
  ├── Worklet이 SharedValue를 동기적으로 읽음
  │
  ├── 새로운 Style 객체 반환
  │
  ▼
C++ ViewPropUpdater가 Style을 Native View에 직접 적용
        │
        ▼
프레임 렌더링 — 사용자는 변경된 애니메이션을 확인

Worklet이 너무 느리다면 어떻게 될까?

• 큰 배열을 순회하는 작업

• 복잡한 문자열 처리

• UI Thread를 블로킹하는 동기적인 JSI 함수 호출

// ✅ 이상적인 Worklet — 순수하고 빠르며 상태가 없음
const style = useAnimatedStyle(() => {
  return {
    opacity: interpolate(
      progress.value,
      [0, 1],
      [0, 1],
      Extrapolate.CLAMP
    ),
    transform: [{ scale: progress.value }],
  };
});

// ❌ 위험한 Worklet — 너무 많은 일을 수행함
const style = useAnimatedStyle(() => {
  const result = heavyArray.reduce((acc, item) => {
    // 이렇게 하지 않는 것이 좋습니다.
    // UI Thread에서 초당 60번 실행될 수 있습니다.
    return acc + item.value;
  }, 0);

  return { opacity: result };
});

Worklet 정리

• 'worklet' 지시문은 Babel 변환을 일으켜 함수의 소스 코드와 Closure Snapshot을 추출하고, 이를 UI Thread Runtime에서 다시 평가할 수 있도록 합니다.

• UI Thread에서 실행되는 Worklet은 원래 함수에 대한 참조가 아니라 복사본입니다. 따라서 실시간으로 변하는 값을 참조하는 것이 아니라 등록 시점의 Snapshot을 캡처합니다.

• Reanimated의 C++ 레이어는 SharedValue 저장소, Worklet Runtime 관리, 프레임 스케줄링, Native View 직접 업데이트 등 전체 동작을 조율합니다.

• runOnJS는 비동기적으로 동작하므로 Worklet 내부에서 메인 JS Thread의 값을 동기적으로 읽는 용도로 사용할 수 없습니다.

• Worklet의 Closure는 등록 시점의 값을 캡처합니다. 애니메이션 도중 변경되는 값이라면 Closure 대신 SharedValue를 사용해야 합니다.

• 매 프레임의 실행 과정은 UI Thread에서 처리됩니다. SharedValue에 대한 JSI 읽기, Worklet 실행, Native View 변경까지 React의 개입 없이 이루어집니다.

다음 글에서는

원문

React Native Reanimated Internals, Part 2: Worklets, the UI Thread Runtime, and How Your Code…

There’s a line of code I’ve written hundreds of times without fully appreciating what it does:

https://medium.com/@debdut.saha.1/react-native-reanimated-internals-part-2-worklets-the-ui-thread-runtime-and-how-your-code-5e3c19634abd