# workiva/react-dart architecture

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

- Interactive diagram: https://gitdiagram.com/workiva/react-dart
- Repository: https://github.com/workiva/react-dart

## Overview

##### Project Type and Purpose
- This is a client-side library/package, not a standalone application or microservice.
- Purpose: Expose the React JS API to Dart developers via a Dart-native API surface, bridging Dart code to React’s JavaScript runtime.

##### High-Level Components
a. Dart API Layer
- lib/react.dart, lib/react_dom.dart, lib/react_client/...
- Defines Dart functions and classes (Component2, hooks, test utilities) that mirror React JS concepts.
b. JS-Interop Bridge
- lib/react_client/js_interop_helpers.dart and related files under lib/react_client/
- Uses Dart’s `package:js` to call into React’s JS code at runtime.
c. React JS Runtime Libraries
- Bundled JS files under lib/js/ and build artifacts in js_src/
- React, ReactDOM, and variants (dev vs. prod, v17 vs. v18) that get loaded into the browser via `<script>` tags.
d. Examples & Consumer Code
- example/ folder with HTML and Dart entrypoints showing how to mount Dart-written React components.
e. Build Tools & Scripts
- tool/dart_dev (runs tests, formatting)
- build.yaml, dart_test.yaml, vite.config.js, js_src build scripts (package.json, pnpm-lock.yaml, Yarn)
f. Test Harness
- test/ and example/test/ folders
- Uses Dart test runner + React TestUtils to verify correct behavior against multiple React builds (v17, v18), with presets for DDC and dart2js.

##### Relationships and Data Flow
- Developer Dart code (importing package:react) → Compiled by Dart2JS or DDC → Produces a `.js` bundle
- At runtime, HTML page loads React JS libraries (from packages/react/js/) → Then loads compiled Dart bundle
- Dart bundle invokes the JS Interop Bridge → Calls into React JS APIs → React constructs/manages DOM in the browser
- Tests: Dart test runner invokes components via react_test_utils → Under the hood those utilities interop with React TestUtils JS API to simulate and verify UI events/state.

##### Architectural Patterns & Principles
- Wrapper/Facade Pattern: Dart APIs façade over the JS implementation.
- Bridge Pattern: Clear separation between Dart code and underlying JS implementation with a dedicated interop layer.
- Modular Packaging: Separate npm/js build (js_src) from Dart packaging (pubspec.yaml, lib/, example/).
- Dual-build Compatibility: Support for both React 17 and React 18 via configuration and alternate JS files.

