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. 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 GROQ queries.
• ⚡ Real-time updates via Server-Sent Events (SSE) with exponential backoff.
• 💾 Offline-first local caching via Hive for last-known-good config.
• 🔌 Extensible — register custom components and action handlers.
• 🛠 CLI code generator — scaffold Flutter widgets + Sanity schemas in one command.
• 🧩 State management agnostic — works with Riverpod, Bloc, Provider, or anything.

Installation #

Add to your pubspec.yaml:

dependencies:
  sdui_flutter_sanity: ^0.3.0

Quick Start #

1. Initialize the Engine #

In your main.dart, initialize the engine before runApp. Register any custom components and action handlers here.

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

// Import generated components and action handlers
import 'sdui_components/product_card_component.dart';
import 'sdui_actions/add_to_cart_action_handler.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await SduiEngine.initialize(
    config: const SduiConfig(
      projectId: 'your_sanity_project_id',
      dataset: 'production',
      // token: 'YOUR_READ_TOKEN', // only needed for private datasets
    ),
    components: [
      ProductCardComponent(),   // <-- Generated by CLI or hand-written
    ],
    actionHandlers: [
      AddToCartActionHandler(), // <-- Generated by CLI or hand-written
    ],
  );

  runApp(const MyApp());
}

2. Render a Screen #

Drop SduiView anywhere in your widget tree. It fetches the Sanity document for the given slug, caches it locally, and subscribes to live updates automatically.

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Home')),
        body: SduiView(
          slug: 'home',          // Matches a Page Config document slug in Sanity
          scrollable: true,      // Wraps in SingleChildScrollView (default: true)
          padding: EdgeInsets.all(16),
          loadingWidget: const Center(child: CircularProgressIndicator()),
          errorBuilder: (ctx, err, stack) => Center(child: Text('$err')),
        ),
      ),
    );
  }
}

CLI Code Generator #

The fastest way to add custom components or actions. Run from your project root:

dart run sdui_flutter_sanity:generate

The interactive CLI will ask a few questions and generate everything automatically.

=== SDUI Code Generator ===
Commands:
  c / component  — scaffold a Flutter component + Sanity schema
  a / action     — scaffold a Flutter action handler
  s / seed       — generate a sample .ndjson to seed a fresh Sanity project

Generating a Component #

=== SDUI Code Generator ===
Generate a Component (c) or Action (a)? [c]: c
Component name (e.g. product_card): product_card
Fields (comma separated name:type, e.g. title:string, price:number): title:string, price:number, imageUrl:image, inStock:boolean
Has children? (y/n) [n]: n
Flutter output directory [lib/sdui_components]:
Sanity schema directory [sanity_studio/schemas]:

✅ Generated Dart Component: lib/sdui_components/product_card_component.dart
✅ Generated Sanity Schema:  sanity_studio/schemas/components/productCardComponent.ts
✅ Updated uiElements.ts
✅ Updated index.ts

🎉 Done! Don't forget to register your new ProductCardComponent in SduiEngine.initialize()

Supported field types:

The generator auto-patches uiElements.ts and index.ts so you never have to touch those files manually.

What gets generated #

lib/sdui_components/product_card_component.dart — A fully typed Flutter component stub:

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

class ProductCardComponent extends SduiComponent {
  @override
  String get type => 'productCard'; // Matches Sanity schema initialValue

  @override
  Widget build(BuildContext context, UiNode node, Widget Function(UiNode) buildChild) {
    final title = node.props['title'] as String? ?? '';
    final price = (node.props['price'] as num?)?.toDouble() ?? 0.0;
    final imageUrl = node.props['imageUrl'] as String? ?? '';
    final inStock = node.props['inStock'] as bool? ?? false;

    // TODO: Implement your custom widget using the extracted properties.
    return const Placeholder();
  }
}

sanity_studio/schemas/components/productCardComponent.ts — The matching Sanity schema:

import {defineField, defineType} from 'sanity'

