vyuh_core library

Composition and lifecycle contracts for modular Flutter applications.

A FeatureDescriptor declares a product capability with routes, lifecycle hooks, dependencies, and extension contributions. PluginDescriptor selects the shared capabilities that features consume. The app owns their composition.

Start with an ordinary Flutter screen:

import 'package:material_ui/material_ui.dart';
import 'package:go_router/go_router.dart';
import 'package:vyuh_core/vyuh_core.dart' as vc;

void main() {
  vc.runApp(
    initialLocation: '/',
    platformWidgetBuilder: vc.PlatformWidgetBuilder.system.copyWith(
      appBuilder: (_, platform) => MaterialApp.router(
        routerConfig: platform.router.instance,
      ),
    ),
    features: () => [
      vc.FeatureDescriptor(
        name: 'hello',
        title: 'Hello',
        routes: () => [
          GoRoute(
            path: '/',
            builder: (_, _) => const Scaffold(body: Text('Hello, Vyuh.')),
          ),
        ],
      ),
    ],
  );
}

Add feature descriptors to compose a larger app. Use plugin contracts for shared services such as networking, storage, authentication, and telemetry. Custom capabilities belong in PluginDescriptor.others and are retrieved from the initialized platform through VyuhPlatform.getPlugin.

Feature packages own their behavior; apps select the implementations and configuration they need. See VyuhPlatform and PlatformWidgetBuilder for runtime access and app-wide loading, error, and branding widgets.

Classes

