go_router_deferred #

A Flutter package that provides extensions for go_router to support deferred loading and lazy initialization of routes.

Features #

• Deferred Route Loading: Load routes lazily to improve initial app startup time
• Shell Route Support: Deferred loading for shell routes
• Stateful Shell Route Support: Deferred loading for stateful shell routes
• Type Safety: Full type safety with Dart's null safety
• Easy Integration: Simple setup with existing go_router configurations

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  go_router_deferred: ^1.0.1
  go_router: ^16.1.0

Usage #

Basic Deferred Route #

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:go_router_deferred/go_router_deferred.dart';

// Import with deferred loading
import 'screens/settings_screen.dart' deferred as settings_screen;

final router = GoRouter(
  routes: [
    DeferredRoute.setup(
      path: '/settings',
      loadLibrary: settings_screen.loadLibrary,
      builder: (context, state) => settings_screen.SettingsScreen(),
    ),
  ],
);

Deferred Shell Route #

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:go_router_deferred/go_router_deferred.dart';

// Import with deferred loading
import 'shell/app_shell.dart' deferred as app_shell;
import 'screens/home_screen.dart' deferred as home_screen;
import 'screens/profile_screen.dart' deferred as profile_screen;

final router = GoRouter(
  routes: [
    DeferredShellRoute.setup(
      parentNavigatorKey: _shellNavigatorKey,
      loadLibrary: app_shell.loadLibrary,
      builder: (context, state, child) => app_shell.AppShell(child: child),
      routes: [
        GoRoute(
          path: '/home', 
          builder: (context, state) => home_screen.HomeScreen()
        ),
        GoRoute(
          path: '/profile', 
          builder: (context, state) => profile_screen.ProfileScreen()
        ),
      ],
    ),
  ],
);

Deferred Stateful Shell Route #

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:go_router_deferred/go_router_deferred.dart';

// Import with deferred loading
import 'shell/app_shell.dart' deferred as app_shell;
import 'screens/home_screen.dart' deferred as home_screen;
import 'screens/profile_screen.dart' deferred as profile_screen;

final router = GoRouter(
  routes: [
    DeferredStatefulShellRoute.setup(
      parentNavigatorKey: _shellNavigatorKey,
      loadLibrary: app_shell.loadLibrary,
      builder: (context, state, navigationShell) => app_shell.AppShell(navigationShell: navigationShell),
      branches: [
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/home', 
              builder: (context, state) => home_screen.HomeScreen()
            ),
          ],
        ),
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/profile', 
              builder: (context, state) => profile_screen.ProfileScreen()
            ),
          ],
        ),
      ],
    ),
  ],
);

Advanced Usage #

With Redirect Logic #

import 'screens/admin_screen.dart' deferred as admin_screen;

DeferredRoute.setup(
  path: '/admin',
  loadLibrary: admin_screen.loadLibrary,
  builder: (context, state) => admin_screen.AdminScreen(),
  redirect: (state) async {
    // Check if user has admin access
    if (!await AuthService.isAdmin()) {
      return '/unauthorized';
    }
    return null;
  },
);

With Custom Page Builder #

import 'screens/modal_screen.dart' deferred as modal_screen;

DeferredRoute.setup(
  path: '/modal',
  loadLibrary: modal_screen.loadLibrary,
  pageBuilder: (context, state) => MaterialPage(
    child: modal_screen.ModalScreen(),
    fullscreenDialog: true,
  ),
);

Benefits #

1. Faster Startup: Routes are loaded only when needed
2. Reduced Memory Usage: Unused route code is not loaded into memory
3. Better Performance: Smaller initial bundle size
4. Modular Architecture: Easier to organize code into feature modules

Best Practices #

1. Use Deferred Imports: Always use import 'file.dart' deferred as alias; pattern
2. Group Related Routes: Use deferred loading for feature modules
3. Minimize Dependencies: Keep deferred imports minimal
4. Error Handling: Handle import failures gracefully
5. Testing: Test deferred routes thoroughly

Example Project Structure #

lib/
├── main.dart
├── router/
│   └── app_router.dart
├── features/
│   ├── home/
│   │   ├── home_screen.dart
│   │   └── home_module.dart
│   ├── settings/
│   │   ├── settings_screen.dart
│   │   └── settings_module.dart
│   └── admin/
│       ├── admin_screen.dart
│       └── admin_module.dart
└── shell/
    └── app_shell.dart

Contributing #

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License #

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