# software-mansion/react-native-reanimated architecture

> Architecture diagram of the GitHub repository software-mansion/react-native-reanimated, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/software-mansion/react-native-reanimated
- Repository: https://github.com/software-mansion/react-native-reanimated

## Overview

##### 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”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% JavaScript Layer
    subgraph "JavaScript Layer"
        U["User Application"]:::js
        AP["JS Animation API & Hooks Layer"]:::js
        BP["Babel Plugin/Code Transformation"]:::js
        JSI["JSI Bridge & Worklets Runtime"]:::js
        WP["Worklets / React Native Worklets Package"]:::js
    end

    %% Native Layer
    subgraph "Native Layer"
        NE["Native Core Animation Engine"]:::native
        iOS["iOS Native Module"]:::native
        Android["Android Native Module"]:::native
    end

    %% Development & Documentation
    subgraph "Development Tools"
        ESL["ESLint Plugin"]:::dev
        DOC["Documentation (docs-reanimated)"]:::dev
        EX["Example Apps"]:::dev
    end

    %% Flow Connections
    U -->|"imports"| AP
    AP -->|"invokes"| BP
    BP -->|"transforms worklets for"| JSI
    JSI -->|"executes worklets via"| WP
    JSI -->|"sends animation commands to"| NE
    NE -->|"integrates with"| iOS
    NE -->|"integrates with"| Android
    U ---|"uses"| DOC
    AP ---|"checked by"| ESL

    %% Styles
    classDef js fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef native fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef dev fill:#fff3cd,stroke:#ffc107,stroke-width:2px;

    %% Click Events
    click AP "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-reanimated/src/hook"
    click BP "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-reanimated/plugin"
    click JSI "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-reanimated/src/ReanimatedModule/js-reanimated"
    click WP "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-worklets"
    click NE "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-reanimated/Common/cpp/reanimated"
    click iOS "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-reanimated/apple"
    click Android "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-reanimated/android"
    click ESL "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/eslint-plugin-reanimated"
    click DOC "https://github.com/software-mansion/react-native-reanimated/tree/main/packages/docs-reanimated"
    click EX "https://github.com/software-mansion/react-native-reanimated/tree/main/apps"
```