AnalyticsPlugin: The default implementation of analytics tracking in Vyuh applications.
AnalyticsProvider: The base interface for an Analytics Provider. The provider is responsible for reporting analytics events, errors, and messages.
AuthPlugin: An authentication plugin that supports various authentication methods.
BuildFailureView: Shown in release builds in place of a widget that failed to build. Small, quiet and themed, so one broken widget does not break the page.
DefaultEnvPlugin: Reads configuration from a .env asset through flutter_dotenv.
DefaultEventPlugin: Default implementation of EventPlugin using the event_bus package.
DefaultNavigationPlugin
DIPlugin: DIPlugin is an abstract class that extends the Plugin class.
EnvPlugin: An abstract class representing an environment plugin. It provides methods to interact with environment variables.
EventHandler<T extends VyuhEvent>: A typed event listener that a feature declares in FeatureDescriptor.events.
EventPlugin: Base class for implementing event handling in Vyuh applications.
ExtensionBuilder<T extends ExtensionDescriptor>: The base type for all extension builders. An extension builder is responsible for building an extension, by assembling all of the extension descriptors.
ExtensionDescriptor: The base type for all extension descriptors. An ExtensionDescriptor provides configurability for an extension.
FailureActions: The recovery actions that apply in a given context. Every error view offers the same choices in the same order: Retry, Go home, Back, Restart.
FailureCard: The default inline failure, used inside a page for a part that failed.
FailurePage: The default full-page failure: a themed page with a clear message and the recovery actions that apply. Error details appear only in debug builds.
FeatureDescriptor: The essential descriptor for a feature. A feature descriptor provides the necessary information to register a feature within the framework.
FeatureFlagPlugin<TSettings, TContext>: The base class for a Feature Flag plugin. Feature Flags are useful to control the visibility of features in an application. They are setup on the server side and can be controlled by the server to enable/disable features for different users.
FeatureLoadedEvent: Emitted after a feature is ready: an eager feature finished its init, or a lazy feature finished loading and activating.
FeatureLoadFailedEvent: Emitted when a lazy feature fails to load, or is disabled by its flag.
FeatureRedirect: A redirect that a feature contributes to the app's router.
GetItDIPlugin: GetItDIPlugin is a class that is final and it extends the DIPlugin. It uses the 'GetIt' package to manage dependency injection in the project.
HttpNetworkConfig
HttpNetworkPlugin
InMemorySecureStoragePlugin: A simple in-memory secure storage plugin that stores data in a Map.
InMemoryStoragePlugin: A simple in-memory storage plugin that stores data in a Map.
LazyFeatureDescriptor: Describes a feature that should be loaded lazily — only when one of its route prefixes is first navigated to.
LocaleConfiguration: Configuration for a single locale including its code, native name, and icon
LocalePlugin: Plugin for managing internationalization across features
Logger: Leveled logging over the telemetry plugin. Every message goes to reportMessage as text; error and fatal also report their error, with its stack trace, through reportError.
NavigationBranchContainer: A bounded alternative to an IndexedStack for stateful shell navigators.
NavigationPlugin
NetworkPlugin: Base class for implementing network communication in Vyuh applications.
NoOpAnalyticsProvider: A no-op implementation of AnalyticsProvider.
NoOpEnvPlugin: The default environment plugin: it holds no values. get throws and maybeGet returns its fallback.
NoOpTelemetryProvider: A no-op implementation of TelemetryProvider that can be used for development or testing purposes.
NoOpTrace: A no-op implementation of Trace that can be used for development or testing.
PlatformWidgetBuilder: A builder for platform-specific widgets used throughout the Vyuh application.
Plugin
PluginDescriptor: A descriptor for configuring the plugin system in a Vyuh application.
RedirectRegistry: The redirects and refresh triggers currently contributed by features.
RouteFailureEvent: Emitted once each time a route cannot be shown: no match, a page that failed to load or a failed lazy feature.
RouteFailureView: Shows a route-level failure through PlatformWidgetBuilder.routeErrorView and reports it once, to telemetry and as a RouteFailureEvent.
RoutingConfigNotifier
SecureStoragePlugin: A storage contract for app-selected secure storage implementations.
StoragePlugin: A key-value storage capability shared by features.
SystemEvent<T>: The base type for every event the platform emits about its own lifecycle.
SystemInitFailedEvent: Emitted when platform initialization fails.
SystemInitStartedEvent: Emitted when platform initialization starts, including on restart.
SystemInitTracker: A tracker for the system initialization process.
SystemReadyEvent: An event indicating that the system is ready.
TelemetryPlugin: The default implementation for a Telemetry Plugin.
TelemetryProvider: The base interface for an Telemetry Provider. The provider is responsible for reporting telemetry events, errors, and messages.
Trace: The base interface for a Telemetry Trace. The trace is responsible for tracking the duration of an operation, and reporting metrics and attributes.
TranslationRegistration: Registration for feature-specific translations
UnknownAuthPlugin: An authentication plugin that does not support any authentication methods.
User: Represents a user of the application.
UserChangedEvent: Emitted whenever an AuthPlugin sets the current user: on sign-in, sign-out and profile changes. data is the new user, which is User.unknown after sign-out.
VyuhBinding
VyuhBranding: "Powered by Vyuh", shown when the theme allows it.
VyuhEvent<T>: Base class for all events in a Vyuh application.
VyuhFailure: A failure the framework shows to the user and reports to telemetry.
VyuhFailureScope: Makes the current VyuhFailure available to error views below it.
VyuhPlatform: The base class for the Vyuh Platform. This class is responsible for initializing the platform and managing the lifecycle of the platform.
VyuhStrings: Every user-facing string the framework shows: failure titles and messages, recovery actions and accessibility labels.
VyuhTheme: The app's themes, given once to PlatformWidgetBuilder.theme.
VyuhThemeExtension: Design tokens for the UI the framework draws itself.

Enums

FailureKind: What went wrong, used to pick the message and the recovery actions.
InitState: The possible states of the system initialization.
LoginMethod: Represents the method used to login.
LogLevel: How severe a log message is, from least to most severe, so levels can be compared by index.
OAuthType
RouterUrlStyle: How URLs look on the web. Has no effect on other platforms.

Mixins

InitOncePlugin: Initializes a plugin once per active lifecycle, sharing concurrent calls.
PreloadedPlugin: A mixin to mark any plugin to be loaded before the Platform.
RouteObservers

Extensions

