The oref package is a high-performance reactive state management library for Flutter, built on the `alien_signals` reactive graph engine. It provides fine-grained reactivity with automatic dependency tracking, enabling Flutter widgets to automatically rebuild when the signals they access change, without requiring boilerplate code like StatefulWidget or manual notification systems.
This document provides a high-level architectural overview of the oref repository structure, its core subsystems, and how they integrate with Flutter's widget lifecycle. For installation and initial setup, see Getting Started. For detailed API documentation, see API Reference. For production patterns and best practices, see Patterns and Best Practices.
Sources: README.md1-92 pubspec.yaml1-33
Oref is structured as a layered reactive system where each layer builds upon the previous one. The foundation is alien_signals v2.1.2, which provides the reactive graph engine. On top of this, oref adds Flutter-specific integration, lifecycle management, and higher-level utilities.
Architecture Layers:
| Layer | Purpose | Key Components | Context Binding |
|---|---|---|---|
| 0 - Foundation | Reactive graph engine | alien_signals | N/A |
| 1 - Primitives | Mutable and derived reactive state | signal, computed, writableComputed | Optional (BuildContext or null) |
| 2 - Effects | Side effects and lifecycle | effect, effectScope, onMounted, onUnmounted | Optional (BuildContext or null) |
| 3 - Flutter Integration | Widget-aware reactivity | useWidgetEffect, useWidgetScope, useMemoized, watch | Required (BuildContext) |
| 4 - Advanced Features | Higher-level patterns | useAsyncData, reactive collections, SignalBuilder | Optional or Required |
| 5 - Utilities | Control and optimization | batch, untrack, Reactive mixin | N/A |
Sources: lib/oref.dart1-21 CHANGELOG.md100-141
The reactive core consists of primitives that can be created either globally (passing null as the context) or widget-scoped (passing BuildContext).
Key Components:
signal(BuildContext? context, T initialValue) - Creates mutable reactive state lib/src/core/signal.dartcomputed(BuildContext? context, T Function() getter) - Creates derived reactive state with automatic dependency tracking lib/src/core/computed.dartwritableComputed(BuildContext? context, {required T Function() get, required void Function(T) set}) - Creates bidirectional computed values lib/src/core/computed.darteffect(BuildContext? context, void Function() callback) - Creates reactive side effects lib/src/core/effect.darteffectScope(BuildContext? context, [void Function()? callback]) - Groups effects for collective lifecycle management lib/src/core/effect_scope.dartSources: lib/src/core/signal.dart lib/src/core/computed.dart lib/src/core/effect.dart lib/src/core/effect_scope.dart CHANGELOG.md54-59
Flutter integration is achieved through BuildContext-aware hooks that automatically manage lifecycle and trigger widget rebuilds.
Key Components:
useWidgetEffect(BuildContext context) - Creates effects bound to widget lifecycle that trigger rebuilds lib/src/core/widget_effect.dartuseWidgetScope(BuildContext context) - Creates scopes bound to widget lifecycle lib/src/core/widget_scope.dartuseMemoized<T>(BuildContext context, T Function() create) - Prevents recreation of values across rebuilds lib/src/core/memoized.dartwatch(BuildContext context, T Function() getter) - Explicitly tracks dependencies and triggers rebuilds lib/src/core/watch.dartSignalBuilder - Widget for scoped reactive rebuilds lib/src/core/signal_builder.dartonMounted(void Function() callback) - Runs once after first frame lib/src/core/lifecycle.dartonUnmounted(void Function() callback) - Runs once when widget unmounts lib/src/core/lifecycle.dartSources: lib/src/core/widget_effect.dart lib/src/core/widget_scope.dart lib/src/core/memoized.dart lib/src/core/watch.dart lib/src/core/signal_builder.dart lib/src/core/lifecycle.dart CHANGELOG.md7-9
Higher-level abstractions built on the reactive core:
Async Data Management:
useAsyncData(BuildContext? context, Future<T> Function() fetcher) - Manages async operations with state machine (idle/pending/success/error) lib/src/async/async_data.dartReactive Collections:
ReactiveList<T> - Observable list with mutation tracking lib/src/collections/list.dartReactiveMap<K, V> - Observable map with mutation tracking lib/src/collections/map.dartReactiveSet<T> - Observable set with mutation tracking lib/src/collections/set.dartUtility Functions:
batch(void Function() callback) - Groups multiple signal updates into single notification lib/src/core/batch.dartuntrack<T>(T Function() callback) - Reads signals without creating dependencies lib/src/core/untrack.dartReactive mixin - Base for custom reactive types lib/src/core/reactive.dartSources: lib/src/async/async_data.dart lib/src/collections/list.dart lib/src/collections/map.dart lib/src/collections/set.dart lib/src/core/batch.dart lib/src/core/untrack.dart lib/src/core/reactive.dart CHANGELOG.md195-234
The library is organized into a clear modular structure exported through lib/oref.dart1-21:
Directory Structure:
| Directory | Purpose | Key Files |
|---|---|---|
lib/src/core/ | Reactive primitives and Flutter integration | signal.dart, computed.dart, effect.dart, effect_scope.dart, widget_effect.dart, widget_scope.dart, memoized.dart, watch.dart, lifecycle.dart, batch.dart, untrack.dart, signal_builder.dart, reactive.dart |
lib/src/collections/ | Reactive collection wrappers | list.dart, map.dart, set.dart |
lib/src/async/ | Async state management | async_data.dart |
lib/src/devtools/ | DevTools diagnostic protocol | Service extensions and instrumentation |
example/ | Living documentation and demonstrations | main.dart, widget tests |
extension/devtools/ | Standalone DevTools extension UI | Flutter web application |
docs/ | VitePress documentation site | Guides in English and Chinese |
Sources: lib/oref.dart1-21 README.md1-92
Oref is built on alien_signals v2.1.2, a high-performance reactive graph engine that provides:
Oref's Extensions to alien_signals:
markNeedsBuild() when dependencies changeSources: pubspec.yaml27 CHANGELOG.md19-29 lib/src/core/alien_signals.dart
The repository includes a comprehensive VitePress documentation site with bilingual support (English and Chinese), deployed to GitHub Pages at a custom domain via automated CI/CD.
Components:
Sources: CHANGELOG.md31-38 README.md71-75
Version 2.7.0 introduced a dedicated DevTools extension for debugging and performance monitoring:
Components:
Architecture: The extension uses VM Service Protocol to communicate between the running Flutter app and the DevTools UI, enabling live introspection without impacting production builds (debug mode only).
Sources: CHANGELOG.md3-9 README.md49-70
Test Coverage:
Version History:
writableComputed for bidirectional computed valuesonMounted, onUnmounted)For detailed migration guidance, see Version History and Migration.
Sources: CHANGELOG.md1-564 pubspec.yaml4
Oref provides a high-performance reactive state management solution for Flutter through:
null) and widget-scoped (BuildContext) reactive stateFor hands-on examples, see Examples. For API details, see API Reference. For best practices, see Patterns and Best Practices.
Sources: README.md1-92 pubspec.yaml1-33 lib/oref.dart1-21 CHANGELOG.md1-564
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.