{"id":28773364,"url":"https://github.com/dev-cetera/df_router","last_synced_at":"2026-01-20T16:33:58.270Z","repository":{"id":295176944,"uuid":"989383839","full_name":"dev-cetera/df_router","owner":"dev-cetera","description":"Just another router, with a focus on ease of use and effective state management.","archived":false,"fork":false,"pushed_at":"2025-06-12T01:13:05.000Z","size":533,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-12T02:31:53.731Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dev-cetera.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-24T01:50:14.000Z","updated_at":"2025-06-12T01:13:09.000Z","dependencies_parsed_at":"2025-06-12T02:22:50.043Z","dependency_job_id":"f14b612d-f145-4f4b-9908-138fc87b1cc4","html_url":"https://github.com/dev-cetera/df_router","commit_stats":null,"previous_names":["robmllze/df_router","dev-cetera/df_router"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dev-cetera/df_router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-cetera%2Fdf_router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-cetera%2Fdf_router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-cetera%2Fdf_router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-cetera%2Fdf_router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dev-cetera","download_url":"https://codeload.github.com/dev-cetera/df_router/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dev-cetera%2Fdf_router/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260379105,"owners_count":23000029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-17T14:30:43.596Z","updated_at":"2026-01-11T13:34:51.259Z","avatar_url":"https://github.com/dev-cetera.png","language":"Dart","funding_links":["https://www.buymeacoffee.com/dev_cetera","https://github.com/sponsors/dev-cetera","https://www.patreon.com/t0mb3rr"],"categories":[],"sub_categories":[],"readme":"[![banner](https://github.com/dev-cetera/df_router/blob/v0.5.4/doc/assets/banner.png?raw=true)](https://github.com/dev-cetera)\n\n[![pub](https://img.shields.io/pub/v/df_router.svg)](https://pub.dev/packages/df_router)\n[![tag](https://img.shields.io/badge/Tag-v0.5.4-purple?logo=github)](https://github.com/dev-cetera/df_router/tree/v0.5.4)\n[![buymeacoffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/dev_cetera)\n[![sponsor](https://img.shields.io/badge/Sponsor-grey?logo=github-sponsors\u0026logoColor=pink)](https://github.com/sponsors/dev-cetera)\n[![patreon](https://img.shields.io/badge/Patreon-grey?logo=patreon)](https://www.patreon.com/t0mb3rr)\n[![discord](https://img.shields.io/badge/Discord-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/gEQ8y2nfyX)\n[![instagram](https://img.shields.io/badge/Instagram-E4405F?logo=instagram\u0026logoColor=white)](https://www.instagram.com/dev_cetera/)\n[![license](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/dev-cetera/df_router/main/LICENSE)\n\n---\n\n\u003c!-- BEGIN _README_CONTENT --\u003e\n\n## Summary\n\nA lightweight router designed for ease of use and efficient state management. Explore it in action with this live web app: https://dev-cetera.github.io/df_router/chat?chatId=123456.\n\n## Features\n\n- **Declarative Routing:** Define your routes and their corresponding widgets in a clean, list-based manner.\n- **Stateful Routes:** `RouteState` objects represent unique routes, including paths, query parameters, and strongly-typed `extra` data.\n- **Widget Caching \u0026 Preservation:** Control whether route widgets are preserved in memory (`shouldPreserve`) or pre-built (`shouldPrebuild`) for performance.\n- **Customizable Transitions:** Easily define custom page transitions called \"effects\" or use the provided `MaterialEffect` and `CupertinoEffect`.\n- **Persistent UI Wrapper:** Add common UI elements like headers, footers, or navigation bars that persist across route changes.\n- **Easy Navigation:** Navigate using `RouteState` objects or simple path strings.\n- **Typed `extra` Data:** Pass strongly-typed data between routes.\n\n## Usage\n\n### 1. Define Your RouteStates\n\nCreate classes that extend `RouteState` for each distinct route in your application. These classes encapsulate the path and can manage query parameters.\n\n```dart\nfinal class HomeRouteState extends RouteState {\n  HomeRouteState()\n    : super.parse(\n        '/home',\n        // Use QuickForwardtEffect() as the default transtion effect for this\n        // route. This can be overridden when pushing this route.\n        animationEffect: const QuickForwardEffect(),\n      );\n}\n\n// This route is only used in the RouteManager, so it does not need to\n// be pushed directly. It is a base route for the chat feature.\nfinal class BaseChatRouteState extends RouteState {\n  BaseChatRouteState({Map\u003cString, String\u003e? queryParameters})\n    : super.parse(\n        '/chat',\n        queryParameters: queryParameters,\n        // Use a different animation effect for this route.\n        animationEffect: const SlideDownEffect(),\n      );\n\n  BaseChatRouteState.from(RouteState other) : super(other.uri);\n}\n\nfinal class ChatRouteState extends BaseChatRouteState {\n  final String chatId;\n\n  ChatRouteState({required this.chatId}) : super(queryParameters: {'chatId': chatId});\n\n  ChatRouteState.from(super.other)\n    : chatId = other.uri.queryParameters['chatId'] ?? '',\n      super.from();\n}\n```\n\n### 2. Configure RouteStateManager\n\nIn your MaterialApp (or CupertinoApp), use the RouteStateManager widget to define your application's routing configuration.\n\n```dart\nclass MyApp extends StatelessWidget {\n  const MyApp({super.key});\n\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      //home: // Do not use \"home\", as it conflicts with RouteManager. Use\n      // \"builder\" instead.\n      builder: (context, child) {\n        return RouteManager(\n          fallbackRouteState: () =\u003e HomeRouteState(),\n          builders: [\n            RouteBuilder(\n              routeState: HomeRouteState(),\n              // Pre-build the HomeScreen even if the initial route is not\n              // HomeRouteState. This is useful for performance optimization.\n              shouldPrebuild: true,\n              // Preserve the HomeScreen widget to avoid rebuilding it.\n              shouldPreserve: true,\n              builder: (context, routeState) =\u003e HomeScreen(routeState: HomeRouteState()),\n            ),\n            RouteBuilder(\n              // Use the BaseChatRouteState instead of the ChatRouteState\n              // since it does not require a chatId to be pushed.\n              routeState: BaseChatRouteState(),\n              builder:\n                  (context, routeState) =\u003e ChatScreen(routeState: ChatRouteState.from(routeState)),\n            ),\n          ],\n        );\n      },\n    );\n  }\n}\n```\n\n### 3. Create Your Screen Widgets\n\nYour screen widgets should use the `RouteWidgetMixin` to easily access the current `RouteState`.\n\n```dart\nclass HomeScreen extends StatelessWidget with RouteWidgetMixin {\n  @override\n  final HomeRouteState? routeState;\n  const HomeScreen({super.key, this.routeState});\n\n  @override\n  Widget build(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: const Text('Home')),\n      backgroundColor: Colors.green,\n      body: Center(\n        child: ElevatedButton(\n          onPressed: () {\n            final controller = RouteController.of(context);\n            controller.push(\n              ChatRouteState(chatId: '123456'),\n              // Override the default animation effect for this push.\n              animationEffect: const CupertinoEffect(),\n            );\n          },\n          child: const Text('Go to Chat'),\n        ),\n      ),\n    );\n  }\n}\n\nclass ChatScreen extends StatelessWidget with RouteWidgetMixin {\n  @override\n  final ChatRouteState? routeState;\n\n  const ChatScreen({super.key, this.routeState});\n\n  @override\n  Widget build(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: Text('Chat - ${routeState?.chatId}')),\n      backgroundColor: Colors.blue,\n      body: Center(\n        child: Column(\n          mainAxisAlignment: MainAxisAlignment.center,\n          children: [\n            ElevatedButton(\n              onPressed: () {\n                final controller = RouteController.of(context);\n                controller.goBackward();\n              },\n              child: const Text('Go Back - Default Effect'),\n            ),\n            ElevatedButton(\n              onPressed: () {\n                final controller = RouteController.of(context);\n                controller.goBackward(animationEffect: const QuickBackEffect());\n              },\n              child: const Text('Go Back - Quick Back Effect'),\n            ),\n            ElevatedButton(\n              onPressed: () {\n                final controller = RouteController.of(context);\n                controller.push(HomeRouteState());\n              },\n              child: const Text('Go Home - Default Effect'),\n            ),\n            ElevatedButton(\n              onPressed: () {\n                final controller = RouteController.of(context);\n                controller.push(HomeRouteState().copyWith(animationEffect: const MaterialEffect()));\n              },\n              child: const Text('Go Home - Material Effect'),\n            ),\n            ElevatedButton(\n              onPressed: () {\n                final controller = RouteController.of(context);\n                controller.push(HomeRouteState(), animationEffect: const PageFlapDown());\n              },\n              child: const Text('Go Home - Page Flap Down Effect'),\n            ),\n          ],\n        ),\n      ),\n    );\n  }\n}\n```\n\n## 4. Navigation\n\nAccess the RouteStateController to navigate:\n\n```dart\nfinal controller = RouteStateController.of(context);\n\n// Push the home screen with a material effect.\ncontroller.push(HomeRouteState(), animationEffect: const CupertinoEffect());\ncontroller.push(HomeRouteState().copyWith(animationEffect: const MaterialEffect()));\n\n// Go back.\ncontroller.pushBack();\n\n// Remove a specific route to free up resources.\ncontroller.removeStatesFromCache([HomeRouteState()]);\n\n// Clear the entire widget cache.\ncontroller.clearCache([HomeRouteState()]);\n\n// Add a route to the cache without navigating. This will preload it.\ncontroller.addToCache([HomeRouteState()]);\n\n// Reset the cache to its initial state. This honours the shouldPrebuild property.\ncontroller.resetState();\n\n// Get the current state, e.g. HomeRouteState();\nfinal current = controller.current;\n\n// Get the requested state, which is what was typed in the URL bar, e.g. \"/home?query=123\" may return an instance of HomeRouteState(). This will return nul if the URL does not match any defined route.\nfinal requested = controller.requested;\n```\n\n\u003c!-- END _README_CONTENT --\u003e\n\n---\n\n🔍 For more information, refer to the [API reference](https://pub.dev/documentation/df_router/).\n\n---\n\n## 💬 Contributing and Discussions\n\nThis is an open-source project, and we warmly welcome contributions from everyone, regardless of experience level. Whether you're a seasoned developer or just starting out, contributing to this project is a fantastic way to learn, share your knowledge, and make a meaningful impact on the community.\n\n### ☝️ Ways you can contribute\n\n- **Find us on Discord:** Feel free to ask questions and engage with the community here: https://discord.gg/gEQ8y2nfyX.\n- **Share your ideas:** Every perspective matters, and your ideas can spark innovation.\n- **Help others:** Engage with other users by offering advice, solutions, or troubleshooting assistance.\n- **Report bugs:** Help us identify and fix issues to make the project more robust.\n- **Suggest improvements or new features:** Your ideas can help shape the future of the project.\n- **Help clarify documentation:** Good documentation is key to accessibility. You can make it easier for others to get started by improving or expanding our documentation.\n- **Write articles:** Share your knowledge by writing tutorials, guides, or blog posts about your experiences with the project. It's a great way to contribute and help others learn.\n\nNo matter how you choose to contribute, your involvement is greatly appreciated and valued!\n\n### ☕ We drink a lot of coffee...\n\nIf you're enjoying this package and find it valuable, consider showing your appreciation with a small donation. Every bit helps in supporting future development. You can donate here: https://www.buymeacoffee.com/dev_cetera\n\n\u003ca href=\"https://www.buymeacoffee.com/dev_cetera\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" height=\"40\"\u003e\u003c/a\u003e\n\n## LICENSE\n\nThis project is released under the [MIT License](https://raw.githubusercontent.com/dev-cetera/df_router/main/LICENSE). See [LICENSE](https://raw.githubusercontent.com/dev-cetera/df_router/main/LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdev-cetera%2Fdf_router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdev-cetera%2Fdf_router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdev-cetera%2Fdf_router/lists"}