Redus Flutter #

Vue-like ReactiveWidget and web-style routing for Flutter with fine-grained reactivity, lifecycle hooks, and dependency injection.

Features #

• 🎯 ReactiveWidget - Reactive widget with auto-reactivity in render() (supports Flutter mixins)
• 🛤️ Redus Router - Web-style routing with useRoute() / useRouter() (context-free)
• 👁️ Observe - Widget that watches a source and rebuilds
• ⚡ ObserveEffect - Widget that auto-tracks dependencies
• 🔄 Lifecycle Hooks - onInitState, onMounted, onDispose, etc.
• 🧩 Composable Mixins - LifecycleCallbacks for custom widgets
• 💉 Dependency Injection - Type + key-based lookup (from redus)
• 🧹 Auto Cleanup - Effect scopes tied to widget lifecycle
• 🔗 Deep Linking - Built-in support with app_links

Installation #

dependencies:
  redus_flutter: ^0.12.0

Quick Start #

ReactiveWidget #

Full reactivity with automatic dependency tracking in render():

import 'package:redus_flutter/redus_flutter.dart';

class CounterStore {
  final count = ref(0);
  void increment() => count.value++;
}

class Counter extends ReactiveWidget {
  const Counter({super.key});

  @override
  ReactiveState<Counter> createState() => _CounterState();
}

class _CounterState extends ReactiveState<Counter> {
  late final CounterStore store;

  @override
  void setup() {
    store = CounterStore();
    onMounted(() => print('Count: ${store.count.value}'));
    onDispose(() => print('Cleaning up...'));
  }

  @override
  Widget render(BuildContext context) {
    // Auto-tracks store.count.value - rebuilds automatically
    return ElevatedButton(
      onPressed: store.increment,
      child: Text('Count: ${store.count.value}'),
    );
  }
}

ReactiveWidget with Flutter Mixins #

When you need Flutter's built-in State mixins (for animations, keep-alive, etc.):

class AnimatedCounter extends ReactiveWidget {
  const AnimatedCounter({super.key});

  @override
  ReactiveState<AnimatedCounter> createState() => _AnimatedCounterState();
}

class _AnimatedCounterState extends ReactiveState<AnimatedCounter>
    with SingleTickerProviderStateMixin {
  late final AnimationController controller;
  late final Ref<int> count;

  @override
  void setup() {
    controller = AnimationController(
      vsync: this,
      duration: const Duration(milliseconds: 300),
    );
    count = ref(0);
    onMounted(() => controller.forward());
    onDispose(() => controller.dispose());
  }

  @override
  Widget render(BuildContext context) {
    return FadeTransition(
      opacity: controller,
      child: ElevatedButton(
        onPressed: () => count.value++,
        child: Text('Count: ${count.value}'),
      ),
    );
  }
}

Using with AutomaticKeepAliveClientMixin

Some Flutter mixins require overriding build(). Use reactiveBuild() to get full reactive functionality:

class _KeepAliveState extends ReactiveState<KeepAliveWidget>
    with AutomaticKeepAliveClientMixin {
  late final Ref<int> count;

  @override
  bool get wantKeepAlive => true;

  @override
  void setup() {
    count = ref(0);
  }

  @override
  Widget build(BuildContext context) {
    super.build(context); // Required for the mixin
    return reactiveBuild(context); // Full reactive functionality!
  }

  @override
  Widget render(BuildContext context) {
    return Text('Count: ${count.value}');
  }
}

Observe Widget #

Observe watches a reactive source (like watch()) and rebuilds when it changes:

final count = ref(0);

// Watch a Ref directly
Observe<int>(
  source: count,
  builder: (context, value) => Text('Count: $value'),
)

// Watch a derived value
Observe<int>(
  source: () => count.value * 2,
  builder: (context, doubled) => Text('Doubled: $doubled'),
)

// Watch multiple sources
ObserveMultiple<String>(
  sources: [firstName, lastName],
  builder: (context, values) => Text('${values[0]} ${values[1]}'),
)

ObserveEffect Widget #

ObserveEffect auto-tracks any reactive values (like watchEffect()):

final count = ref(0);
final name = ref('Alice');

// Auto-tracks all .value accesses
ObserveEffect(
  builder: (context) => Column(
    children: [
      Text('Count: ${count.value}'),
      Text('Name: ${name.value}'),
    ],
  ),
)

Fine-Grained .watch(context) #

Use .watch(context) in any widget for automatic rebuilds:

class MyStatelessWidget extends StatelessWidget {
  final Ref<int> count;
  
  @override
  Widget build(BuildContext context) {
    // Only THIS widget rebuilds when count changes
    return Text('Count: ${count.watch(context)}');
  }
}

Redus Router #

Web-framework-style routing with context-free hooks:

import 'package:redus_flutter/router.dart';

// Define routes
final routes = [
  RouteConfig(path: '/', builder: (_) => HomePage()),
  RouteConfig(
    path: '/users/:id',
    builder: (_) => UserPage(),
    transition: RouteTransition.fade(),
    guards: [AuthGuard()],
    meta: {'requiresAuth': true},
  ),
  RouteConfig(path: '*', builder: (_) => NotFoundPage()),
];

// Use in app
void main() {
  runApp(
    MaterialApp.router(
      routerConfig: RedusRouterConfig(
        routes: routes,
        initialRoute: '/',
        beforeEach: (to, from) async {
          if (to.meta['requiresAuth'] == true && !isLoggedIn) {
            return '/login';
          }
          return null;
        },
      ),
    ),
  );
}

