QuicUI - Server-Driven UI Framework for Flutter #

QuicUI is a powerful Server-Driven UI (SDUI) framework for Flutter that enables you to build, update, and deliver dynamic user interfaces without redeploying your app. Define your UI as JSON and render it natively at runtime.

🚀 Features #

• Instant Updates: Ship UI changes without App Store/Play Store approval
• JSON-Driven: Define widgets in JSON, render natively in Flutter
• Cloud-Powered by Supabase: Store UI definitions and user data in PostgreSQL
• Real-Time Sync: Live UI updates from Supabase with minimal latency
• Dynamic Navigation: Control routes from the backend
• Form Management: Server-side forms with built-in validation
• Dynamic Theming: Update branding and styles in real-time
• Offline-First: Lightning-fast local database (ObjectBox) for offline apps
• Extensible: Custom widgets, actions, and native integrations
• Cross-Platform: iOS, Android, Web, Windows, macOS, Linux

📦 What's New #

v1.0.1 (October 30, 2025) - Production Release ✨

• ✅ Cloud integration via Supabase only
• ✅ 70+ pre-built widgets fully functional
• ✅ BLoC state management complete
• ✅ Offline-first architecture with sync
• ✅ Real-time UI sync with Supabase
• ✅ ObjectBox local persistence
• ✅ Comprehensive Supabase integration guide
• ✅ 5 complete example applications
• ✅ 11,000+ lines of documentation
• ✅ 228/228 tests passing (100%)
• ✅ Published to pub.dev

🎯 Quick Start #

Installation #

flutter pub add quicui

Basic Usage #

import 'package:quicui/quicui.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize with Supabase for cloud UI configuration
  await QuicUIService().initialize(
    supabaseUrl: 'https://your-project.supabase.co',
    supabaseAnonKey: 'your-anon-key',
  );
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: QuicUIScreen(
        jsonData: '''
        {
          "type": "container",
          "properties": {"padding": "16"},
          "child": {
            "type": "text",
            "properties": {"text": "Hello from Supabase!"}
          }
        }
        ''',
      ),
    );
  }
}

📚 Documentation #

Getting Started #

• Quick Start Guide - 5-minute setup guide with examples
• Implementation Plan - Detailed 7-week roadmap and architecture

Technical Documentation #

• Architecture Guide - System design and component structure
• Database Strategy - ObjectBox integration and local storage
• Development Roadmap - Phase-by-phase breakdown with milestones

Cloud Integration #

• Supabase Integration Guide - Complete guide for cloud data, real-time sync, and authentication
• Supabase Examples - Ready-to-use code examples (Todo App, Product Catalog, User Profiles)

Example Applications #

See /example folder for:

• Counter App - Simple state management
• Form App - Input handling and validation
• Todo App - CRUD operations
• Offline Sync App - Offline-first synchronization
• Dashboard App - Complex layouts and theming

🏗️ Architecture Overview #

Layered Architecture #

┌─────────────────────────────┐
│   Presentation Layer (UI)   │
│  Widgets, Factory, Rendering│
└─────────────────────────────┘
              ↓
┌─────────────────────────────┐
│ Business Logic Layer        │
│ State, Forms, Actions       │
└─────────────────────────────┘
              ↓
┌─────────────────────────────┐
│   Data Layer                │
│ API, Database, Cache        │
└─────────────────────────────┘

Core Components #

🎨 Supported Widgets #

Layout Widgets #

• Container, Column, Row, Stack, Center
• Scaffold, AppBar, BottomNav, Drawer
• ListView, GridView, SingleChildScrollView

Input Widgets #

• TextField, Checkbox, Radio, DropDown
• Switch, DatePicker, FilePicker

Display Widgets #

• Text, Image, Icon, Badge, Chip
• Card, Dialog, SnackBar

Advanced Widgets #

• Conditional (if/else)
• Loop (dynamic lists)
• Form (with validation)
• Custom (extensible)

📝 JSON Schema Example #

Simple Screen #

{
  "type": "scaffold",
  "appBar": {
    "type": "appbar",
    "title": "Welcome"
  },
  "body": {
    "type": "column",
    "properties": {"padding": "16"},
    "children": [
      {
        "type": "text",
        "properties": {
          "text": "Hello QuicUI",
          "fontSize": 24,
          "fontWeight": "bold"
        }
      },
      {
        "type": "button",
        "properties": {"label": "Click Me"},
        "onPressed": {
          "type": "api",
          "method": "POST",
          "url": "/api/action",
          "onSuccess": {"type": "showSnackBar", "message": "Success!"}
        }
      }
    ]
  }
}

Form with Validation #

{
  "type": "form",
  "formId": "contact_form",
  "fields": [
    {
      "type": "textfield",
      "fieldName": "name",
      "label": "Full Name",
      "validators": [
        {"type": "required", "message": "Name is required"},
        {"type": "minLength", "value": 2}
      ]
    },
    {
      "type": "textfield",
      "fieldName": "email",
      "label": "Email",
      "validators": [
        {"type": "required"},
        {"type": "email"}
      ]
    }
  ],
  "submitAction": {
    "type": "api",
    "method": "POST",
    "url": "/api/contact",
    "body": {"name": "${name}", "email": "${email}"}
  }
}