export default defineType({
  name: 'productCardComponent',
  title: 'Product Card',
  type: 'object',
  fields: [
    defineField({ name: 'type', type: 'string', hidden: true, initialValue: 'productCard' }),
    defineField({
      name: 'props',
      title: 'Properties',
      type: 'object',
      fields: [
        defineField({ name: 'title',    title: 'Title',    type: 'string' }),
        defineField({ name: 'price',    title: 'Price',    type: 'number' }),
        defineField({ name: 'imageUrl', title: 'Image Url', type: 'image' }),
        defineField({ name: 'inStock',  title: 'In Stock', type: 'boolean' }),
      ],
    }),
  ],
  preview: {
    select: {subtitle: 'props.title'},
    prepare(selection) {
      return {title: 'Product Card', subtitle: selection.subtitle}
    },
  },
})

Generating an Action Handler #

Generate a Component (c) or Action (a)? [c]: a
Action name (e.g. add_to_cart): add_to_cart
Flutter output directory [lib/sdui_actions]:

✅ Generated Dart Action Handler: lib/sdui_actions/add_to_cart_action_handler.dart

🎉 Done! Don't forget to register your new AddToCartActionHandler in SduiEngine.initialize()

lib/sdui_actions/add_to_cart_action_handler.dart:

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

class AddToCartActionHandler implements SduiActionHandler {
  @override
  bool canHandle(SduiAction action) => action.type == 'add_to_cart';

  @override
  void handle(BuildContext context, SduiAction action) {
    final payload = action.payload; // e.g. a product ID
    final params  = action.params;  // optional extra fields from CMS

    // TODO: Implement your custom action logic.
    // Works with any state management: Riverpod, Bloc, Provider, etc.
    debugPrint('AddToCartActionHandler: Handled action with payload $payload');
  }
}

Writing Custom Components Manually #

If you prefer not to use the CLI, you can implement SduiComponent directly:

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

class PromoBannerComponent extends SduiComponent {
  @override
  String get type => 'promoBanner'; // Must match the Sanity schema 'initialValue'

  @override
  Widget build(BuildContext context, UiNode node, Widget Function(UiNode) buildChild) {
    final headline = node.props['headline'] as String? ?? '';
    final subtitle = node.props['subtitle'] as String? ?? '';
    final bgColor  = node.props['bgColor'] as String? ?? '#6200EA';

    // Extract an optional CMS-defined action (e.g. navigate to a promo page)
    final action = SduiAction.tryParse(node.props['action']);

    return GestureDetector(
      onTap: () {
        if (action != null) {
          // Dispatch to any registered SduiActionHandler
          SduiEngine.handleAction(context, action);
        }
      },
      child: Container(
        padding: const EdgeInsets.all(20),
        color: Color(int.parse(bgColor.replaceFirst('#', '0xFF'))),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(headline, style: Theme.of(context).textTheme.headlineSmall),
            Text(subtitle,  style: Theme.of(context).textTheme.bodyMedium),
            // Recursively render any CMS children embedded in this component
            ...node.children.map(buildChild),
          ],
        ),
      ),
    );
  }
}

Writing Custom Action Handlers Manually #

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

class AddToCartActionHandler implements SduiActionHandler {
  @override
  // The `type` must match the prefix of the CMS action string, e.g. "cart_add:product-123"
  bool canHandle(SduiAction action) => action.type == 'cart_add';

  @override
  void handle(BuildContext context, SduiAction action) {
    final productId = action.payload; // e.g. "product-123"
    final quantity  = action.params['qty'] as int? ?? 1;

    // Use any state management — the package doesn't care!
    // context.read<CartNotifier>().add(productId, quantity);

    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('Added $productId (qty: $quantity) to cart!')),
    );
  }
}

CMS Action String formats accepted:

• "cart_add:product-123" — legacy colon-separated string
• {"type": "cart_add", "payload": "product-123", "params": {"qty": 2}} — structured Map

Sanity Studio Setup #

1. Create a Studio project #

npm create sanity@latest

2. Copy the bundled schemas #

Copy the entire sanity_studio/schemas/ folder from this repository into your Sanity project's schemaTypes/ or schemas/ folder. This gives you:

