Vyuh Framework

Build Modular, Scalable Flutter Apps

Docs | Website

Vyuh Core 🚀

The core library for the Vyuh framework, providing essential building blocks and runtime functionality for building modular, scalable Flutter applications. This package is the foundation of the Vyuh ecosystem, offering a robust plugin architecture and modular features. It has no CMS dependency: CMS-driven UI is an optional add-on (vyuh_extension_content) built on the extension mechanism.

Features ✨

• Feature-based Architecture 🏗️: Build modular applications by breaking them into independent features, each encapsulating its own routes, UI, and business logic. Compose your app by assembling these features together.
• Plugin Architecture 🔌: Extensible plugin system for features like navigation, networking, storage, auth and telemetry
• Extensions 🧩: Features contribute to shared registries through ExtensionDescriptor and ExtensionBuilder. The optional CMS add-on is built this way.
• Navigation 🧭: Advanced routing capabilities using Go Router
• State Management 💫: Integrated MobX for reactive state management. You are also free to use your own State Management solution.
• Networking 🌐: Flexible HTTP client with retry capabilities
• Telemetry 📊: Configurable telemetry system for logging and error tracking
• Analytics 📊: Built-in analytics system for tracking user interactions and app usage
• Dependency Injection 💉: Simple yet powerful DI system for managing dependencies
• Event System 📡: Typed events, with lifecycle events from the platform and declarative per-feature handlers
• Errors and recovery 🛟: Themed failure views that always offer a way out, reported once to telemetry and as events
• Theming 🎨: One VyuhTheme for every framework screen, plus design tokens
• Storage 💾: Persistent storage capabilities for local data
• Environment Variables 🔧: Flexible configuration system for managing environment-specific settings
• Locale: the locale plugin to manage translations
• Platform Widgets 🎨: Customizable widgets for common UI patterns like loaders and error views

Installation 📦

Add this to your package's pubspec.yaml file:

dependencies:
  vyuh_core: any

Usage 💡

Basic App Setup

The entry point of your Vyuh application. Here you configure the initial route, register your features, and set up any custom plugins. Features are assembled as an array, making it easy to add or remove functionality.

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

void main() {
  vyuh.runApp(
    initialLocation: '/',
    plugins: _getPlugins(),
    features: () => [
      // Your features here
      counter.feature,
      auth.feature(),
    ],
  );
}

Feature Definition

Features are the building blocks of your application. Each feature is self-contained with its own routes, UI and business logic, and can also act on the whole app through event handlers and redirects. The platform starts and stops all of it with the feature, so there is nothing to clean up by hand.

import 'package:vyuh_core/vyuh_core.dart';

final feature = FeatureDescriptor(
  name: 'account',
  title: 'Account',
  routes: () => [
    GoRoute(path: '/account', builder: (_, _) => const AccountPage()),
  ],
  // App-level listeners, subscribed before init and removed on dispose.
  events: [
    EventHandler<SystemReadyEvent>((_) => restoreSession()),
  ],
  // App-wide redirects that re-run when their triggers fire.
  redirects: [
    FeatureRedirect(
      name: 'require-sign-in',
      refreshOn: [UserSignedOutEvent],
      redirect: (_, state) =>
          !signedIn && state.matchedLocation.startsWith('/account')
              ? '/login'
              : null,
    ),
  ],
);

Lazy features (LazyFeatureDescriptor) get the same behaviour when they activate.

Plugin Configuration

Plugins extend the core functionality of your app. The plugin system is flexible and allows you to configure various aspects like navigation, environment variables, and telemetry. You can also create custom plugins for specific needs.

Plugins are described with the PluginDescriptor class.

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

PluginDescriptor _getPlugins() {
  // Enable URL reflection for navigation (optional)
  vyuh.DefaultNavigationPlugin.enableURLReflectsImperativeAPIs();
  vyuh.DefaultNavigationPlugin.usePathStrategy();

  return PluginDescriptor(
    // Configure environment plugin
    env: vyuh.DefaultEnvPlugin(),
    // Configure telemetry
    telemetry: vyuh.TelemetryPlugin(
      providers: [vyuh.ConsoleLoggerTelemetryProvider()],
    ),
  );
}

Using a CMS 📝

Content types, layouts and CMS-driven routes are not part of vyuh_core. Add vyuh_extension_content and register its plugin with PluginDescriptor(others: [DefaultContentPlugin(provider: ...)]). See the CMS docs.

Analytics 📊

Track events and user interactions using the analytics plugin:

// Get analytics plugin
final analytics = vyuh.di.get<AnalyticsPlugin>();

// Track a simple event
analytics.reportEvent('page_view');

// Track event with parameters
analytics.reportEvent(
  'button_click',
  params: {
    'button_id': 'submit',
    'screen': 'checkout',
  },
);

// Configure multiple providers
final analyticsPlugin = AnalyticsPlugin(
  providers: [
    GoogleAnalyticsProvider(),
    MixpanelProvider(),
    CustomAnalyticsProvider(),
  ],
);

Navigation 🧭

Vyuh provides a simple yet powerful navigation system built on top of GoRouter. The router is globally accessible through vyuh.router, making it easy to navigate between routes from anywhere in your app.

For more information about GoRouter, visit the pub package.

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// Navigate to a route
vyuh.router.push('/your-route');

// Navigate with named route
vyuh.router.pushNamed(
  'route-name',
  pathParameters: {'id': '123'},
  queryParameters: {'filter': 'active'},
);

// Go to a route (replaces current route)
vyuh.router.go('/your-route');

