How software-mansion/react-native-reanimated works
Main Components
• JavaScript API & Hooks Layer – This is the user‐facing API, which includes all the animation hooks, components (e.g., useAnimatedStyle, useSharedValue, useAnimatedGestureHandler), and the inline JavaScript execution of worklets.
• Babel Plugin / Code Transformation – The Babel plugin component that analyzes and transforms “worklet” code. This module performs static analysis so that worklets can be offloaded to the native thread.
• JSI Bridge & Worklets Runtime – The intermediary layer that connects the JavaScript side to the native runtime. It is responsible for executing worklets (small functions) on a separate thread. This component is central to Reanimated’s design.
• Native Core Animation Engine – Implemented primarily in C++ and integrated through native modules on iOS (Objective-C/Swift) and Android (Java/Kotlin). It includes the core animation schedulers, layout animation managers, sensor handling (e.g., gesture and accelerometer events), and platform-specific optimizations.
• Platform-specific Modules – Separate components for iOS (Xcode projects, Swift/Objective-C code, Fabric integration) and Android (Gradle projects, Kotlin/Java code, C++ code interfacing via JNI). These use native rendering and sensor frameworks.
• ESLint Plugin – Helps developers catch common mistakes when using the Reanimated API. This shows the developer experience tools that are part of the ecosystem.
• Documentation & Examples – The “docs-reanimated” package and example apps (under the apps directory) demonstrate usage scenarios and serve as interactive playgrounds for the API.
• Worklets / React Native Worklets Package – This package contains the implementation for the “worklets” that are executed in a separate JavaScript runtime/natively to avoid the main thread blocking.
Relationships and Interactions
• User Application – When a developer uses Reanimated inside their React Native app, the JavaScript API and hooks are imported and invoked. These calls are detected and transformed by the Babel plugin.
• Babel Plugin Transformation – During build time, the Babel plugin analyzes “worklet” functions in the JavaScript code, extracts and transforms them for execution in the separate thread. This output then feeds into the JSI Bridge.
• JSI Bridge / Worklets Runtime – The transformed worklets are communicated via the JSI bridge to the native core animation engine, ensuring animations run smoothly on dedicated threads.
• Native Core Animation Engine – This layer is implemented in C++ and integrated across iOS and Android. It receives animation commands from the JSI Bridge, manages the animation frames (using requestAnimationFrame-like scheduling), and synchronizes with the native rendering systems.
• Platform-specific Modules – The native engine further interacts with iOS and Android framework APIs (such as CADisplayLink on iOS and similar scheduling on Android) for timing and sensor data. These components also expose native modules that feed back to the JS side if needed.
• Development and Tools – Tools such as the ESLint plugin, testing scripts, and continuous integration workflows (defined in the .github/workflows directory) support code quality and build processes. Although not part of runtime execution, these aspects ensure the developer experience is smooth.
• Documentation & Examples – The documentation package “docs-reanimated” and example apps demonstrate usage and are integrated into the repository structure. They serve as a reference implementation for how to call the APIs and a testbed for the animations.
Architectural Patterns and Design Principles
• Separation of Concerns – The project strictly separates the JS user API from the native execution engine through the JSI bridge and worklets model.
• Cross-platform Abstraction – Different packages abstract platform differences; the native C++ code is shared across platforms, with clear platform-specific integration for iOS and Android.
• Modular Design – The repository is split into many packages (core library, ESLint plugin, docs, worklets) which communicate through well-defined dependencies.
• Asynchronous and Real-Time Execution – Emphasis is on offloading heavy animation calculations off the main thread to maintain smooth UI performance.
• Developer Experience – Uses tooling (Babel transformations, ESLint plugins) and extensive documentation to streamline integration and troubleshooting for developers.
Elements to Emphasize
– Clear labeling of each component, ensuring that every layer (JS API, Babel Plugin, JSI Bridge, Native Core, Platform-specific integrations, Dev Tools) is represented.
– Annotations for key workflows such as “Animation Scheduling”, “Worklet Execution”, and “Code Transformation”.