💾 Local Storage (ObjectBox) #

QuicUI uses ObjectBox for blazingly fast local storage:

• ⚡ Sub-millisecond queries (0.2ms avg)
• 🔒 ACID transactions for data integrity
• 📦 50x faster than SQLite for typical operations
• 🔄 Built for sync scenarios
• 🔐 Optional encryption support

// Cache UI responses
await QuicUIManager.cache('home', jsonData);

// Retrieve from cache
final cached = await QuicUIManager.getCache('home');

// Offline support with automatic sync
await QuicUIManager.syncOfflineChanges();

🔧 State Management #

// Access global state
Consumer<QuicState>(
  builder: (context, state, _) {
    return Text(state.get('userName') ?? 'Guest');
  },
)

// Update state
Provider.of<QuicState>(context, listen: false)
  .set('userName', 'John Doe');

// Listen to events
state.on('userLoggedIn', (data) {
  print('User logged in: $data');
});

🎨 Dynamic Theming #

// Define theme as JSON
final theme = {
  "colors": {
    "primary": "#6366F1",
    "secondary": "#EC4899"
  },
  "typography": {
    "heading": {"fontSize": 24, "fontWeight": "bold"}
  }
};

// Apply dynamically at runtime
Provider.of<ThemeManager>(context, listen: false)
  .setTheme(jsonEncode(theme));

🧪 Testing #

QuicUI includes comprehensive testing utilities:

// Unit tests for JSON parsing
test('Parse simple widget', () {
  final json = '{"type":"text","properties":{"text":"Hello"}}';
  final widget = QuicWidget.fromJson(jsonDecode(json));
  expect(widget.type, equals('text'));
});

// Widget tests
testWidgets('Render QuicText', (tester) async {
  await tester.pumpWidget(
    MaterialApp(home: Scaffold(body: QuicText(text: 'Hello')))
  );
  expect(find.text('Hello'), findsOneWidget);
});

📊 Performance #

🚀 Development Roadmap #

Phase 1-2: Foundation & Widgets (Weeks 1-3) #

• Core models and JSON parser
• Widget factory and all core widgets
• Basic rendering engine

Phase 3-4: State & Forms (Weeks 3-5) #

• State management system
• Action execution engine
• Complete form system

Phase 5-7: Storage, Theming & Polish (Weeks 5-7) #

• ObjectBox integration
• Sync mechanism
• Dynamic theming system
• Testing & documentation

Target Release: End of Week 7 (v1.0 production-ready)

See ROADMAP.md for detailed timeline.

🔌 Extensibility #

Custom Widgets #

class CustomWidgetRegistry {
  static void register(String type, WidgetBuilder builder) {
    // Register custom widget
  }
}

Custom Actions #

class CustomActionHandler {
  static void register(String type, ActionHandler handler) {
    // Handle custom actions
  }
}

Custom Validators #

class ValidatorRegistry {
  static void register(String type, ValidatorFn validator) {
    // Custom validation logic
  }
}

🔒 Security #

• ✅ JSON schema validation prevents injection
• ✅ Encrypted local storage (optional)
• ✅ HTTPS-only API communication
• ✅ Request signing and verification
• ✅ Sandbox for custom code execution

📱 Platform Support #

📦 Dependencies #

Core Dependencies #

• flutter_bloc: ^9.0.0 - State management (BLoC pattern)
• equatable: ^2.0.5 - Value equality
• dio: ^5.7.0 - HTTP client
• objectbox: ^4.1.1 - Local database
• json_annotation: ^4.8.1 - JSON serialization

See pubspec.yaml for complete list.

📖 Examples #

Complete example applications are available in the /example folder:

• Basic text and button rendering
• Form with validation
• API integration
• List rendering
• Theme switching
• Offline support
• A/B testing

🤝 Contributing #

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

How to Contribute #

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

🐛 Issue Reporting #

Found a bug? Please report it on GitHub with:

• Minimal reproducible example
• Flutter/Dart version
• Platform details
• Relevant logs

📞 Support #

• 📚 Full Documentation - Complete guides and examples
• 🏗️ Architecture Guide - System design
• 📱 Supabase Integration - Cloud data sync
• ☕ Buy Me a Coffee - Support the development

📜 License #

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

🙏 Acknowledgments #

Inspired by:

• Stac - Server-Driven UI inspiration
• Flutter community and best practices
• Open-source SDUI pioneers

🚀 What's Next? #

1. Review the Implementation Plan
2. Read the Architecture Guide
3. Follow the Quick Start
4. Check the Development Roadmap

Made with ❤️ by the QuicUI team

⭐ If you find QuicUI useful, please give it a star on GitHub!