reanimated-skia-performance

Reanimated + Skia Performance

Defaults

• Keep animation state on the UI thread: useSharedValue, useDerivedValue, worklets.
• Prefer Reanimated v4 declarative APIs; avoid legacy Animated.
• Prefer shared.get() / shared.set() over shared.value in app code (React Compiler friendly).
• Minimize JS↔UI crossings: avoid scheduleOnRN/runOnJS except for unavoidable side effects.
• For Skia, avoid per-frame React renders: pass SharedValues directly to Skia props/uniforms.

Workflow

1. Define the effect: what animates, duration/curve, interrupt rules, and gesture input.
2. Choose the renderer:
   • Use Reanimated styles for transforms/opacity/layout.
   • Use Skia for custom drawing, particles, gradients, runtime effects/shaders.
3. Choose the primitive:
   • Use Reanimated CSS transitions/animations for simple declarative style changes.
   • Use withTiming for tweens, withSpring for physics, withDecay for momentum.
   • Use Layout Animations for mount/unmount or layout changes.
4. Implement a single data flow on the UI thread (no setState per frame).
5. Do a perf pass (see references/perf-checklist.md).

Patterns

Shared values (React Compiler safe)

• Read: progress.get()
• Write: progress.set(withTiming(1))

import { useEffect } from 'react';
import { useSharedValue, withTiming } from 'react-native-reanimated';
 
const progress = useSharedValue

Reanimated v4 CSS transitions

Use for state-driven style changes where you do not need bespoke worklets.

Reanimated v4 CSS animations (keyframes)

Use for keyframe-like sequences (pulses, wiggles, repeated loops) without writing custom worklets.

Supported settings:

• animationName (keyframes object)
• animationDuration
• animationDelay
• animationTimingFunction
• animationDirection
• animationIterationCount
• animationFillMode
• animationPlayState

Dev-mode tuning panel (sliders)

Use sliders to tune animation configs or shader uniforms in __DEV__.

• Keep the tuning UI in a separate component to avoid re-rendering the animated scene.
• Write slider values into SharedValues via .set().
• For shader tuning: feed SharedValues into uniforms via useDerivedValue.
• For animation config tuning: store config params in SharedValues and read them when starting/restarting the animation.

See: references/dev-tuning.md.

Gesture-driven animation (Gesture Builder API)

Update shared values in onUpdate and drive visuals via animated styles.

Skia shader with animated uniforms

• Compile the runtime effect once (useMemo).
• Pass uniforms as a SharedValue<Uniforms> (Skia detects animated props by { value: T }).
• Do not access .value in your app code; pass the SharedValue object.

Common pitfalls

• Do not read shared values in React render; read them in worklets (useAnimatedStyle, useDerivedValue).
• Do not call runOnJS/scheduleOnRN in onUpdate unless you must.
• Do not allocate big arrays/paths/images per frame; memoize Skia objects and update via animated props.
• For runtime effects, always provide every uniform declared in the shader; missing uniforms throw.

References

• Reanimated v4 patterns and repo conventions: references/reanimated-v4.md
• Skia Canvas + runtime effects/shaders patterns: references/skia-shaders.md
• Dev-mode tuning panels (sliders): references/dev-tuning.md
• Performance checklist + debugging: references/perf-checklist.md