sdui_flutter_sanity 0.1.0

A Server-Driven UI Flutter package powered by Sanity.io headless CMS with realtime config updates.

SDUI Flutter Sanity

A Server-Driven UI (SDUI) Flutter package powered by Sanity.io headless CMS with realtime config updates.

Sanity.io stores the component tree for each screen as structured content, and the Flutter app renders it live — including picking up edits published in Sanity Studio in realtime, with no app rebuild required.

Features

• Dynamic widget rendering powered by Sanity.io.
• Real-time updates via Server-Sent Events (SSE).
• Local caching (Hive) for offline access.
• Easy to extend with custom components and actions.

Installation

Add it to your pubspec.yaml:

dependencies:
  sdui_flutter_sanity: ^0.1.0

Setup

1. Configure the SduiEngine before runApp. You can inject credentials via environment variables for security.

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:sdui_flutter_sanity/sdui_flutter_sanity.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await SduiEngine.initialize(
    config: const SduiConfig(
      projectId: 'your_sanity_project_id',
      dataset: 'production',
      token: 'your_optional_read_token',
    ),
  );

  runApp(const ProviderScope(child: MyApp()));
}

2. Render dynamic content in your app:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('SDUI')),
        body: const SduiView(slug: 'home'),
      ),
    );
  }
}

Sanity Studio Setup

The package repository contains a sanity_studio and sduiflutter directory acting as a reference for setting up your Sanity schemas.

1. Ensure your Sanity schema defines a pageConfig type with a slug and a layout (array of components).
2. Set up component builders in Flutter that match the _type property from Sanity nodes.

See the example/ directory for a fully functioning sample app.

Extensibility & Future Use Cases

This package is built to handle the infrastructure of Server-Driven UI (networking, caching, parsing, rendering), but it does not map every Flutter widget out of the box.

Instead, it provides powerful extension points to support any complex UI or business logic you might need in the future:

Custom Components

You can render any Flutter widget (even highly complex forms, charts, or animations) by registering a custom SduiComponent.

class MyCustomComponent extends SduiComponent {
  @override
  String get type => 'my_custom_type'; // Matches '_type' from Sanity

  @override
  Widget build(BuildContext context, UiNode node, Widget Function(UiNode) buildChild) {
    // Read props and return any Flutter widget
    return MyComplexWidget(title: node.props['title']);
  }
}

State Management & Analytics

If your SDUI requires complex data-binding (e.g. form fields, validating inputs, tracking analytics impressions), you handle this inside your custom components. Your components can freely use Riverpod, Provider, or Flutter's VisibilityDetector because they are just standard Flutter Widgets once parsed.

Custom Actions

You can trigger complex logic (like "Add to Cart" or "Log out") from the CMS by registering custom SduiActionHandlers.

// Register before runApp()
SduiEngine.initialize(
  config: const SduiConfig(projectId: 'xyz'),
  components: [MyCustomComponent()],
  actionHandlers: [MyCartActionHandler()],
);