// Go back
vyuh.router.pop();

// Go to the home route (runApp's homeLocation)
vyuh.router.goHome();

Features add app-wide redirects with FeatureDescriptor.redirects. See Routes and navigation.

State Management with MobX 💫

Vyuh comes with built-in support for MobX, providing reactive state management out of the box. MobX's simple yet powerful approach makes it easy to manage application state with minimal boilerplate.

import 'package:mobx/mobx.dart';
import 'package:flutter/material.dart';
import 'package:flutter_mobx/flutter_mobx.dart';

// Create observable value
final counter = 0.obs();

// Use in widget with Observer
Column(
  children: [
    Observer(
      builder: (_) => Text('${counter.value}'),
    ),
    IconButton(
      icon: Icon(Icons.add),
      onPressed: () => runInAction(() => counter.value++),
    ),
  ],
);

Dependency Injection 💉

A simple yet powerful dependency injection system for managing your app's dependencies.

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// Register a dependency
vyuh.di.register<MyService>(() => MyServiceImpl());

// Get an instance
final service = vyuh.di.get<MyService>();

Event System 📡

Features declare typed listeners with FeatureDescriptor.events (see above). For shorter-lived listeners, subscribe directly and cancel with the returned function:

final cancel = vyuh.event.on<UserSignedOutEvent>((event) { /* ... */ });
vyuh.event.emit(UserSignedOutEvent());
cancel();

The platform emits SystemEvents for its lifecycle: SystemInitStartedEvent, FeatureLoadedEvent, FeatureLoadFailedEvent, SystemReadyEvent, SystemInitFailedEvent and RouteFailureEvent. Delivery is asynchronous.

Storage 💾

Persist data locally using the storage plugin.

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// Store data
await vyuh.storage.set('key', 'value');

// Retrieve data
final value = await vyuh.storage.get('key');

Environment Variables 🔧

Manage environment-specific configuration with the env plugin.

import 'package:vyuh_core/vyuh_core.dart' as vyuh;

// Access environment variables
final apiKey = vyuh.env.get('API_KEY');
final isDev = vyuh.env.get('IS_DEV', defaultValue: false);

Theme, errors and platform widgets 🎨

Give the framework your theme once. The loading screen, the startup failure screen, the default app root, loaders, error views and placeholders all follow it in light and dark mode:

vyuh.runApp(
  homeLocation: '/', // where "Go home" leads from any failure
  platformWidgetBuilder: vyuh.PlatformWidgetBuilder.system.copyWith(
    theme: vyuh.VyuhTheme(light: MyDesign.light, dark: MyDesign.dark),
  ),
  features: () => [...],
);

Every route failure has a way out: Try again, Back, Go home, or Restart app, whichever applies. A missing route, a failed lazy feature, a page that fails to load and a failed startup all work this way. Failures are reported once to telemetry and as a RouteFailureEvent. Error details show only in debug builds.

Restyle the defaults with VyuhThemeExtension tokens in your ThemeData, or replace any builder with copyWith:

• appBuilder: the root app widget; read platform.widgetBuilder.theme
• appLoader, routeLoader, contentLoader: loaders (contentLoader is the inline one, for a part of a page)
• routeErrorView: full-page failures (FailurePage by default)
• errorView: inline failures (FailureCard by default)
• imagePlaceholder: image placeholder
• theme: the app's VyuhTheme

Inside a custom error view, VyuhFailureScope.maybeOf(context) gives the full VyuhFailure and FailureActions tells you which actions apply. See Theming and Errors and recovery.

Learn More 📚

• Visit docs.vyuh.tech for detailed documentation
• Check out the GitHub repository for source code
• Report issues on the issue tracker

---

Made with ❤️ by Vyuh

Libraries

asserts

extension

feature_descriptor

feature_hooks

lazy_feature_descriptor

plugin/analytics/analytics_plugin

plugin/analytics/analytics_provider

plugin/analytics/noop_analytics_provider

plugin/auth/anonymous_auth_plugin

plugin/auth/auth_plugin

plugin/auth/exceptions

plugin/auth/user

plugin/di/di_plugin

plugin/di/plugin_di_get_it

plugin/env/default_env_plugin

plugin/env/env_plugin

plugin/env/noop_env_plugin

plugin/event_plugin

plugin/feature_flag

plugin/i18n/i18n

Internationalization (i18n) support for the Vyuh framework.

plugin/i18n/locale_configuration

plugin/i18n/locale_plugin

plugin/i18n/translation_registration

plugin/navigation/default_navigation_plugin

plugin/navigation/navigation

plugin/network/http_network_plugin

plugin/network/http_network_plugin_stub

plugin/network/http_network_plugin_web

plugin/network/network_plugin

plugin/plugin

plugin/plugin_descriptor

plugin/storage/in_memory_secure_storage_plugin

plugin/storage/in_memory_storage_plugin

plugin/storage/storage

plugin/storage/storage_plugin

plugin/telemetry/logger

plugin/telemetry/noop_telemetry_provider

plugin/telemetry/telemetry_plugin

plugin/telemetry/telemetry_provider

runtime/failure

runtime/failure_view

runtime/init_tracker

runtime/platform/env/test_env_io

runtime/platform/env/test_env_stub

runtime/platform/events

runtime/platform/powered_by_widget

runtime/platform/vyuh_platform

runtime/platform_widget_builder

runtime/run_app

runtime/strings

runtime/theme

vyuh_core

Composition and lifecycle contracts for modular Flutter applications.