Route Guards

What are Route Guards?

Route Guards provide middleware-style navigation protection for your applications. Think of them as security checkpoints that can allow, redirect, or block navigation based on your custom logic.

🛡️ Middleware Pattern

Clean, composable guards that intercept navigation attempts before they reach your screens.

🔧 Framework Agnostic

Core guard logic works with any routing system. Framework-specific integrations provide seamless developer experience.

⚡ Composable Logic

Combine simple guards into complex protection schemes with logical operators: AND, OR, XOR.

🎯 Precise Control

Fine-grained control over which routes are protected, with inclusion/exclusion patterns and conditional logic.

Core Concept

Every guard implements a simple middleware pattern:

class AuthGuard extends RouteGuard {
  @override
  FutureOr<void> onNavigation(
    NavigationResolver resolver,
    Object context,
    Object state,
  ) async {
    if (await isAuthenticated()) {
      resolver.next(); // ✅ Allow navigation
    } else {
      resolver.redirect('/login'); // 🔀 Redirect to login
    }
  }
}

Guards receive a resolver that controls the navigation flow:

• resolver.next() - Allow navigation to continue
• resolver.redirect('/path') - Redirect to a different route
• resolver.block() - Block navigation entirely

Architecture

route_guards

Framework-agnostic foundation providing:

• Base RouteGuard class
• NavigationResolver pattern
• Guard composition utilities
• Works with any router

Framework Packages

Specialized integrations for popular frameworks:

• go_router_guards - Flutter Go Router integration
• More integrations coming soon…

Guard Composition

Combine guards to create sophisticated protection:

// All guards must pass (AND logic)
final adminGuard = Guards.all([
  AuthGuard(),
  RoleGuard(['admin']),
  PermissionGuard(['manage_users']),
]);

// Any guard can pass (OR logic)
final accessGuard = Guards.anyOf([
  SubscriptionGuard(),
  StaffAccessGuard(),
  BetaTesterGuard(),
]);

// Exactly one guard must pass (XOR logic)
final exclusiveGuard = Guards.oneOf([
  DevelopmentModeGuard(),
  ProductionAccessGuard(),
]);

Real-World Use Cases

Authentication

Protect authenticated routes, handle login flows, manage session validation.

Authorization

Role-based access control, permission systems, organizational hierarchies.

Business Logic

Subscription gates, feature flags, trial limitations, geographic restrictions.

Security

Rate limiting, device verification, suspicious activity detection, compliance checks.

Multi-Tenant

Tenant isolation, cross-tenant security, workspace-specific access control.

A/B Testing

Experiment-based routing, feature rollouts, user segmentation.

Framework Integration Example

Here’s how it looks with Go Router integration:

// Type-safe route with guards
@TypedGoRoute<AdminRoute>(path: '/admin')
class AdminRoute extends GoRouteData with GuardedRoute {
  @override
  RouteGuard get guards => Guards.all([
    AuthGuard(),
    RoleGuard(['admin']),
  ]);

  @override
  Widget build(context, state) => AdminScreen();
}

// Traditional route with guards
GoRoute(
  path: '/admin',
  builder: (context, state) => AdminScreen(),
  redirect: RouteGuardUtils.createGuardRedirect(
    Guards.all([AuthGuard(), RoleGuard(['admin'])]),
  ),
)

Key Benefits

• 🔒 Security First: Fail securely with proper error handling
• 📦 Reusable: Write once, use everywhere
• 🧪 Testable: Clean interfaces make testing straightforward
• ⚡ Performant: Efficient execution with caching support
• 🛠️ Developer Friendly: Clear patterns and comprehensive documentation
• 🌐 Production Ready: Used in real applications with enterprise requirements

Get Started

📦 Installation

Add route guards to your project

⚡ Quick Start

Create your first guard in 5 minutes

🏗️ Core Package

Framework-agnostic foundation

🎯 Go Router

Flutter Go Router integration

---

Route Guards - Secure navigation made simple