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. Backend is fully optional - works standalone with local data, or integrates with any cloud backend via plugins.

🚀 Features #

• Instant Updates: Ship UI changes without App Store/Play Store approval
• JSON-Driven: Define widgets in JSON, render natively in Flutter
• Standalone Usage: Works with local JSON data - no backend required
• Backend Optional: Integrate with Supabase, Firebase, REST API, or custom backends
• Real-Time Sync: Live UI updates with minimal latency (when backend is available)
• Dynamic Navigation: Control routes from the backend or locally
• Form Management: Server-side or local 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 ✨

• ✅ Backend-agnostic plugin architecture
• ✅ 70+ pre-built widgets fully functional
• ✅ BLoC state management complete
• ✅ Offline-first architecture with sync
• ✅ Real-time UI sync support
• ✅ ObjectBox local persistence
• ✅ Comprehensive backend integration guides
• ✅ 5 complete example applications
• ✅ 11,000+ lines of documentation
• ✅ 267/267 tests passing (100%)
• ✅ Published to pub.dev

🎯 Quick Start #

Installation #

flutter pub add quicui

Minimal Setup (No Backend) #

import 'package:quicui/quicui.dart';

void main() {
  runApp(QuicUIApp(home: MyApp()));
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Render local JSON without any backend
    final jsonData = {
      'type': 'column',
      'properties': {'mainAxisAlignment': 'center'},
      'children': [
        {
          'type': 'text',
          'properties': {'text': 'Hello from Local JSON!', 'fontSize': 24}
        }
      ]
    };
    
    final screen = Screen.fromJson(jsonData);
    return UIRenderer.render(screen);
  }
}

With Cloud Backend (Optional) #

import 'package:quicui/quicui.dart';
import 'package:quicui_supabase/quicui_supabase.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize with backend (optional)
  final dataSource = SupabaseDataSource(
    'https://your-project.supabase.co',
    'your-anon-key',
  );
  await QuicUIService().initializeWithDataSource(dataSource);
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Now fetch dynamic UI from backend
    return MaterialApp(
      home: FutureBuilder(
        future: QuicUIService().fetchScreen('home_screen'),
        builder: (context, snapshot) {
          if (snapshot.hasData) {
            final screen = Screen.fromJson(snapshot.data);
            return UIRenderer.render(screen);
          }
          return const Scaffold(body: CircularProgressIndicator());
        },
      ),
    );
  }
}

📚 Documentation #

Getting Started #

• Quick Start Guide - 5-minute setup guide with plugin examples
• Plugin Architecture - Understanding the plugin system

Backend Integration #

• Backend Integration Guide - How to build custom DataSource implementations
• API Reference - Complete DataSource interface documentation
• Supabase Backend Package - Supabase integration with examples
• Firebase Integration - Firebase backend setup
• Custom Backend - Build your own DataSource

Examples & Patterns #

• Example Applications - REST API and custom backend examples
• Scaffold Counter App - Complete counter app with Scaffold widget
• Supabase Examples - See the Supabase package for Supabase-specific examples
• Testing Guide - Mock backends and unit testing
• Performance Guide - Caching, optimization, and best practices

Technical Documentation #

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

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!"}
        }
      }
    ]
  }
}

Counter App with Scaffold #

{
  "type": "scaffold",
  "appBar": {
    "type": "appBar",
    "title": "Counter App",
    "backgroundColor": "#1976D2"
  },
  "body": {
    "type": "center",
    "child": {
      "type": "column",
      "mainAxisAlignment": "center",
      "crossAxisAlignment": "center",
      "children": [
        {
          "type": "text",
          "properties": {
            "text": "You have pushed the button this many times:",
            "fontSize": 16
          }
        },
        {
          "type": "sizedBox",
          "properties": {"height": 16}
        },
        {
          "type": "container",
          "properties": {
            "padding": "24",
            "decoration": {
              "color": "#E3F2FD",
              "borderRadius": "12"
            }
          },
          "child": {
            "type": "text",
            "properties": {
              "text": "42",
              "fontSize": 72,
              "fontWeight": "bold",
              "color": "#1976D2"
            }
          }
        },
        {
          "type": "sizedBox",
          "properties": {"height": 32}
        },
        {
          "type": "row",
          "mainAxisAlignment": "center",
          "children": [
            {
              "type": "elevatedButton",
              "properties": {
                "label": "−",
                "backgroundColor": "#F44336"
              }
            },
            {
              "type": "sizedBox",
              "properties": {"width": 16}
            },
            {
              "type": "elevatedButton",
              "properties": {
                "label": "+",
                "backgroundColor": "#4CAF50"
              }
            }
          ]
        }
      ]
    }
  },
  "floatingActionButton": {
    "type": "floatingActionButton",
    "icon": "Icons.add",
    "tooltip": "Increment"
  }
}

See Scaffold Counter App Example for complete implementation with state management.

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

☕ Love QuicUI? #

If you find QuicUI helpful and want to support its development, consider buying me a coffee! Every cup fuels more features, faster updates, and better documentation.

☕ Buy Me a Coffee - Help keep QuicUI growing!

Your support helps us:

• 🚀 Build new features faster
• 📚 Create better documentation
• 🐛 Fix bugs quickly
• 💡 Implement community requests
• 🎯 Maintain long-term support

Every contribution is deeply appreciated! ❤️

📜 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!