How workiva/react-dart works
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).