Dioxus Agent Guide

Dioxus is a cross-platform UI framework for Rust, similar to React. It compiles to web (WASM), desktop (webview), mobile (iOS/Android), and native (GPU-rendered).

Quick Overview

• Language: Rust (stable toolchain)
• UI Model: React-like with VirtualDOM, components, hooks, signals
• Syntax: JSX-like rsx! macro for declaring UI
• Platforms: Web, Desktop (Windows/macOS/Linux), Mobile, Native, LiveView (server-rendered)

Workspace Structure

packages/
├── dioxus/           # Main re-export crate users depend on
├── core/             # VirtualDOM, components, diffing, scheduling
├── rsx/              # RSX macro parsing and code generation
├── rsx-hotreload/    # Template diffing for hot-reload
├── signals/          # Reactive state (Signal, Memo, Store)
├── hooks/            # Built-in hooks (use_signal, use_effect, etc.)
├── router/           # Type-safe routing with #[derive(Routable)]
├── fullstack/        # SSR, hydration, #[server] functions
├── cli/              # `dx` build tool, dev server, bundling
├── web/              # WASM renderer
├── desktop/          # Wry/Tao webview renderer
├── native/           # Blitz/Vello GPU renderer
├── liveview/         # WebSocket streaming renderer
├── manganis/         # asset!() macro for compile-time assets
├── subsecond/        # Hot-patching system (jump table indirection)
├── devtools/         # Dev server communication protocol
├── interpreter/      # Sledgehammer JS for DOM mutations
└── wasm-split/       # WASM code splitting

Architecture Documentation

For deeper understanding, see notes/architecture/:

Key Concepts

• VirtualDOM: Tree of VNode with templates, dynamic nodes, and attributes
• Signals: Copy-able reactive primitives via generational-box (generation-based validity)
• WriteMutations: Trait that renderers implement to apply DOM changes
• RSX: Proc macro that compiles JSX-like syntax to VNode construction
• Server Functions: #[server] macro generates client RPC stubs and server handlers
• Subsecond: Hot-patches Rust code via jump table indirection (no memory modification)
• Manganis: asset!("/main.css") macro for including assets by embedding data via linker symbols

Common Patterns

Component definition:

#[component]
fn MyComponent(name: String) -> Element {
    let mut count = use_signal(|| 0);
    rsx! {
        button { onclick: move |_| count += 1, "{name}: {count}" }
    }
}

Notes for Agents

1. The dioxus crate re-exports from other crates - most implementation is in packages/vdom, packages/signals, etc.
2. RSX macro expansion happens in packages/rsx - look there for syntax questions
3. Each renderer implements WriteMutations differently - see 06-RENDERERS.md
4. Hot-reload has two systems: RSX template diffing (fast) and Subsecond code patching (full Rust)
5. Assets use link sections and binary patching - the asset!() macro creates symbols the CLI processes