orbital

Convenience bundle that reexports the full Orbital runtime from a single import.

When to use this package

Use orbital when you want:

  • one import for core contracts, injector, router and state
  • the default scope runtime available immediately
  • the convenience enableOrbitalDevtools(...) wrapper in the same package
import 'package:orbital/orbital.dart';

Choose the individual packages when you want tighter dependency boundaries:

  • orbital_core for contracts, logging and debug primitives
  • orbital_injector for scope trees without Flutter routing
  • orbital_router for Flutter navigation on top of Orbital scopes
  • orbital_state for the reactive StateMixin<T> on OrbitalLifecycle objects
  • orbital_devtools for the Flutter DevTools extension UI

Quick start

final router = OrbitalRouter(
  scopeFactory: const DefaultOrbitalScopeFactory(),
  initialUri: Uri.parse('/'),
  modules: [
    OrbitalModule(
      path: '/',
      routes: [
        OrbitalPageRoute(
          path: '/',
          builder: (context, routeContext) => const HomePage(),
        ),
      ],
    ),
  ],
);

MaterialApp.router(
  routerConfig: router,
);

Installing the DevTools extension

Flutter DevTools discovers package extensions from the app package config. Add orbital_devtools to the app's dev_dependencies so the Orbital tab appears while debugging:

dev_dependencies:
  orbital_devtools: ^0.2.2

That's it — OrbitalRouter auto-enables the DevTools bridge in debug builds as soon as it's created, so no application code is required for the common case. Pass devtoolsAppId on OrbitalRouter to customize the app id, or enableDevtoolsBridge: false to opt out.

For custom setups (e.g. enabling the bridge before a router exists, or with a different logger/appId than the router uses), call enableOrbitalDevtools(...) directly:

final logger = OrbitalLogger();
enableOrbitalDevtools(logger: logger, appId: 'my-app');

The bridge is a singleton and the first enabler owns it. If OrbitalRouter already auto-enabled it, a later enableOrbitalDevtools(...) call does not replace it — it returns the router's existing bridge, so the router's logger and appId win. Enable the bridge before constructing the router to use your own logger/appId, or construct the router with enableDevtoolsBridge: false.

What the bundle reexports

  • all public APIs from orbital_core
  • all public APIs from orbital_injector
  • all public APIs from orbital_router
  • all public APIs from orbital_state
  • enableOrbitalDevtools(...), a convenience wrapper around OrbitalDebugBridge.enable(...)

Design intent

The bundle adds almost no new runtime behavior. Its value is ergonomic:

  • single-import app bootstrapping
  • aligned versions of the Orbital packages
  • one obvious entrypoint for example apps and app-level tests

The underlying behavior still lives in the granular packages.

More detail

See doc.md for package relationships, lifecycle flow and when to use the bundle versus granular imports.

Libraries

orbital