tp_router 0.5.0

A simplified Flutter router based on go_router with annotation support.

TpRouter

Package	Version
tp_router
tp_router_annotation
tp_router_generator

A simplified, type-safe, and annotation-driven routing library for Flutter.

TpRouter eliminates the need for manual routing tables. By simply using NavKey to establish relationships between pages, it automatically generates the entire routing tree—including complex nested shells.

✨ Key Features

• 🗝️ NavKey-Driven Linking: No more nesting hell. Just tell a route "My parent is MainNavKey", and they are automatically linked.
• 📐 Type-Safe Navigation: UserRoute(id: 1).tp() instead of string manipulation.
• 🐚 Simple Shells: Define app layouts (BottomNav, Drawers) purely through annotations.
• 🧩 Smart Code Gen: Automatically handles parameters, return values, and deep linking.

---

🛠️ Installation

Add the following to your pubspec.yaml:

dependencies:
  tp_router: ^0.1.0
  tp_router_annotation: ^0.1.0

dev_dependencies:
  build_runner: ^2.4.0
  tp_router_generator: ^0.1.0

Run the generator:

dart run build_runner build

---

🚀 Quick Start

1. Define NavKeys

NavKeys are the heart of TpRouter. They act as unique identifiers for your navigators and bridges between parents and children.

Create a file lib/routes/nav_keys.dart:

import 'package:tp_router/tp_router.dart';

// Key for the main application shell (e.g. BottomNavigationBar)
class MainNavKey extends TpNavKey {
  const MainNavKey() : super('main');
}

// Sub-keys for branches if you use IndexedStack (optional but recommended)
class HomeNavKey extends TpNavKey {
  const HomeNavKey() : super('main', branch: 0);
}

class SettingsNavKey extends TpNavKey {
  const SettingsNavKey() : super('main', branch: 1);
}

2. Define Layouts (Shells)

Mark your container widget (e.g., a page with BottomNavigationBar) with @TpShellRoute. Link it to a key (MainNavKey).

@TpShellRoute(
  navigatorKey: MainNavKey, // <--- Identified by this Key
  isIndexedStack: true,     // Enable stateful nested navigation
  branchKeys: [HomeNavKey, SettingsNavKey], // <--- Define branch key order
)
class MainShellPage extends StatelessWidget {
  final TpStatefulNavigationShell navigationShell;
  const MainShellPage({required this.navigationShell, super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: navigationShell,
      bottomNavigationBar: BottomNavigationBar(
        currentIndex: navigationShell.currentIndex,
        onTap: (index) => navigationShell.tp(index),
        items: [/* ... */],
      ),
    );
  }
}

3. Define Routes & Link to Parent

Just annotate your pages.

• To nest a page, simply set parentNavigatorKey to the Shell's key.
• No nesting? Omit the key.

// Standard Route
@TpRoute(path: '/login')
class LoginPage extends StatelessWidget { ... }

// Nested Route (Child of MainShellPage)
@TpRoute(
  path: '/home',
  isInitial: true,
  parentNavigatorKey: HomeNavKey, // <--- Linked to MainShell's branch 0 automatically!
)
class HomePage extends StatelessWidget { ... }

// Another Nested Route
@TpRoute(
  path: '/settings',
  parentNavigatorKey: SettingsNavKey, // <--- Linked to MainShell's branch 1
)
class SettingsPage extends StatelessWidget { ... }

4. Initialization

Pass the generated tpRoutes to TpRouter.

void main() {
  final router = TpRouter(
    routes: tpRoutes, // Generated by build_runner
  );

  runApp(MaterialApp.router(
    routerConfig: router.routerConfig,
  ));
}

---

🧭 Navigation

Type-Safe Navigation

The generator creates a Route class for every annotated widget.

// Open a page
UserRoute(id: 123).tp();

// Await result
final result = await SelectProfileRoute().tp<String>();

// Replace current route
LoginRoute().tp(replacement: true);

⚙️ Advanced

Guards & Redirects

Protected routes? Just use redirect.

class AuthGuard extends TpRedirect<ProtectedRoute> {
  @override
  FutureOr<TpRouteData?> handle(BuildContext context, ProtectedRoute route) {
    if (!isLoggedIn) return const LoginRoute();
    return null; // Proceed
  }
}

@TpRoute(path: '/protected', redirect: AuthGuard)
class ProtectedPage extends StatelessWidget { ... }

Route Lifecycle

Intercept back button presses (e.g., unsaved changes).

class UnsavedChangesGuard extends TpOnExit<EditorRoute> {
  @override
  FutureOr<bool> onExit(BuildContext context, EditorRoute route) async {
    return await showDialog(...) ?? false;
  }
}

---

📝 Configuration

Customize output in build.yaml:

targets:
  $default:
    builders:
      tp_router_generator:
        options:
          output: lib/routes/route.gr.dart # Custom output path