Dioxus Architecture Overview

This directory contains comprehensive architecture documentation for the Dioxus framework, designed to help future Claude agents (and human contributors) understand the codebase deeply.

Document Index

Crate Dependency Overview

dioxus (umbrella crate)
├── dioxus-core (VirtualDOM, runtime, scheduler)
│   └── generational-box (Copy semantics for references)
├── dioxus-rsx (macro parsing)
│   └── dioxus-autofmt (code formatting)
├── dioxus-signals (reactive state)
│   ├── generational-box
│   └── dioxus-stores (nested reactivity)
├── dioxus-hooks (use_signal, use_effect, etc.)
├── dioxus-html (HTML elements, events)
├── dioxus-router (client-side routing)
│
├── Renderers:
│   ├── dioxus-web (WASM/browser)
│   ├── dioxus-desktop (wry/tao webview)
│   ├── dioxus-native (blitz/vello GPU)
│   ├── dioxus-liveview (WebSocket streaming)
│   └── dioxus-ssr (server-side rendering)
│
├── Fullstack:
│   ├── dioxus-fullstack (client/server coordination)
│   ├── dioxus-fullstack-core (transport, types)
│   ├── dioxus-fullstack-macro (#[server] macro)
│   └── dioxus-server (Axum integration)
│
├── CLI (dx command):
│   ├── dioxus-cli (main binary)
│   ├── dioxus-cli-config (Dioxus.toml parsing)
│   └── dioxus-cli-opt (optimization passes)
│
├── Hot Reload:
│   ├── subsecond (hot-patching runtime)
│   ├── dioxus-rsx-hotreload (template diffing)
│   └── dioxus-devtools (WebSocket communication)
│
├── Assets:
│   ├── manganis (asset!() macro)
│   ├── manganis-core (asset types)
│   ├── manganis-macro (proc-macro)
│   └── const-serialize (compile-time CBOR)
│
└── Code Splitting:
    ├── wasm-splitter (CLI tool)
    ├── wasm-split-macro (#[wasm_split])
    └── wasm-split-cli (binary processing)

Key Architectural Patterns

1. Copy Semantics for Reactive State

Dioxus uses generational-box to provide Copy semantics for references. This enables signals and other reactive primitives to be freely passed around without explicit cloning.

2. WriteMutations Trait

All renderers implement WriteMutations which defines how VirtualDOM changes translate to real DOM operations. This abstraction enables the same component code to run on web, desktop, mobile, and server.

3. Template-Based Rendering

RSX macros generate static Template definitions at compile time. Only dynamic parts are diffed at runtime, making updates extremely efficient.

4. Hot-Reload Without Full Rebuild

Two complementary systems:

• RSX Hot-Reload: Changes to template literals are diffed and sent via WebSocket
• Subsecond Hot-Patching: Full Rust function replacement via jump table indirection

5. Compile-Time Asset Processing

The asset!() macro embeds asset metadata in binary link sections. The CLI extracts this at build time, processes assets, and patches the binary with final URLs.

6. Server Functions as RPC

The #[server] macro generates dual code paths - client serialization and server handler - enabling seamless RPC-style communication.

Important Design Decisions

1. Single VirtualDOM: Even multi-window desktop apps share one VirtualDOM for simpler state management
2. Scope-Based Cleanup: All state (signals, tasks, contexts) is tied to component scope lifetime
3. Platform Agnostic Events: Events are converted through HtmlEventConverter trait for cross-platform support
4. Binary Protocols: Desktop and liveview use Sledgehammer binary format for compact mutation encoding
5. Generational GC: References are invalidated by generation counters, preventing use-after-free without runtime overhead per access

Future Development Areas

These docs are designed to help with planned features:

• Custom Bundlers: Replacing tauri-bundler with native implementation
• CLI Tunnels: Remote device hot-reloading via SSH/SCP
• Workspace Hot-Patching: Patching library crates, not just the tip crate
• Universal Android Builds: Single APK for all architectures
• Fullstack Extensions: First-party database, auth, IAAC, secrets