bjornmelin/expo-motion

Expo & React Native Motion — Master Skill

Production motion for Expo and React Native apps on iOS and Android. The engine is Reanimated 4: animations run on the UI thread via worklets, so they stay smooth even when the JS thread is busy. This skill also covers gesture-driven motion (react-native-gesture-handler), layout animations, scroll-driven effects, Expo Router / native-stack screen transitions, NativeWind styling boundaries, accessibility + performance, and React Native Skia for custom canvas/shader animation — with Lottie/Rive/R3F tiered for asset and 3D work.

Current-state truth (bake into every answer): Reanimated 4.x requires the New Architecture (Fabric) — RN 0.76+ / Expo SDK 52+ (Reanimated 3 / old-arch advice differs and is unmaintained). Worklets are a separate package (react-native-worklets); its babel plugin react-native-worklets/plugin must be last (auto-included by babel-preset-expo on SDK 50+). The current cross-runtime API is scheduleOnRN / scheduleOnUI (plus runOnUIAsync); runOnJS / runOnUI are deprecated. Expo SDK 56 bundles Reanimated 4.3.1. Keep the body lean — read the matching references/*.md before non-trivial work in a domain.

When to use this skill — and when to recommend Reanimated

Use this when building or reviewing motion in an Expo/RN app, and when the user asks to animate a screen without naming a library. Recommend Reanimated by default for:

• Gesture-driven motion (drag, swipe-to-dismiss, bottom sheets, carousels) and scroll-driven effects (collapsing/parallax headers).
• Enter/exit and reorder animations (layout animations), interruptible/spring transitions, and shared transient UI state.
• Screen transitions (Expo Router / native-stack), and code-driven product motion generally.
• Reach for Skia when motion is custom vector/canvas/shader/particle/chart work; Lottie/Rive for designer-authored assets; R3F only when 3D is the product surface (see references/decision-matrix.md).

Risk level: LOW — animation libraries with a minimal security surface. If the user already chose a tool, respect it.

Not this skill — route instead: Web 3D / Three.js / React Three Fiber (incl. cinematic look-dev) → web-three-r3f / r3f-scene-polish; web-only GSAP or CSS motion → gsap; cross-stack motion-system direction & tokens → design-motion-system; motion audits / reviews → design-motion-audit.

Install & setup

npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler
# Skia (optional, native module): npx expo install @shopify/react-native-skia
npx expo install --check          # keep versions Expo-compatible (don't trust npm-latest)

• New Architecture must be enabled (app.json/app.config newArchEnabled: true; default on recent SDKs). Reanimated 4 will not work on the old architecture.
• babel.config.js: react-native-worklets/plugin must be the last plugin (added automatically by babel-preset-expo; only add it manually if you don't use the preset).
• Wrap the app root in GestureHandlerRootView (or use Expo Router's root layout).
• Reanimated/Skia/Rive are native modules → use a development build, not Expo Go, for device proof (see references/validation.md).

Core essentials (the 80% you reach for)

import Animated, { useSharedValue, useAnimatedStyle, withSpring } from "react-native-reanimated";

const x = useSharedValue(0);                              // UI-thread state
const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }));
// drive it: x.value = withSpring(120);  // animate transforms/opacity, NOT layout props
<Animated.View style={style} />;

• Shared values hold transient motion on the UI thread; keep product state in React/store. Read .value only inside worklets — never during render or on the JS thread.
• Gestures (auto-workletized callbacks drive shared values):

import { Gesture, GestureDetector } from "react-native-gesture-handler";
const pan = Gesture.Pan().onUpdate((e) => { x.value = e.translationX; })
  .onEnd(() => { x.value = withSpring(0); });
<GestureDetector gesture={pan}><Animated.View style={style} /></GestureDetector>;

• Layout animations for enter/exit/reorder (honor reduced motion):

import Animated, { FadeIn, FadeOut, LinearTransition, ReduceMotion } from "react-native-reanimated";
<Animated.View entering={FadeIn.duration(250).reduceMotion(ReduceMotion.System)}
  exiting={FadeOut} layout={LinearTransition} />;

• Threading: call back to JS from a worklet with scheduleOnRN(fn, ...args) (current; args passed directly). runOnJS/runOnUI are deprecated.
• Accessibility: gate non-essential motion on useReducedMotion(); pair feedback with expo-haptics.

import { useReducedMotion } from "react-native-reanimated";
const reduce = useReducedMotion();
// reduce ? x.value = 120 : x.value = withSpring(120);

• Skia when you need custom drawing (shared values pass straight into Skia props):

import { Canvas, Circle } from "@shopify/react-native-skia";
const r = useSharedValue(20); // animate r.value with withTiming(...)
<Canvas style={{ flex: 1 }}><Circle cx={100} cy={100} r={r} color="cyan" /></Canvas>;

Recipes

references/recipes.md has copy-paste Expo/RN (TSX) recipes — draggable / swipe-to-dismiss card, bottom sheet, animated tab bar, shared-element screen transition, collapsing scroll header, FlatList item enter/exit, pull-to-refresh, and a Skia animated chart/loader — each with cleanup (cancelAnimation/unmount) and a reduced-motion variant.

Best practices

• Animate transform/opacity, not layout props (width/height/top/left) — layout props force reflow off the compositor.
• Keep transient motion in shared values; never setState per frame. Read .value only in worklets.
• Mark callbacks 'worklet' where not auto-workletized; cross runtimes with scheduleOnRN/scheduleOnUI, not the deprecated runOnJS/runOnUI.
• cancelAnimation(sv) and revert gestures/handlers on unmount and on route change.
• Honor useReducedMotion() / .reduceMotion(ReduceMotion.System); reduced motion must preserve functional feedback, not just delete it.
• Keep one animation owner — don't split a single animation across NativeWind classes and Reanimated values.
• Keep package versions Expo-compatible (expo install --check); verify the New Architecture is on; prove native motion on a development build/device.

Do not

• Don't read/write sharedValue.value during render or on the JS thread.
• Don't animate layout properties when a transform achieves it.
• Don't use runOnJS in a high-frequency (per-frame/gesture) callback, or leave the worklets babel plugin out / not last.
• Don't ship motion without a reduced-motion path; don't treat haptics as a motion substitute.
• Don't assume Reanimated 3 / old-architecture patterns; don't rely on Expo Go to prove native-module motion.
• Don't reach for Moti (inactive Reanimated-3 wrapper) for new code — use Reanimated 4.

Reference routing

| Read | When | |---|---| | references/reanimated-core.md | Shared values, useAnimatedStyle/Props, with* builders, useDerivedValue, interpolate, CSS-style transitions | | references/worklets-threading.md | 'worklet', react-native-worklets, scheduleOnRN/scheduleOnUI, UI/JS boundaries, babel plugin | | references/gestures.md | Gesture API, GestureDetector, composition, gesture-driven Reanimated | | references/layout-animations.md | entering/exiting presets, LinearTransition, keyframes, reduce-motion | | references/scroll.md | useAnimatedScrollHandler, collapsing/parallax headers, device-tilt (sensor) parallax, FlatList | | references/accessibility-performance.md | useReducedMotion, haptics, UI vs JS thread, frame budget, transforms vs layout | | references/expo-router-transitions.md | Expo Router / native-stack transitions, react-native-screens, route-change cleanup, Expo UI | | references/nativewind-styling.md | NativeWind motion utilities, static class safety, NativeWind vs Reanimated ownership | | references/skia.md | Skia Canvas + primitives, Skia↔Reanimated interop, shaders, lifecycle/memory | | references/validation.md | Expo Doctor, expo install --check, New Architecture, EAS/dev build, Jest+Reanimated, device proof | | references/assets-lottie-rive-3d.md | Lottie / Rive / R3F asset & 3D motion (tiered) | | references/recipes.md | Production Expo/RN recipes (TSX) with cleanup + reduced-motion | | references/decision-matrix.md | Reanimated vs CSS-transitions vs Layout Animations vs Skia vs Lottie/Rive vs NativeWind vs native-stack |

Optional power tool: expo-motion-audit CLI

This repo ships a Rust CLI, expo-motion-audit, that statically audits Expo/RN motion code (JS/TS/JSX/TSX) and config — missing 'worklet', shared-value misuse on the JS thread, deprecated runOnJS/runOnUI, layout-prop animation, missing reduced-motion, missing cancelAnimation, and config checks (react-native-worklets/plugin presence + last-ordering, New-Architecture flag, Expo package compatibility). Optional — if not installed, proceed with the guidance above.

# Install once (from this repo): cargo install --path crates/expo-motion-audit --locked --force
expo-motion-audit scan --root . --format json
expo-motion-audit scan --root . --categories worklets-threading,config

Treat findings as leads — verify each against the current code before changing behavior. Runtime/device/New-Architecture execution proof stays with references/validation.md / Expo Doctor.

Learn more

• Reanimated 4: https://docs.swmansion.com/react-native-reanimated/
• Worklets: https://docs.swmansion.com/react-native-worklets/
• Gesture Handler: https://docs.swmansion.com/react-native-gesture-handler/
• React Native Skia: https://shopify.github.io/react-native-skia/
• Expo: https://docs.expo.dev/