animation-with-worklets_skill

Overview

This skill provides concise React Native Worklets guidelines for scheduling functions between JavaScript and UI threads. It explains when to use scheduleOnRN and scheduleOnUI, recommended function-definition patterns, and how to avoid unnecessary worklet directives. The guidance targets animation, gesture handlers, and cross-thread communication in mobile apps.

How this skill works

The skill inspects common scheduling patterns and recommends using scheduleOnRN and scheduleOnUI from react-native-worklets instead of runOnJS/runOnUI. It enforces defining callback functions outside of inline handlers (typically with useCallback) and passing references plus direct arguments. It also advises against using the "worklet" directive except when explicitly required because scheduleOnUI performs conversion automatically.

When to use it

• When scheduling UI-thread work from the JS thread (animations, batched shared-value changes).
• When calling JS-thread logic from UI-thread worklets (state updates, API calls, navigation).
• Inside useAnimatedReaction, gesture handlers, or useAnimatedStyle where cross-thread calls occur.
• When batching multiple shared-value updates to reduce UI thread overhead.
• When implementing haptics, video controls, or other side effects triggered by gestures or animations.

Best practices

• Always define scheduled functions outside the callback and memoize with useCallback; pass the function reference instead of an inline arrow.
• Use scheduleOnRN for JS-thread work (state setters, API calls, navigation, haptics) and scheduleOnUI for UI-thread operations and batched shared-value updates.
• Pass arguments directly as separate parameters (rest args), not as an array. Example: scheduleOnRN(fn, arg1, arg2).
• Avoid the "worklet" directive in almost all cases; scheduleOnUI handles conversion automatically and gesture callbacks usually don’t need the directive.
• Prefer the react-native-worklets API over react-native-reanimated runOnJS/runOnUI for better type safety and consistent behavior.

Example use cases

• Update React state from a UI-thread reaction: useAnimatedReaction -> scheduleOnRN(stateSetter).
• Batch two shared-value updates on the UI thread: define a memoized batch function and call scheduleOnUI(batchUpdates).
• Trigger video controls or haptic feedback from a gesture handler using scheduleOnRN(controlFunction).
• Call navigation or API side effects from an animation callback via scheduleOnRN(navigationOrApiCall).
• Batch visual spring animations together on UI thread to reduce frame overhead with scheduleOnUI(batchAnimations).