• pageConfig.ts — Schema for a single app screen.
• components/uiElements.ts — Array schema listing all available UI component types.
• components/*.ts — Individual schemas for text, image, button, column, row, card, spacer.

3. Seed Sample Content (Recommended for new projects) #

A fresh Sanity project has no documents, so your Flutter app will show a loading spinner with nothing to render. The CLI can generate a ready-to-import .ndjson seed file that pre-populates two sample pages showcasing every built-in component:

dart run sdui_flutter_sanity:generate
# Choose: s (seed)
# Output path: sdui_seed.ndjson

Then import it into your Sanity dataset:

cd your_sanity_studio_dir
sanity dataset import /path/to/sdui_seed.ndjson production --replace

This creates two published pageConfig documents:

Your Flutter app will immediately render them via SduiView(slug: 'home') — no app changes needed.

Tip: The seed documents are real Sanity documents. Open Sanity Studio after importing to see them and edit freely.

4. Export the schemas #

Ensure your schemaTypes/index.ts exports all schemas:

import pageConfig from './pageConfig'
import textComponent from './components/textComponent'
import imageComponent from './components/imageComponent'
import buttonComponent from './components/buttonComponent'
import spacerComponent from './components/spacerComponent'
import columnComponent from './components/columnComponent'
import rowComponent from './components/rowComponent'
import cardComponent from './components/cardComponent'
import uiElements from './components/uiElements'

export const schemaTypes = [
  pageConfig,
  textComponent,
  imageComponent,
  buttonComponent,
  spacerComponent,
  columnComponent,
  rowComponent,
  cardComponent,
  uiElements,
]

Custom components added via the CLI are auto-imported here.

4. Run the Studio and create content #

npm run dev

1. Open http://localhost:3333.
2. Create a new Page Config document.
3. Set the Slug to home (or any screen identifier your Flutter app uses).
4. Build the Layout by adding components from the CMS.
5. Click Publish — the Flutter app will immediately render the update via SSE.

SduiConfig Reference #

SduiConfig(
  projectId:        'abc123',       // Required. Your Sanity project ID.
  dataset:          'production',   // Optional. Default: 'production'.
  apiVersion:       'v2024-01-01',  // Optional. Sanity API version.
  token:            'sk...',        // Optional. Required for private datasets.
  enableCache:      true,           // Optional. Hive disk cache. Default: true.
  supportedVersion: 1,              // Optional. Schema version guard. Default: 1.
)

SduiView Reference #

SduiView(
  slug:          'home',           // Required. Sanity Page Config slug.
  scrollable:    true,             // Wraps in SingleChildScrollView. Default: true.
  padding:       EdgeInsets.all(16), // Padding around the rendered tree. Default: 16.
  loadingWidget: CircularProgressIndicator(), // Shown while fetching. Default: spinner.
  errorBuilder: (ctx, err, stack) => Text('$err'), // Custom error UI.
)

Core Use Cases #

1. E-Commerce & Promotional Campaigns #

Marketing teams use Sanity Studio to update banners, hero layouts, and product carousels — no developer involvement, no app store review. Changes arrive on-device in milliseconds via SSE.

2. A/B Testing & Personalization #

Pass different slug values to SduiView based on user segments (premium vs free, region, etc.) to serve entirely different UI trees from the same Flutter code.

3. Feature Flags & Phased Rollouts #

Wrap new features in a custom SDUI component. Add or remove it from the Sanity layout to toggle the feature for 100% of live users instantly — no code change, no deployment.

State Management Agnostic #

SDUI Flutter Sanity does not force any state management library. Custom components return standard Flutter widgets, so you can use:

// Riverpod
class MyComponent extends SduiComponent {
  @override Widget build(ctx, node, buildChild) =>
    Consumer(builder: (ctx, ref, _) {
      final cart = ref.watch(cartProvider);
      return Text('${cart.count} items');
    });
}

// Bloc
class MyComponent extends SduiComponent {
  @override Widget build(ctx, node, buildChild) =>
    BlocBuilder<CartBloc, CartState>(
      builder: (ctx, state) => Text('${state.count} items'),
    );
}