🍬 Go Router Sugar

The Simplest Flutter Routing Ever - Revolutionary CLI that transforms complex routing into simple commands and auto-magic route generation.

🎯 Why Go Router Sugar?

Before: Hours of complex routing configuration, manual route definitions, string-based navigation prone to typos.

After: Simple CLI commands, auto-magic route generation, beautiful visualizations, and 100% type-safe navigation!

Every feature designed to eliminate confusion, reduce code, and prevent errors:

• ⚡ Instant App Creation - Complete Flutter apps in seconds
• 🧠 Smart Parameter Detection - Constructor parameters = Route parameters (zero config)
• 🛡️ Smart Route Guards - Interface-based auth with @Protected annotation
• 📁 File System = Route Map - Your folder structure IS your routing
• 🔒 100% Type Safety - Impossible to make navigation typos
• 🎨 Beautiful Transitions - Professional animations with one line
• 👀 Real-time Watch Mode - Auto-regeneration on file changes
• 🗺️ Visual Route Maps - Beautiful console visualization of your routes

✅ Compatibility

• Dart SDK: >=3.0.0 <4.0.0
• Flutter: >=3.10.0
• Go Router: >=10.0.0

🚀 Revolutionary Features

⚡ Instant App Creation

# Create complete Flutter apps in seconds
dart run go_router_sugar new my_app --template minimal
cd my_app && flutter run  # Complete app ready!

Available templates:

• minimal - Clean starter with navigation setup

🧠 Smart Parameter Detection (Zero Configuration!)

// ✅ Your constructor IS your route config (no setup needed!)
class ProductPage extends StatelessWidget {
  final String productId;    // Auto-becomes /products/:productId  
  final String? category;    // Auto-becomes ?category=value
  final int? page;          // Auto-parsed from ?page=1
  final bool featured;      // Auto-parsed from ?featured=true
  
  const ProductPage({
    super.key,
    required this.productId,  // Required = Path parameter
    this.category,            // Optional = Query parameter
    this.page,               // Nullable = Optional query
    this.featured = false,   // Default = Optional with fallback
  });
  
  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: Text('Product $productId')),
    body: Column(children: [
      Text('Category: ${category ?? "All"}'),
      Text('Page: ${page ?? 1}'),
      Text('Featured: $featured'),
    ]),
  );
}

Magic happens automatically:

• Required parameters → Path parameters (:productId)
• Optional parameters → Query parameters (?category=value)
• Types auto-parsed (String, int, bool, double)
• Null safety respected throughout

🛡️ Smart Route Guards (Zero Configuration!)

// ✅ Simple interface implementation = Instant auth protection
class AuthGuard implements RouteGuard {
  @override
  Future<bool> canActivate(BuildContext context, Map<String, String> params) async {
    return UserService.isLoggedIn;
  }
  
  @override
  String? get redirectRoute => '/login';
}

// ✅ One annotation = Protected route
@Protected(AuthGuard)
class ProfilePage extends StatelessWidget {
  // Page automatically protected - zero configuration!
}

📁 File-Based Routing (Zero Boilerplate)

lib/pages/
├── products/[id]_page.dart         → /products/:id  
├── auth/login_page.dart            → /auth/login
├── user/profile/settings_page.dart → /user/profile/settings
## 🔥 The Zero-Ambiguity Advantage