AsyncLazyDI on DIPlugin: An extension on the DIPlugin class to provide asynchronous lazy dependency injection.
LoggerInterface on VyuhBinding: A convenience wrapper to provide a Logger interface to the Telemetry reportMessage() calls.
NamedBindings on VyuhBinding: The same named accessors as vyuh.*, for code that must also run in widget mode, where runApp (and so vyuh) is not used.
NamedPlugins on VyuhPlatform: Named accessors for the system plugins: vyuh.router, vyuh.auth, ...
PlatformLoggerInterface on VyuhPlatform
Restartable on VyuhPlatform: Restart the platform, re-running the initialization process.

Properties

vyuh ↔ VyuhPlatform: The platform interface for Vyuh. This tracks the instance of the platform and can be used to access various aspects of the framework.
getter/setter pair

Functions

debugAssertOneOfPathOrRouteId(String? path, String? routeId) → void: Asserts only one of path or routeId is provided and not both. Asserts that only one of path or routeId is provided.
defaultAppRunner(Widget app) → void: The default app runner that initializes Flutter bindings and runs the app using flutter.runApp.
reportFailure(VyuhFailure failure, {bool emitRouteEvent = true}) → void: Reports a failure in one consistent way: to telemetry and, for route-level failures, as a RouteFailureEvent.
runApp({required FeaturesBuilder features, LazyFeaturesBuilder? lazyFeatures, PluginDescriptor? plugins, PlatformWidgetBuilder? platformWidgetBuilder, String? initialLocation, String? homeLocation, bool captureErrors = true, AppRunner? appRunner}) → void: The main entry point to kick off the Vyuh Application. This function should be called from the main function of the application. It initializes the Vyuh Platform and runs the application with given features and plugins.

Typedefs

AppBuilder = Widget Function(BuildContext context, VyuhPlatform platform): A builder for root Widget of the application. Typically this would be a MaterialApp or CupertinoApp.
AppRunner = void Function(Widget app): A function that takes a Widget and runs the application.
DeferredFeatureLoader = Future<FeatureDescriptor> Function(): A callback that loads a FeatureDescriptor, potentially using Dart's deferred import mechanism for web code splitting.
DisposeFunction = void Function(): A function that can be called to dispose of (cancel) an event subscription.
ErrorViewBuilder = Widget Function(BuildContext context, {dynamic error, VoidCallback? onRetry, String? retryLabel, bool showRestart, StackTrace? stackTrace, String? subtitle, required String title}): A builder for an error view widget.
FeaturesBuilder = FutureOr<List<FeatureDescriptor>> Function(): The builder function that creates a set of features.
ImagePlaceholderBuilder = Widget Function(BuildContext context, {double? height, double? width}): A builder for an image placeholder widget.
LazyFeaturesBuilder = List<LazyFeatureDescriptor> Function(): A builder that returns lazy feature descriptors.
Loader = Widget Function(BuildContext context): A builder for a widget that is shown when the app is loading.
RouteBuilderFunction = FutureOr<List<RouteBase>?> Function(): A function that returns a list of routes.
RouteErrorViewBuilder = Widget Function(BuildContext context, {dynamic error, VoidCallback? onRetry, String? retryLabel, StackTrace? stackTrace, String? subtitle, required String title}): A builder for a route error view widget.
RouteLoader = Widget Function(BuildContext context, [Uri? url, String? routeId]): A builder for a widget that is shown when a route is loading.
VoidFutureFunction = Future<void> Function(): A function that returns a void Future.
VyuhEventListener<T extends VyuhEvent> = void Function(T event): A function that handles events of type T.

Exceptions / Errors

AuthException: Base type for all Authentication related exceptions.
CreateUserFailure: Exception thrown when creating a user fails.
DeleteAccountFailure: Exception thrown when the account deletion fails.
LoginMethodCanceled: Exception thrown when a login method is canceled.
LoginMethodFailure: Exception thrown when a login method fails.
LogoutFailure: Exception thrown when the logout fails.
SendEmailLinkFailure: Exception thrown when sending an email-link for logging in.
SendPasswordResetEmailFailure: Exception thrown when sending a password reset email.

vyuh_core library

Classes

Enums

Mixins

Extensions

Properties

Functions

Typedefs

Exceptions / Errors

vyuh_core package

vyuh_core library