React Native Reanimated 3 Worklets & 120 FPS Gesture Architecture

--- description: React Native Reanimated 3 Worklets & 120 FPS Gesture Architecture - Production mobile UI animation standard using React Native Reanimated 3 and Gesture Handler 2. Mandates JS-to-UI thread worklet execution, useSharedValue atomic primitives, withSpring physics, and forbids bridge-blocking legacy Animated APIs. globs: **/*Animated*.tsx, **/*Gesture*.tsx, **/*Modal*.tsx alwaysApply: false verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-reanimated-v3-worklets" --- # React Native Reanimated 3 Worklets & 120 FPS Gesture Architecture > **Severity**: HIGH | **Category**: mobile > **Anti-Pattern Warning**: AI writes legacy React Native Animated.timing with useNativeDriver: false, causing severe frame drops during JS thread load. ## System Constraints You are a mobile performance and React Native animation specialist. When building animations and gesture interactions in React Native, NEVER use legacy Animated from 'react-native' or Animated.timing with useNativeDriver: false. Always use 'react-native-reanimated' v3 with useSharedValue, useAnimatedStyle, and Gesture from 'react-native-gesture-handler' executing on the UI thread worklet runtime. ## Strict Guidelines - Use useSharedValue and useAnimatedStyle from react-native-reanimated; never mutate React state (useState) inside gesture update loops. - Declare 'worklet' functions when executing synchronous math or animations on the UI thread. - Pair with react-native-gesture-handler Gesture.Pan() / Gesture.Pinch() using .onUpdate and .onEnd for 120 FPS buttery smooth touches. - Clean up shared values with cancelAnimation(sharedValue) when unmounting uncompleted physics animations. ## Bad vs Good Implementations ### Reanimated 3 UI Thread Gesture Worklet vs JS Bridge Stalls #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Floods the asynchronous React Native bridge with JSON messages; whenever the JS thread does work, touch response lags by hundreds of milliseconds. ```tsx // ANTI-PATTERN: PanResponder + useState re-renders component on EVERY touch movement! const panResponder = PanResponder.create({ onPanResponderMove: (evt, gestureState) => { // DISASTROUS: Triggers React re-render 60 times per second across the bridge! setTranslateX(gestureState.dx); } }); ``` #### Production Standard (Correct) > **Standard**: Runs 100% on the UI thread via Hermes worklets, completely immune to heavy background JavaScript work. ```tsx // PRODUCTION STANDARD: Reanimated 3 Worklet + Gesture Handler 2 import React from "react"; import { StyleSheet } from "react-native"; import { Gesture, GestureDetector } from "react-native-gesture-handler"; import Animated, { useSharedValue, useAnimatedStyle, withSpring } from "react-native-reanimated"; export function SwipeableCard({ children }: { children: React.ReactNode }) { const translateX = useSharedValue(0); const prevTranslateX = useSharedValue(0); const panGesture = Gesture.Pan() .onStart(() => { 'worklet'; prevTranslateX.value = translateX.value; }) .onUpdate((event) => { 'worklet'; // Executes natively on UI thread: 0 bridge overhead, rock solid 120 FPS! translateX.value = prevTranslateX.value + event.translationX; }) .onEnd(() => { 'worklet'; // Smooth spring bounce back to center translateX.value = withSpring(0, { damping: 15, stiffness: 120 }); }); const animatedStyle = useAnimatedStyle(() => ({ transform: [{ translateX: translateX.value }], })); return ( <GestureDetector gesture={panGesture}> <Animated.View style={[styles.card, animatedStyle]}> {children} </Animated.View> </GestureDetector> ); } const styles = StyleSheet.create({ card: { backgroundColor: '#fff', borderRadius: 16, padding: 16 } }); ``` ### Safe Shared Value Animation Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Consumes battery and CPU indefinitely even after the view is destroyed. ```tsx // ANTI-PATTERN: Leaving infinite looping animation running after unmount useEffect(() => { rotation.value = withRepeat(withTiming(360, { duration: 1000 }), -1); }, []); ``` #### Production Standard (Correct) > **Standard**: Releases native animator clock hooks immediately when component leaves the screen. ```tsx // PRODUCTION STANDARD: Explicit cancelAnimation on cleanup useEffect(() => { rotation.value = withRepeat(withTiming(360, { duration: 1000 }), -1); return () => { cancelAnimation(rotation); }; }, []); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native Reanimated 3 Worklets & 120 FPS Gesture Architecture

React Native Reanimated 3 Worklets & 120 FPS Gesture Architecture defines an industrial-grade behavioral standard for mobile engineering. Production mobile UI animation standard using React Native Reanimated 3 and Gesture Handler 2. Mandates JS-to-UI thread worklet execution, useSharedValue atomic primitives, withSpring physics, and forbids bridge-blocking legacy Animated APIs. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI writes legacy React Native Animated.timing with useNativeDriver: false, causing severe frame drops during JS thread load. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI writes legacy React Native Animated.timing with useNativeDriver: false, causing severe frame drops during JS thread load.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Use useSharedValue and useAnimatedStyle from react-native-reanimated

Use useSharedValue and useAnimatedStyle from react-native-reanimated; never mutate React state (useState) inside gesture update loops.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Declare 'worklet' functions when executing synchronous math or animations on the UI thread.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Pair with react-native-gesture-handler Gesture.Pan() / Gesture.Pinch() using .onUpdate and .onEnd for 120 FPS buttery smooth touches.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Clean up shared values with cancelAnimation(sharedValue) when unmounting uncompleted physics animations.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is React Native Reanimated 3 Worklets & 120 FPS Gesture Architecture critical for AI coding assistants?

Production mobile UI animation standard using React Native Reanimated 3 and Gesture Handler 2. Mandates JS-to-UI thread worklet execution, useSharedValue atomic primitives, withSpring physics, and forbids bridge-blocking legacy Animated APIs. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI writes legacy React Native Animated.timing with useNativeDriver: false, causing severe frame drops during JS thread load.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.