Nav Bridge #

A progressive, router-agnostic navigation layer for Flutter that allows you to wrap existing GoRouter apps and migrate to a clean, testable, decoupled architecture — without rewriting your routes.

Why Nav Bridge? #

Flutter apps are usually tightly coupled to a routing library:

// ❌ Your business logic depends on GoRouter
context.go('/users/42');
context.push('/settings');

This creates several problems:

• Vendor lock-in: Business logic depends on GoRouter/AutoRoute
• Untestable: Navigation requires Flutter widgets
• Expensive migrations: Changing routers means rewriting navigation
• Tight coupling: UI and routing are inseparable

Nav Bridge solves this with a thin abstraction layer:

// ✅ Your app talks to AppRouter, not GoRouter
appRouter.goToUserProfile('42');

Key Features #

Installation #

dependencies:
  nav_bridge: ^2.0.0
  go_router: ^15.0.0

  # Optional - for Riverpod guards
  flutter_riverpod: ^2.4.0

flutter pub get

Quick Start #

Step 1: Wrap Your Existing Router #

Zero changes to your existing code:

import 'package:nav_bridge/nav_bridge.dart';

// Your existing GoRouter (unchanged)
final goRouter = GoRouter(
  routes: [...],
  redirect: myRedirectLogic,
);

// Wrap it with Nav Bridge
final adapter = GoRouterAdapter.wrap(goRouter);

// Everything still works!
context.go('/profile/42');  // ✅ Still works

Step 2: Add Guards with DI Support #

final adapter = GoRouterAdapter.wrap(
  goRouter,
  additionalGuards: [AuthGuard(), RoleGuard()],
);

// Inject dependencies (Riverpod Ref, etc.)
adapter.contextBuilder = (state) => {
  'ref': ref,
  'goRouterState': state,
  'context': navigatorKey.currentContext,
};

Step 3: Create Type-Safe Navigation (Optional) #

abstract class AppRouter {
  Future<void> goToHome();
  Future<void> goToUserProfile(String userId);
}

class MyAppRouter implements AppRouter {
  final GoRouterAdapter _adapter;

  MyAppRouter(this._adapter);

  @override
  Future<void> goToUserProfile(String userId) =>
      _adapter.go('/profile/$userId');
}

Guards #

Modern Riverpod Guards #

class AuthGuard extends RiverpodRouteGuard {
  @override
  int get priority => 100;  // Higher = runs first

  @override
  List<String>? get excludes => ['/login', '/register'];

  @override
  Future<GuardResult> canActivateWithRef(
    GuardContext context,
    Ref ref,
  ) async {
    final isAuthenticated = ref.read(authProvider).isAuthenticated;

    if (!isAuthenticated) {
      return GuardResult.redirect('/login');
    }

    return GuardResult.allow();
  }
}

Bridge Existing Guards (Zero Rewrite) #

Already have guards? Bridge them without any changes:

// Your existing guard function
FutureOr<GuardResult> myExistingGuard(
  BuildContext context,
  GoRouterState state,
  Ref ref,
) async {
  // Your existing logic...
}

// Bridge it - zero changes needed!
final bridgedGuard = GoRouterGuardBridge(myExistingGuard);

Guard Result Types #

sealed class GuardResult {
  // Allow navigation
  static GuardAllow allow();

  // Redirect to another path
  static GuardRedirect redirect(String path, {Map<String, dynamic>? extra});

  // Block navigation
  static GuardReject reject({String? reason});
}

Unit Testing #

Test navigation without Flutter widgets:

void main() {
  group('Navigation', () {
    test('authenticated user can access profile', () async {
      final router = InMemoryAdapter(
        guards: [MockAuthGuard(isAuthenticated: true)],
      );

      await router.go('/profile/42');

      expect(router.currentLocation, '/profile/42');
    });

    test('unauthenticated user is redirected to login', () async {
      final router = InMemoryAdapter(
        guards: [MockAuthGuard(isAuthenticated: false)],
      );

      await router.go('/profile/42');

      expect(router.currentLocation, '/login');
    });

    test('tracks navigation history', () async {
      final router = InMemoryAdapter();

      await router.go('/');
      await router.push('/profile/42');
      await router.push('/settings');

      expect(router.navigationHistory, ['/', '/profile/42', '/settings']);

      router.pop();
      expect(router.currentLocation, '/profile/42');
    });
  });
}

Progressive Migration Guide #

Phase 1: Wrap (Day 1) #

// Just wrap, nothing else changes
final adapter = GoRouterAdapter.wrap(existingRouter);

Phase 2: Bridge Guards (Week 1) #

// Bridge existing guards
final bridged = GoRouterGuardBridge(existingGuard);

Phase 3: Add AppRouter (Week 2) #

// Create type-safe navigation
abstract class AppRouter {
  Future<void> goToProfile(String id);
}

Phase 4: Migrate Features (Ongoing) #

// Old and new coexist
context.go('/old');           // Old code ✅
appRouter.goToProfile('42');  // New code ✅

Architecture #

┌─────────────────────────────────────────────────────────┐
│                    Feature Code                          │
│              (Uses AppRouter interface)                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                     AppRouter                            │
│            (Your type-safe abstraction)                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                     Nav Bridge                           │
│         (Guards, DI, Navigation abstraction)             │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              GoRouterAdapter.wrap()                      │
│            (Wraps your existing router)                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Your Existing GoRouter                      │
│          (Routes, Shell, everything intact)              │
└─────────────────────────────────────────────────────────┘

API Reference #

Adapters #

Guards #

Core Classes #

Roadmap #

• ✅ GoRouter wrap mode
• ✅ Riverpod guard support
• ✅ Guard bridge adapters
• ✅ InMemoryAdapter for testing
• ✅ Shell navigation support
• ❌ AutoRoute adapter
• ❌ Beamer adapter
• ❌ Typed route code generation
• ❌ Analytics observers
• ❌ Transition abstraction

When Should You Use This? #

Community #

• Report bugs
• Request features
• Read the docs
• Discussions

Contributing #

Contributions are welcome! Please read our Contributing Guide first.

# Clone the repo
git clone https://github.com/chekarhamza88-stack/nav_bridge.git

# Install dependencies
flutter pub get

# Run tests
flutter test

# Check analysis
flutter analyze

License #

MIT License - see LICENSE for details.

Nav Bridge doesn't replace GoRouter.
It makes GoRouter testable, replaceable, decoupled, and enterprise-ready.

Made with love by chekarhamza88-stack