{"id":51094718,"url":"https://github.com/vicajilau/genui","last_synced_at":"2026-06-24T05:03:42.880Z","repository":{"id":362087558,"uuid":"1256905021","full_name":"vicajilau/genui","owner":"vicajilau","description":"Zero-boilerplate code generation for the official flutter/genui package. Use @generativeUI to automatically extract JSON schemas and build CatalogItems at compile-time.","archived":false,"fork":false,"pushed_at":"2026-06-15T11:56:51.000Z","size":456,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T12:23:46.864Z","etag":null,"topics":["dart","flutter","generative-ui","genkit","genui"],"latest_commit_sha":null,"homepage":"https://vicajilau.github.io/genui/","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/vicajilau.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T07:27:44.000Z","updated_at":"2026-06-15T11:56:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vicajilau/genui","commit_stats":null,"previous_names":["vicajilau/genui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vicajilau/genui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicajilau%2Fgenui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicajilau%2Fgenui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicajilau%2Fgenui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicajilau%2Fgenui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vicajilau","download_url":"https://codeload.github.com/vicajilau/genui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicajilau%2Fgenui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34717772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["dart","flutter","generative-ui","genkit","genui"],"created_at":"2026-06-24T05:03:40.638Z","updated_at":"2026-06-24T05:03:42.868Z","avatar_url":"https://github.com/vicajilau.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GenUI: Code Generation for Flutter Generative UI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/logo.png\" alt=\"GenUI Logo\" width=\"160\"\u003e\u003cbr\u003e\u003cbr\u003e\n  \u003cimg src=\"https://github.com/vicajilau/genui/actions/workflows/ci.yml/badge.svg\" alt=\"CI Status\"\u003e\n  \u003cimg src=\"https://github.com/vicajilau/genui/actions/workflows/deploy_web.yml/badge.svg\" alt=\"Web CD Status\"\u003e\n\u003c/p\u003e\n\nThe developer experience (DX) companion for the official Google **Generative UI (GenUI)** ecosystem in Flutter.\n\nGenUI code generation automatically extracts data schemas and generates type-safe builders for your widgets at compile time. Instead of manually writing JSON schemas and writing repetitive catalog adapters, you can focus on building standard Flutter widgets.\n\n---\n\n## 🚀 Key Features\n\n* **Zero-Boilerplate Catalogs:** Simply decorate your Flutter widget with `@generativeUI`. The build system automatically handles schema mapping and widget instantiation.\n* **Compile-Time Introspection:** Uses Dart's AST (Abstract Syntax Tree) and `build_runner` to extract property constraints, avoiding runtime reflection overhead.\n* **Two-Phase Code Generation:** Automatically generates highly optimized local component schemas (`CatalogItem`s) AND assembles a central `genui_registry.g.dart` catalog index. No manual wiring required.\n* **Automatic Event Mapping:** Event callback properties (like `VoidCallback`) are automatically mapped to dispatch A2UI events (`dispatchEvent(UserActionEvent)`), sending widget states back to the LLM.\n* **Seamless Integration:** Built directly on top of the official `package:genui` and `package:json_schema_builder`.\n\n---\n\n## ✨ The Developer Experience (DX)\n\n1. **Zero Boilerplate:** Decorate your Flutter widget with `@generativeUI`.\n2. **Auto-Discovery:** You don't need to manually register your widgets into a massive list. The `genui_builder` crawls your project and creates a single `globalGenUICatalog` containing everything.\n3. **Fully Type-Safe:** Automatically casts `itemContext.data` values to your widget constructor fields, preventing type mismatches at runtime.\n\n---\n\n## 📁 Workspace Structure\n\nThis monorepo utilizes Dart Pub Workspaces and Melos to ensure clean dependency graphs.\n\n| Package | Description |\n| --- | --- |\n| [`genui_annotations`](./packages/genui_annotations) | Lightweight package containing the `@generativeUI` and `@GenerativeUI` annotations. |\n| [`genui_builder`](./packages/genui_builder) | The AST code generator using `build_runner` and `analyzer` to extract component schemas and build the global catalog index at compile time. |\n| [`example`](./example) | The playground Flutter app demonstrating the integration with Google's official `package:genui` Surface and SurfaceController. |\n\n---\n\n## 🛠️ Getting Started\n\n### Prerequisites\n\nEnsure you have **Dart SDK ^3.12.0** or Flutter SDK installed. You also need Melos activated globally.\n\n```bash\n# Activate Melos globally\ndart pub global activate melos\n```\n\n### Setup the Workspace\n\nClone the repository and resolve dependencies:\n\n```bash\ngit clone https://github.com/vicajilau/genui.git\ncd genui\n\n# Link dependencies natively across the workspace\nflutter pub get\n```\n\n### Code Generation\n\nTo generate your UI schemas and the global registry, run:\n\n```bash\n# Triggers code generation across all workspace packages\nmelos run build_runner\n```\n\n---\n\n## 📖 Usage Example\n\n### 1. Annotate your Widgets\n\nImport the annotations package, decorate your widget, and include the `.genui.g.dart` part directive.\n\n```dart\nimport 'package:flutter/material.dart';\nimport 'package:genui/genui.dart';\nimport 'package:genui_annotations/genui_annotations.dart';\nimport 'package:json_schema_builder/json_schema_builder.dart';\n\npart 'user_card.genui.g.dart';\n\n@generativeUI\nclass UserCard extends StatelessWidget {\n  final String username;\n  final String role;\n\n  const UserCard({\n    super.key,\n    required this.username,\n    required this.role,\n  });\n\n  @override\n  Widget build(BuildContext context) {\n    return Card(\n      child: ListTile(\n        title: Text(username),\n        subtitle: Text(role),\n      ),\n    );\n  }\n}\n```\n\n### 2. Consume the Global Catalog\n\nRun the code generator. GenUI will automatically compile your widget into a `CatalogItem` and export it to a global `Catalog` in `lib/genui_registry.g.dart`.\n\n```dart\nimport 'package:flutter/material.dart';\nimport 'package:genui/genui.dart';\n\n// Auto-generated by GenUI Builder\nimport 'genui_registry.g.dart';\n\nvoid main() {\n  // Inject the global catalog into the official SurfaceController\n  // Note: globalGenUICatalog automatically includes Google's official layout elements (Row, Column, Text, etc.) alongside your custom widgets!\n  final controller = SurfaceController(catalogs: [globalGenUICatalog]);\n\n  runApp(MainApp(controller: controller));\n}\n\nclass MainApp extends StatelessWidget {\n  final SurfaceController controller;\n  const MainApp({super.key, required this.controller});\n\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      home: Scaffold(\n        body: Center(\n          // Render dynamic surfaces automatically using your catalog!\n          child: Surface(\n            surfaceContext: controller.contextFor('demo_surface'),\n          ),\n        ),\n      ),\n    );\n  }\n}\n```\n\n### 3. Handle Events Type-Safely\n\nIf your widget defines interactive callbacks (like `VoidCallback onToggle`), you can parse and process them cleanly using `GenUiEvent` and auto-generated event constants:\n\n```dart\nimport 'package:genui_annotations/genui_annotations.dart';\n// Import the generated events:\nimport 'widgets/user_card.genui.g.dart';\n\nvoid handleWidgetEvent(String eventJson) {\n  final event = GenUiEvent.parse(eventJson);\n  if (event == null) return;\n\n  if (event.name == UserCardEvents.onToggle) {\n    print('UserCard clicked for component ID: ${event.sourceComponentId}');\n    print('Widget properties context: ${event.context}');\n  }\n}\n```\n\n*Note: For callbacks that take arguments (e.g. `ValueChanged\u003cbool\u003e onChanged`), parameter names and values are automatically appended to the event's `context` map (e.g. `event.context['value']`).*\n\n### 4. Decoupled AI Schema Sharing (e.g. Google Genkit)\n\nGenUI supports exporting your UI component schemas in a framework-agnostic way. This is ideal if you are orchestrating your AI models in a separate Node.js, Go, or Python backend (like Google Genkit).\n\n#### In-Memory Usage (Client-Side LLM)\nIf your AI runs locally on the device or if you have a Dart backend, you can fetch pre-formatted schemas directly from `genui_registry.g.dart`:\n\n```dart\n// 1. Raw Dart Map of JSON Schemas:\nMap\u003cString, Map\u003cString, dynamic\u003e\u003e schemas = globalGenUISchemas;\n\n// 2. Pre-formatted Markdown list ready for LLM System Instructions:\nString systemInstruction = '''\nYou are a GenUI assistant. You must respond using components defined here:\n$globalGenUISchemasPromptDescription\n''';\n```\n\n#### Static File Export (Backend Genkit/TypeScript)\nTo use your schemas in a separate backend repository (e.g., Node.js with Genkit), you can export the schemas to a static JSON file. \n\nBecause the generated registry transitively imports `package:flutter` (which has native graphic/engine bindings), running a standalone Dart script via `dart run` in the console will fail. Instead, we run a headless script using the `flutter test` runner, which resolves all Flutter engine bindings correctly.\n\nTo set this up in your own Flutter project:\n\n1. **Create the export script** as a test file (e.g., `test/genui_schemas_export_test.dart`):\n\n```dart\nimport 'dart:convert';\nimport 'dart:io';\nimport 'package:flutter_test/flutter_test.dart';\nimport 'package:your_app_name/genui_registry.g.dart'; // Import your generated registry\n\nvoid main() {\n  test('Export GenUI schemas to JSON', () {\n    final schemas = globalGenUISchemas;\n    final jsonString = const JsonEncoder.withIndent('  ').convert(schemas);\n    \n    // Auto-detect the project root and write to build/genui_schemas.json\n    final envPath = Platform.environment['GENUI_EXPORT_PATH'];\n    final file = envPath != null \u0026\u0026 envPath.isNotEmpty\n        ? File(envPath)\n        : File('build/genui_schemas.json');\n        \n    file.parent.createSync(recursive: true);\n    file.writeAsStringSync(jsonString);\n    print('✓ Schemas exported to: ${file.absolute.path}');\n  });\n}\n```\n\n2. **Trigger the export automatically** by appending it to your build command in your `pubspec.yaml` scripts or Melos tasks:\n\n```bash\n# Run build_runner, then run the test script to write the JSON schema contract\ndart run build_runner build \u0026\u0026 flutter test test/genui_schemas_export_test.dart\n```\n\nBy default, this will write the schema to `build/genui_schemas.json` relative to your project's root.\n\nIf you want to copy the file directly to a custom directory (e.g., to a sibling folder containing your Node.js Genkit backend), you can use the `GENUI_EXPORT_PATH` environment variable:\n\n```bash\nGENUI_EXPORT_PATH=../my-genkit-backend/src/genui_schemas.json flutter test test/genui_schemas_export_test.dart\n```\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicajilau%2Fgenui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicajilau%2Fgenui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicajilau%2Fgenui/lists"}