### ❌ Before: Complex Manual Configuration
```dart
// 50+ lines of repetitive GoRoute configuration
GoRouter(
  routes: [
    GoRoute(
      path: '/products/:id',
      builder: (context, state) {
        final id = state.pathParameters['id']!; // Runtime error risk!
        final category = state.uri.queryParameters['category'];
        final pageStr = state.uri.queryParameters['page'];
        final page = pageStr != null ? int.tryParse(pageStr) : null;
        return ProductPage(id: id, category: category, page: page);
      },
    ),
    // ...endless boilerplate for every route
  ],
);

// String-based navigation (typo = crash!)
context.go('/prodcuts/123?category=electronics'); // Oops! Typo = runtime error

✅ After: Zero-Ambiguity Magic

// 🎯 Your constructor IS your route config
class ProductPage extends StatelessWidget {
  final String productId;    // Auto-becomes /products/:productId  
  final String? category;    // Auto-becomes ?category=value
  final int? page;          // Auto-parsed from ?page=1
  
  const ProductPage({
    super.key,
    required this.productId,  // Required = Path parameter
    this.category,            // Optional = Query parameter  
    this.page,               // Nullable = Optional query
  });
}

// 🎯 100% type-safe navigation
Navigate.goToProduct(
  productId: '123',         // ✅ Required parameter - impossible to forget!
  category: 'electronics',  // ✅ Optional parameter - perfect IntelliSense
  page: 2,                 // ✅ Type-safe int - no parsing errors
);

🚀 The Result: 90% Less Code, 100% More Safety

• 5 minutes setup vs. hours of manual configuration
• Zero boilerplate - your file system is your route map
• Type-safe navigation - impossible to make typo errors
• Smart parameter detection - constructor parameters become route parameters
• Zero-config guards - simple interfaces for route protection
• Instant app creation - complete apps generated in seconds

🚀 Quick Start

1. Instant App Creation (Recommended)

Create a complete Flutter app with routing in seconds:

# Create app with instant routing setup
dart run go_router_sugar new my_app --template minimal
cd my_app && flutter run

Available templates:

• minimal - Clean starter with navigation setup

🧹 Clean & Unified Architecture (v1.2.1)

Go Router Sugar now features a completely unified architecture with zero ambiguities:

• ✅ Single Source of Truth - No duplicate classes or conflicting implementations
• ✅ Comprehensive Help System - Every command supports --help with beautiful output
• ✅ Smart Guards Unified - Single, powerful guard system with @Protected annotations
• ✅ Clean CLI Structure - Consistent command interface across all operations
• ✅ Zero Conflicts - All architectural duplications eliminated

# Get help for any command
dart run go_router_sugar --help
dart run go_router_sugar generate --help
dart run go_router_sugar watch --help
dart run go_router_sugar visual --help
dart run go_router_sugar new --help

Choose your instant app:

• minimal - Clean starter with navigation
• ecommerce - Products, cart, checkout, profile
• auth - Complete authentication flow

✨ All Features at a Glance

Core Zero-Ambiguity Features:

• ⚡ Instant App Creation - Complete Flutter apps in seconds with templates
• 🧠 Smart Parameter Detection - Constructor parameters become route parameters automatically
• 🛡️ Zero-Config Route Guards - Simple interface implementation for authentication
• 📁 File-Based Routing - Your file system becomes your route map
• 🔒 100% Type Safety - Impossible to make navigation typos
• 🎨 Beautiful Transitions - Professional animations with one line

Advanced Capabilities:

• 🚀 Zero Boilerplate - Automatically generates GoRouter configuration
• ⚡ Dynamic Routes - Built-in support for path parameters using [param] syntax
• 🎯 Flutter-First - Designed specifically for Flutter's ecosystem
• 📱 Hot Reload Friendly - Works seamlessly with Flutter's development workflow
• 🔧 Progressive Enhancement - Simple start, powerful when needed

📖 Documentation

2. Manual Setup (For Existing Projects)

Add dependencies:

dependencies:
  flutter:
    sdk: flutter
  # go_router is automatically included as a dependency

dev_dependencies:
  go_router_sugar: ^1.2.1

Note: You don't need to manually add go_router to your pubspec.yaml - it's automatically included as a dependency of go_router_sugar.

5. Create Your Pages

Create your page files in lib/pages/ (or your preferred directory). Page files must end with _page.dart.

lib/
├── pages/
│   ├── home_page.dart              # Route: /home
│   └── products/
│       └── [id]_page.dart          # Dynamic route: /products/:id
└── main.dart

Simple page example (lib/pages/home_page.dart):

import 'package:flutter/material.dart';

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: const Center(
        child: Text('Welcome Home!'),
      ),
    );
  }
}

Page with smart parameters (lib/pages/products/[id]_page.dart):

import 'package:flutter/material.dart';

class ProductPage extends StatelessWidget {
  final String id;          // ✅ Auto-injected from route path
  final String? category;   // ✅ Auto-injected from query params
  final int? page;         // ✅ Auto-parsed to correct type

  const ProductPage({
    super.key, 
    required this.id,
    this.category,
    this.page,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Product $id')),
      body: Center(
        child: Column(
          children: [
            Text('Product ID: $id'),
            if (category != null) Text('Category: $category'),
            if (page != null) Text('Page: $page'),
          ],
        ),
      ),
    );
  }
}

6. Generate Your Routes

Run the code generator to create your app_router.g.dart file.

🌟 Option 1: Use the Smart CLI (Recommended)

# Generate routes for existing project
dart run go_router_sugar generate

# Watch for file changes (perfect for development)  
dart run go_router_sugar watch

# Visualize your route tree
dart run go_router_sugar visual

# Get help for any command
dart run go_router_sugar generate --help

⚙️ Option 2: Use the Standard Dart Build Runner

# Run the generator once
dart run build_runner build --delete-conflicting-outputs

# Watch for file changes
dart run build_runner watch --delete-conflicting-outputs

7. Use the Generated Router

In your main.dart, import the generated file and configure your MaterialApp.router.

import 'package:flutter/material.dart';
import 'app_router.g.dart'; // Generated file

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      title: 'My App',
      routerConfig: AppRouter.router,
    );
  }
}

8. Navigate with Type-Safety

Forget string-based paths and runtime errors. Use the generated, type-safe navigation helpers for 100% safety and IDE autocomplete.

import 'package:flutter/material.dart';
import 'app_router.g.dart'; // Import the generated file

// Option 1: Static Navigate class (simple and direct)
Navigate.goToHome();
Navigate.goToProduct(id: 'abc-123', category: 'electronics', page: 2);

// Option 2: GoRouter/BuildContext extension methods (fluent and idiomatic)
context.goToHome();
context.goToProduct(id: 'abc-123', category: 'electronics', page: 2);

While you can still use raw strings with the generated Routes constants (context.go(Routes.home)), the navigation helpers are the recommended, safer approach.

✨ Features

• 🚀 Zero Boilerplate: Automatically generates GoRouter configuration.
• 📁 File-Based Routing: Your file system becomes your route map.
• � Smart Parameter Detection: Constructor parameters become route/query parameters automatically.
• 🛡️ Zero-Config Route Guards: Simple interface implementation for authentication.
• �🎨 Rich Page Transitions: 15+ built-in transition types with zero effort.
• 🔧 Instant App Creation: Complete apps with dart run go_router_sugar new my_app.
• � Progressive Enhancement: Simple start, powerful when needed.
• ⚡ Dynamic Routes: Built-in support for path parameters using [param] syntax.
• 🎯 Flutter-First: Designed specifically for Flutter's ecosystem.
• 📱 Hot Reload Friendly: Works seamlessly with Flutter's development workflow.
• 🎭 Per-Page Transitions: Configure transitions individually for each page.
• 🗂️ Shell Routes: Automatic layout detection for nested navigation.
• 📊 Query Parameters: Type-safe query parameter handling with automatic parsing.
• 📈 Analytics: Built-in route analytics and performance monitoring.
• 🛠️ Smart CLI: Template-based app creation and intelligent generation.
• 🔌 VS Code Extension (Planned): Rich IDE integration with IntelliSense and code actions.

🎨 Page Transitions

Go Router Sugar includes a comprehensive transition system with 10+ built-in animation types.

Available Transition Types

Using Transitions

Annotate your page widget with @PageTransition to specify an animation.

import 'package:flutter/material.dart';
import 'package:go_router_sugar/go_router_sugar.dart';

// Use a simple preset
@PageTransition(TransitionConfig.fade)
class AboutPage extends StatelessWidget {
  const AboutPage({super.key});
  // ... widget implementation
}

// Customize the transition
@PageTransition(TransitionConfig(
  type: PageTransitionType.slideUp,
  duration: Duration(milliseconds: 400),
  curve: Curves.easeInOutCubic,
))
class ModalPage extends StatelessWidget {
  const ModalPage({super.key});
  // ... widget implementation
}

🔧 Configuration

Customize the generator's behavior using CLI flags or a build.yaml file.

Method 1: CLI Flags (Recommended for one-offs)

Use command-line flags for quick, temporary changes.

# Generate with a custom pages directory
dart run go_router_sugar --pages-dir lib/screens

# Specify a different output file
dart run go_router_sugar --output lib/config/app_routes.g.dart

# Combine flags
dart run go_router_sugar --pages-dir lib/views -o lib/my_router.g.dart

Method 2: build.yaml (Recommended for teams/projects)

For permanent configuration that you can commit to version control, create a build.yaml file in your project root. This is the best way to ensure your entire team uses the same settings.

targets:
  $default:
    builders:
      go_router_sugar|routes:
        options:
          # Directory containing your page files.
          pages_directory: "lib/pages"
          
          # Whether to generate type-safe navigation helpers.
          generate_navigation_helpers: true
          
          # Name of the generated router class.
          router_class_name: "AppRouter"
          
          # Output file path.
          output_file: "lib/app_router.g.dart"

📝 File Naming Conventions

• Page files must end with _page.dart.
• Dynamic parameters use square brackets: [id]_page.dart, [slug]_page.dart.
• Nested routes follow your directory structure.

🛠️ Generated Code

The generator creates a single file (app_router.g.dart) with several helpful utilities.

1. Router Configuration

A ready-to-use GoRouter instance.

class AppRouter {
  static final GoRouter router = GoRouter(routes: [...]);
}

2. Route Constants

String constants for all your routes.

abstract class Routes {
  static const String home = '/home';
  static const String productsId = '/products/:id';
  // ... more routes
}

3. Type-Safe Navigation

Static methods and extension methods for safe, easy navigation.

// Static helper class
class Navigate {
  static void goToHome() => AppRouter.router.go('/home');
  static void pushToProductsId({required String id}) => 
    AppRouter.router.push('/products/$id');
}

// Extension on GoRouter/BuildContext
extension AppRouterNavigation on GoRouter {
  void goToHome() => go('/home');
  void pushToProductsId({required String id}) => push('/products/$id');
}

🧪 Example Projects

Explore our examples to see the package in action.

Minimal Example (Quick Start)

Demonstrates basic file-based routing.

cd example/minimal
flutter pub get
dart run go_router_sugar
flutter run

Full Example (All Features)

Showcases advanced features like transitions, guards, and nested routing.

cd example
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter run

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details on how to submit pull requests and report issues.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

• 📖 Documentation: https://github.com/mukhbit0/go_router_sugar
• 🐛 Issue Tracker: https://github.com/mukhbit0/go_router_sugar/issues
• 💬 Discussions: https://github.com/mukhbit0/go_router_sugar/discussions

Made with ❤️ for the Flutter community.