AGENTS.md

1# Dioxus Agent Guide
2 
3Dioxus 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).
4 
5## Quick Overview
6 
7- **Language**: Rust (stable toolchain)
8- **UI Model**: React-like with VirtualDOM, components, hooks, signals
9- **Syntax**: JSX-like `rsx!` macro for declaring UI
10- **Platforms**: Web, Desktop (Windows/macOS/Linux), Mobile, Native, LiveView (server-rendered)
11 
12## Workspace Structure
13 
14```
15packages/
16├── dioxus/           # Main re-export crate users depend on
17├── core/             # VirtualDOM, components, diffing, scheduling
18├── rsx/              # RSX macro parsing and code generation
19├── rsx-hotreload/    # Template diffing for hot-reload
20├── signals/          # Reactive state (Signal, Memo, Store)
21├── hooks/            # Built-in hooks (use_signal, use_effect, etc.)
22├── router/           # Type-safe routing with #[derive(Routable)]
23├── fullstack/        # SSR, hydration, #[server] functions
24├── cli/              # `dx` build tool, dev server, bundling
25├── web/              # WASM renderer
26├── desktop/          # Wry/Tao webview renderer
27├── native/           # Blitz/Vello GPU renderer
28├── liveview/         # WebSocket streaming renderer
29├── manganis/         # asset!() macro for compile-time assets
30├── subsecond/        # Hot-patching system (jump table indirection)
31├── devtools/         # Dev server communication protocol
32├── interpreter/      # Sledgehammer JS for DOM mutations
33└── wasm-split/       # WASM code splitting
34```
35 
36## Architecture Documentation
37 
38For deeper understanding, see `notes/architecture/`:
39 
40| When working on...                         | Read...            |
41| ------------------------------------------ | ------------------ |
42| VirtualDOM, components, diffing, events    | `01-CORE.md`       |
43| CLI, build system, bundling, dev server    | `02-CLI.md`        |
44| RSX macro, parsing, formatting             | `03-RSX.md`        |
45| Signals, state management, reactivity      | `04-SIGNALS.md`    |
46| Server functions, SSR, hydration           | `05-FULLSTACK.md`  |
47| Web/desktop/native/liveview renderers      | `06-RENDERERS.md`  |
48| Hot-reload, hot-patching, devtools         | `07-HOTRELOAD.md`  |
49| Asset macro, manganis, const serialization | `08-ASSETS.md`     |
50| Router, navigation, nested routes          | `09-ROUTER.md`     |
51| WASM code splitting                        | `10-WASM-SPLIT.md` |
52 
53## Key Concepts
54 
55- **VirtualDOM**: Tree of `VNode` with templates, dynamic nodes, and attributes
56- **Signals**: Copy-able reactive primitives via generational-box (generation-based validity)
57- **WriteMutations**: Trait that renderers implement to apply DOM changes
58- **RSX**: Proc macro that compiles JSX-like syntax to `VNode` construction
59- **Server Functions**: `#[server]` macro generates client RPC stubs and server handlers
60- **Subsecond**: Hot-patches Rust code via jump table indirection (no memory modification)
61- **Manganis**: `asset!("/main.css")` macro for including assets by embedding data via linker symbols
62 
63## Common Patterns
64 
65**Component definition**:
66```rust
67#[component]
68fn MyComponent(name: String) -> Element {
69    let mut count = use_signal(|| 0);
70    rsx! {
71        button { onclick: move |_| count += 1, "{name}: {count}" }
72    }
73}
74```
75 
76## Notes for Agents
77 
781. The `dioxus` crate re-exports from other crates - most implementation is in `packages/core`, `packages/signals`, etc.
792. RSX macro expansion happens in `packages/rsx` - look there for syntax questions
803. Each renderer implements `WriteMutations` differently - see `06-RENDERERS.md`
814. Hot-reload has two systems: RSX template diffing (fast) and Subsecond code patching (full Rust)
825. Assets use link sections and binary patching - the `asset!()` macro creates symbols the CLI processes
83