How workiva/over_react works
Project Type & Purpose
• OverReact is an open-source Dart library/framework for authoring statically-typed React UI components.
• It comprises:
• A core runtime library (over_react) exposing UiFactory/UiProps/UiComponent2 abstractions
• An OverReact Redux extension for state management
• A build_runner “builder” plugin that parses Dart code and generates .g.dart artifacts
• An analyzer_plugin providing IDE linting & assists
• Extensive documentation, examples, and a test harness
Directory Structure & Architectural Layers
• Top-level modules:
• lib/ – Core library code, split into subpackages:
– builder/ (codegen entrypoints + AST parsing + generator)
– component/ (runtime component classes, mixins)
– component_declaration/ (UiFactory / builder DSL annotations)
– over_react_redux/ (Redux connectors, hooks, devtools middleware)
– util/ (DOM interop, CSS utils, promise interop, debug tools)
• tools/analyzer_plugin/ – Dart analysis server plugin for OverReact-specific diagnostics
• app/over_react_redux/todo_client/ – sample Todo app demonstrating usage
• example/, web/ – multiple demonstration apps (builder, hooks, suspense, component demos)
• test/ + test_fixtures/ – unit/integration tests for library & plugins
• doc/ + CHANGELOG.md + CONTRIBUTING.md – documentation & contributor guides
Core Components & Interactions
• Developer Code (e.g., app/..., example/..., user’s own app)
→ imports package:over_react/over_react.dart & optionally over_react_redux.dart
→ annotates components with mixins and UiFactory definitions
• Build System (build_runner)
→ invokes OverReact “builder” (configured via build.yaml)
→ Builder parses developer Dart AST (via lib/src/builder/parsing)
→ Generates .over_react.g.dart files (lib/src/builder/codegen modules)
• Analyzer Plugin (IDE)
→ Reads code + generated parts to provide lints, code fixes, assists
→ Lives under tools/analyzer_plugin and plugs into the Dart Analysis Server
• Runtime
→ Dart2JS/Dart VM executes compiled code
→ OverReact runtime classes (UiComponent2, Dom builders, Redux connectors)
→ Interops with React.JS and ReactDOM (via react.dart and JS interop)
• OverReact Redux
→ Provides Provider components, hooks (useSelector, useDispatch), middleware
→ Integrates with external Redux store implementations
Architectural Patterns & Design Principles
• Layered Architecture:
1. DSL Layer – UiFactory/UiProps/UiState mixin declarations
2. Codegen Layer – AST parsing + code generation
3. Runtime Layer – component base classes + utilities + interop
4. External Facades – react-dart, React.JS, Redux libraries
• Plugin Pattern: builder and analyzer are pluggable into the standard Dart toolchain
• Fluent Interface & Builder Pattern: component instantiation via cascading setters
• Separation of Concerns: parsing, codegen, runtime, tooling (IDE plugin) are distinct
Elements
• Developer Application (e.g., Todo Client or any user app)
• OverReact Core Library (split into Runtime, DSL, Util)
• OverReact Redux Extension
• Build Runner & OverReact Builder
• Analyzer Plugin (IDE)
• External Dependencies: react-dart, React.JS, Redux, Dart2JS/Dart VM
• Developer Code → imports → OverReact DSL/Runtimes
• build_runner → invokes → Builder → generates → .g.dart files
• IDE (Analysis Server) → loads → Analyzer Plugin → provides → lints/assists
• Compilation → Dart2JS → JavaScript → ReactJS runtime → browser DOM
• OverReact Redux connects Developer Code to external Redux Stores
• Visual Aids:
– Tooling (builder/analyzer) in one hue
– Runtime libraries in another
– External dependencies in a third
– Rectangles for code modules
– Clouds for external libraries/services