fiber_router

Typed navigation layer built on go_router - declarative view, node, and shell routes with fade transitions and code-generated BuildContext extensions.

Designed to work with fiber_router_gen, the companion code generator that produces typed navigation helpers from your router definition.

Features

  • Declarative route tree via FiberRouteNode.view(), .node(), .shell(), .controller(), and .deeplink()
  • Shell routes - persistent UI wrapper (e.g. auth layout) while inner routes change
  • Controller routes - hybrid shell + navigable route that auto-redirects to its first leaf
  • Typed navigation - context.go<MyView, MyParams>() instead of string paths
  • Fade & system transitions out of the box
  • @FiberRouterGen() annotation - marks the router variable for code generation
  • NavigatorFadeTransition - fade PageRoute for local Navigator push

Installation

dependencies:
  fiber_router: ^1.0.0

Usage

1. Define your router

import 'package:fiber_router/fiber_router.dart';

@FiberRouterGen()
final router = FiberRouter.create(
  initialLocation: const HomeView(),
  refreshListenable: myAuthNotifier,
  redirect: (context, state) {
    if (!myAuthNotifier.isSignedIn) return const SignInView();
    return null;
  },
  nodes: [
    // Simple view route
    FiberRouteNode.view<HomeView, Null>(
      transition: RouteTransition.fade,
      builder: (_, __) => const HomeView(),
    ),

    // Named group with sub-routes
    FiberRouteNode.node(
      name: 'dashboard',
      main: FiberRouteNode.view<DashboardView, Null>(
        builder: (_, __) => const DashboardView(),
      ),
      routes: [
        FiberRouteNode.view<SettingsView, Null>(
          builder: (_, __) => const SettingsView(),
        ),
      ],
    ),

    // Shell route - layout persists, inner content changes
    FiberRouteNode.shell(
      builder: (context, child) => AuthShell(child: child),
      routes: [
        FiberRouteNode.view<SignInView, Null>(
          transition: RouteTransition.fade,
          builder: (context, _) => SignInView(
            onRequiresOtp: (token) => context.go<OtpView, OtpParams>(OtpParams(token: token)),
          ),
        ),
        FiberRouteNode.view<OtpView, OtpParams>(
          transition: RouteTransition.fade,
          builder: (_, params) => OtpView(token: params?.token ?? ''),
        ),
      ],
    ),

    // Deeplink route - parameters from query string
    FiberRouteNode.deeplink<InviteView, InviteParams>(
      fromQuery: InviteParams.fromMap,
      builder: (_, params) => InviteView(params: params),
    ),
  ],
);

2. Navigate

// Navigate to a route (replaces current)
context.go<HomeView, Null>(replace: true);

// Navigate with parameters
context.go<OtpView, OtpParams>(OtpParams(token: token));

// Check current route
if (state.isOn<DashboardView>()) { ... }

3. Shell route

A shell route renders a persistent wrapper widget while swapping its inner child as routes change. Useful for layouts that must stay on screen (e.g. auth shell with background image).

class AuthShell extends StatelessWidget {
  final Widget child;
  const AuthShell({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Row(
        children: [
          Expanded(child: child), // SignInView or OtpView renders here
          const AuthBackground(),
        ],
      ),
    );
  }
}

4. Code generation

Annotate your router variable with @FiberRouterGen() and run the generator:

dart run fiber_router_gen lib/src/router/router.dart

This produces a typed router.g.dart with BuildContext extensions:

// Generated
context.router.dashboard.go();
context.router.dashboard.settings.go();

5. Local navigator fade transition

For push navigation inside a local Navigator:

navigatorKey.currentState?.push(
  NavigatorFadeTransition(OtpView(token: pendingToken)),
);

Route types

Factory Description
FiberRouteNode.view<T, P>() Single screen route
FiberRouteNode.node() Named group with optional main route and sub-routes
FiberRouteNode.shell() Shell wrapper - layout persists across inner routes, not directly navigable
FiberRouteNode.controller<T>() Shell wrapper that is also a named route at /<T>; navigating to it redirects to first leaf
FiberRouteNode.deeplink<T, P>() Route with query-string parameter deserialization

Transitions

Value Behavior
RouteTransition.fade Cross-fade
RouteTransition.system Platform default (Cupertino slide on iOS, fade on others)

Libraries

annotation
controller
fiber_router