// Access route anywhere (no context needed!)
final route = useRoute();
print(route.params['id']);
print(route.query['tab']);

// Navigate anywhere
useRouter().push('/users/123');
useRouter().back();

Router Config Options #

RedusRouterConfig supports many configuration options:

RedusRouterConfig(
  routes: routes,
  initialRoute: '/',
  
  // Global default transition for all routes
  defaultTransition: RouteTransition.fade(),
  
  // Wrap all routes in a common layout
  layoutBuilder: (context, child) => Scaffold(
    appBar: AppBar(title: Text('My App')),
    drawer: AppDrawer(),
    body: child,
  ),
  
  // Custom 404 page
  notFoundBuilder: (location) => NotFoundPage(path: location.path),
  
  // Navigation guards
  beforeEach: (to, from) async {
    if (to.meta['auth'] == true && !isLoggedIn) return '/login';
    return null;
  },
  afterEach: (to, from) async => analytics.track('page_view', to.path),
  
  // Navigator observers (for analytics, logging)
  observers: [AnalyticsObserver(), LoggingObserver()],
  
  // Redirect initial route based on state
  onInitialRoute: (route) {
    if (!onboardingComplete) return '/onboarding';
    if (!isLoggedIn) return '/login';
    return route;
  },
)

Route Transitions #

RouteConfig(
  path: '/page',
  builder: (_) => Page(),
  transition: RouteTransition.fade(),           // Fade
  transition: RouteTransition.slide(direction: SlideDirection.up),  // Slide
  transition: RouteTransition.scale(),          // Scale
  transition: RouteTransition.none,             // No animation
  transition: RouteTransition.custom(           // Custom
    transitionsBuilder: (ctx, anim, secAnim, child) => ...,
  ),
)

Route Guards #

class AuthGuard extends RouteGuard {
  @override
  Future<GuardResult> canActivate(RouteLocation to, RouteLocation from) async {
    if (!isLoggedIn) {
      return GuardRedirect('/login?redirect=${to.fullPath}');
    }
    return const GuardAllow();
  }
  
  @override
  Future<bool> canDeactivate(RouteLocation to, RouteLocation from) async {
    // Return false to block leaving (e.g., unsaved changes)
    return true;
  }
  
  @override
  Future<Map<String, dynamic>?> resolve(RouteLocation to) async {
    // Prefetch data before route activates
    return {'user': await fetchUser(to.params['id']!)};
  }
}

Deep Linking #

Deep linking is powered by the app_links package. You need to configure your platform projects to handle deep links.

Platform Configuration

Android (android/app/src/main/AndroidManifest.xml):

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="yourdomain.com" />
    <data android:scheme="myapp" android:host="open" />
</intent-filter>

iOS (ios/Runner/Info.plist):

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>
<key>FlutterDeepLinkingEnabled</key>
<true/>

Web (web/index.html - for path-based routing):

<base href="/">

For full setup instructions including Universal Links (iOS) and App Links (Android), see the app_links documentation.

Usage

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Get initial link if app started via deep link
  final initialLink = await DeepLinkHandler.getInitialLink();
  
  runApp(
    MaterialApp.router(
      routerConfig: RedusRouterConfig(
        routes: routes,
        initialRoute: initialLink ?? '/',
      ),
    ),
  );
  
  // Listen for incoming links while app is running
  DeepLinkHandler.listenToIncomingLinks();
}

Lifecycle Hooks #

Timing Control #

All hooks support timing parameter for before/after control:

@override
void setup() {
  // Fire before super.initState()
  onInitState(() => print('before'), timing: LifecycleTiming.before);
  
  // Fire after super.initState() (default)
  onInitState(() => print('after'));
  
  // Fire before dispose (default for onDispose)
  onDispose(() => cleanup(), timing: LifecycleTiming.before);
  
  // Access old and new widget
  onDidUpdateWidget<MyWidget>((oldWidget, newWidget) {
    if (oldWidget.value != newWidget.value) {
      print('Value changed!');
    }
  });
}

Composable Architecture #

The library uses a composable mixin architecture:

// ReactiveWidget uses State-based mixins internally
class ReactiveState extends State<ReactiveWidget>
    with LifecycleCallbacks, LifecycleHooksStateMixin, 
         ReactiveStateMixin { ... }

// Use mixins in your own StatefulWidget
class _MyWidgetState extends State<MyWidget>
    with LifecycleCallbacks, LifecycleHooksStateMixin {
  
  late final MyStore store;
  
  @override
  void initState() {
    store = MyStore();
    onMounted(() => print('Mounted!'));
    onDispose(() => print('Disposing...'));
    super.initState();
  }
  
  @override
  Widget build(BuildContext context) {
    scheduleMountedCallbackIfNeeded();
    return Text('Value: ${store.value}');
  }
}

Available mixins:

• LifecycleCallbacks - Callback storage and registration
• LifecycleHooksStateMixin - Flutter lifecycle method overrides
• ReactiveStateMixin - EffectScope and reactivity for auto-tracking

Dependency Injection #

DI comes from redus package with key support:

// By type
register<ApiService>(ApiService());
final api = get<ApiService>();

// By key (multiple instances)
register<Logger>(ConsoleLogger(), key: #console);
register<Logger>(FileLogger(), key: #file);
final log = get<Logger>(key: #console);

When to Use What #

License #

MIT License