##### Essential Elements
- Clear component names: “Dart React API,” “JS Interop Bridge,” “React & ReactDOM (v17/v18),” “Example HTML + Dart Entry,” “Test Runner & TestUtils.”
- Notes on synchronous vs. asynchronous flows (e.g., script loading order, deferred loading of Dart bundle).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Code
    subgraph "Consumer Code" 
        direction TB
        EXHTML["example/index.html"]:::dart
        EXJSComp["example/js_components/js_components.dart"]:::dart
        EXSusp["example/suspense/simple_component.dart"]:::dart
        EXGeo["example/geocodes/geocodes.dart"]:::dart
    end

    %% Dart API Layer
    subgraph "Dart API Layer"
        direction TB
        RACT["lib/react.dart"]:::dart
        RDOM["lib/react_dom.dart"]:::dart
        HOOKS["lib/hooks.dart"]:::dart
        RCLIENT["lib/react_client.dart"]:::dart
        COMPFACT["lib/react_client/component_factory.dart"]:::dart
    end

    %% JS-Interop Bridge
    subgraph "JS-Interop Bridge"
        direction TB
        JSHELP["lib/react_client/js_interop_helpers.dart"]:::dart
        BRIDGE["lib/react_client/bridge.dart"]:::dart
        RINTEROP["lib/react_client/react_interop.dart"]:::dart
        JSBM["lib/react_client/js_backed_map.dart"]:::dart
    end

    %% React JS Runtime Libraries
    subgraph "React JS Runtime"
        direction TB
        RDEV["lib/js/react.dev.js"]:::js
        RPROD["lib/js/react_prod.js"]:::js
        RADD["lib/js/react_with_addons.js"]:::js
        RDOMJS["lib/js/react_dom.js"]:::js
        RDOMPR["lib/js/react_dom_prod.js"]:::js
        SRCREACT["js_src/react.mjs"]:::js
        SRCDOM["js_src/react_dom.mjs"]:::js
        SRCDOMDEV["js_src/react_dom_dev.mjs"]:::js
    end

    %% Build Tools & Scripts
    subgraph "Build Tools & Scripts"
        direction TB
        TOOL["tool/dart_dev"]:::tools
        YAML1["build.yaml"]:::tools
        YAML2["dart_test.yaml"]:::tools
        VITE["vite.config.js"]:::tools
        PKG["package.json"]:::tools
        LOCK["pnpm-lock.yaml"]:::tools
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        TESTDIR["test/"]:::tests
        EXTDIR["example/test/"]:::tests
        JSHELPT["test/react_client/js_interop_helpers_test.dart"]:::tests
        JS17T["test/js_builds/react17/js_dev_test.dart"]:::tests
        JS18T["test/js_builds/react18/js_prod_test.dart"]:::tests
    end

    %% Relationships
    EXHTML -->|"script include"| RDEV
    EXHTML -->|"script include"| SRCREACT
    EXHTML -->|"script include"| SRCDOM
    EXHTML -->|"script include"| SRCDOMDEV

    EXHTML -->|"loads Dart bundle"| RACT
    EXJSComp -->|"import package:react"| RACT
    EXSusp -->|"import package:react"| RACT
    EXGeo -->|"import package:react"| RACT

    RACT -->|"uses"| RDOM
    RACT -->|"uses"| HOOKS
    RACT -->|"uses"| RCLIENT
    RCLIENT -->|"factory"| COMPFACT

    RACT -->|"JS interop call"| JSHELP
    RDOM -->|"JS interop call"| JSHELP
    JSHELP -->|"bridge"| BRIDGE
    BRIDGE -->|"interop"| RINTEROP
    RINTEROP -->|"backed map"| JSBM

    BRIDGE -->|"calls"| RDEV
    BRIDGE -->|"calls"| RPROD
    BRIDGE -->|"calls"| RADD
    BRIDGE -->|"calls"| RDOMJS
    BRIDGE -->|"calls"| RDOMPR

    TOOL -->|"build js_src"| SRCREACT
    TOOL -->|"build js_src"| SRCDOM
    TOOL -->|"build js_src"| SRCDOMDEV

    TOOL -->|"compile Dart"| RACT
    TOOL -->|"compile Dart"| RDOM
    TOOL -->|"compile Dart"| HOOKS

    TESTDIR -->|"test runner invokes"| RACT
    TESTDIR -->|"uses"| JSHELPT
    JSHELPT -->|"interop test"| JSHELP
    TESTDIR -->|"runs"| JS17T
    TESTDIR -->|"runs"| JS18T

    EXTDIR -->|"example tests"| EXHTML

    %% Click Events
    click EXHTML "https://github.com/workiva/react-dart/blob/master/example/index.html"
    click EXJSComp "https://github.com/workiva/react-dart/blob/master/example/js_components/js_components.dart"
    click EXSusp "https://github.com/workiva/react-dart/blob/master/example/suspense/simple_component.dart"
    click EXGeo "https://github.com/workiva/react-dart/blob/master/example/geocodes/geocodes.dart"
    click RACT "https://github.com/workiva/react-dart/blob/master/lib/react.dart"
    click RDOM "https://github.com/workiva/react-dart/blob/master/lib/react_dom.dart"
    click HOOKS "https://github.com/workiva/react-dart/blob/master/lib/hooks.dart"
    click RCLIENT "https://github.com/workiva/react-dart/blob/master/lib/react_client.dart"
    click COMPFACT "https://github.com/workiva/react-dart/blob/master/lib/react_client/component_factory.dart"
    click JSHELP "https://github.com/workiva/react-dart/blob/master/lib/react_client/js_interop_helpers.dart"
    click BRIDGE "https://github.com/workiva/react-dart/blob/master/lib/react_client/bridge.dart"
    click RINTEROP "https://github.com/workiva/react-dart/blob/master/lib/react_client/react_interop.dart"
    click JSBM "https://github.com/workiva/react-dart/blob/master/lib/react_client/js_backed_map.dart"
    click RDEV "https://github.com/workiva/react-dart/blob/master/lib/js/react.dev.js"
    click RPROD "https://github.com/workiva/react-dart/blob/master/lib/js/react_prod.js"
    click RADD "https://github.com/workiva/react-dart/blob/master/lib/js/react_with_addons.js"
    click RDOMJS "https://github.com/workiva/react-dart/blob/master/lib/js/react_dom.js"
    click RDOMPR "https://github.com/workiva/react-dart/blob/master/lib/js/react_dom_prod.js"
    click SRCREACT "https://github.com/workiva/react-dart/blob/master/js_src/react.mjs"
    click SRCDOM "https://github.com/workiva/react-dart/blob/master/js_src/react_dom.mjs"
    click SRCDOMDEV "https://github.com/workiva/react-dart/blob/master/js_src/react_dom_dev.mjs"
    click TOOL "https://github.com/workiva/react-dart/tree/master/tool/dart_dev"
    click YAML1 "https://github.com/workiva/react-dart/blob/master/build.yaml"
    click YAML2 "https://github.com/workiva/react-dart/blob/master/dart_test.yaml"
    click VITE "https://github.com/workiva/react-dart/blob/master/vite.config.js"
    click PKG "https://github.com/workiva/react-dart/blob/master/package.json"
    click LOCK "https://github.com/workiva/react-dart/blob/master/pnpm-lock.yaml"
    click TESTDIR "https://github.com/workiva/react-dart/tree/master/test/"
    click EXTDIR "https://github.com/workiva/react-dart/tree/master/example/test/"
    click JSHELPT "https://github.com/workiva/react-dart/blob/master/test/react_client/js_interop_helpers_test.dart"
    click JS17T "https://github.com/workiva/react-dart/blob/master/test/js_builds/react17/js_dev_test.dart"
    click JS18T "https://github.com/workiva/react-dart/blob/master/test/js_builds/react18/js_prod_test.dart"

    %% Styles
    classDef dart fill:#cce5ff,stroke:#007bff,font-weight:bold
    classDef js fill:#e2e3e5,stroke:#6c757d,font-weight:bold
    classDef tools fill:#d4edda,stroke:#155724,font-weight:bold
    classDef tests fill:#fff3cd,stroke:#856404,font-weight:bold
```
