Purpose

flutter_declarative_mdx explores a simple idea:

Common application UI can be described declaratively and delivered from a server, while still rendering as fully native Flutter widgets.

The library provides a structured, extensible Markdown (MDX) approach to defining UI such as documents, forms, and workflows that can be rendered dynamically inside Flutter apps.

This project aims to make server-driven UI in Flutter:

Problem Statement

Modern mobile applications frequently need to ship UI and content changes without requiring a full app release.

Common approaches include:

Each has tradeoffs.

Hardcoded UI:

WebView/HTML rendering:

JSON-driven UI:

Low-code platforms:

There is space for a simpler, developer-centric approach.

Core Idea

Use Markdown as the baseline language, extended with structured components, to define UI declaratively.

Markdown provides:

Extensible components provide:

Flutter renders the result natively.

This creates a clear separation:

Server defines structure and content Client renders and executes behaviour

Design Goals

1. Native-first rendering

All output should render as native Flutter widgets.

This is not an HTML renderer or WebView abstraction. The goal is native performance, accessibility, and theming.

2. Declarative over imperative

Documents describe what should be rendered, not how to render it.

Rendering logic lives in Flutter components. Documents describe structure, content, and intent.

3. Extensibility as a first-class concept

Different apps require different components.

The system must allow:

Without modifying core library code.

4. Composability

Documents should be:

Components should compose cleanly without hidden coupling.

5. Server-driven, not server-controlled

The server defines documents and flows. The client retains control over:

This avoids turning the client into a thin runtime shell.

6. Readability and debuggability

Documents should remain human-readable.

A developer should be able to:

Markdown provides a strong foundation for this.

Non-Goals

To maintain clarity and focus, this project intentionally avoids becoming:

A full low-code/no-code platform

The library provides primitives, not a visual builder or hosted platform.

A layout engine replacement

Flutter remains responsible for layout and rendering. MDX describes structure and components, not pixel-perfect layout systems.

A web content renderer

This is not intended to render arbitrary HTML or replicate browser behaviour.

A CMS

Content management and authoring tools are out of scope for the core library.

A complete workflow engine

The library supports workflows and step-based UI, but does not aim to replace backend orchestration systems.

Tradeoffs

Flexibility vs control

Server-driven UI increases flexibility but requires strong component contracts and versioning discipline.

Simplicity vs completeness

The project prioritises a small, understandable core over covering every UI scenario.

Markdown vs strict schema

Markdown improves readability and authoring experience, but requires careful extension design to avoid ambiguity.

Long-Term Direction

This project may evolve toward:

The focus will remain on:

Intended Audience

This project is primarily for:

Status

The project is evolving. APIs and patterns may change as real-world usage informs design.

Feedback, discussion, and contributions are welcome from teams exploring similar approaches.