108 lines
5.1 KiB
Markdown
108 lines
5.1 KiB
Markdown
# 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
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `01-CORE.md` | VirtualDOM, rendering pipeline, component system, diffing algorithm |
|
|
| `02-CLI.md` | Build system, dev server, bundling, terminal UI, platform support |
|
|
| `03-RSX.md` | RSX macro parsing, AST types, code generation, autofmt |
|
|
| `04-SIGNALS.md` | Signals, generational-box, hooks, stores, state management |
|
|
| `05-FULLSTACK.md` | Server functions, SSR, hydration, client-server communication |
|
|
| `06-RENDERERS.md` | Web, desktop, native, liveview renderer implementations |
|
|
| `07-HOTRELOAD.md` | Subsecond hot-patching, RSX hot-reload, devtools protocol |
|
|
| `08-ASSETS.md` | Manganis asset system, const serialization, build-time processing |
|
|
| `09-ROUTER.md` | Routing system, Routable trait, navigation, history |
|
|
| `10-WASM-SPLIT.md` | WASM code splitting, lazy loading, chunk management |
|
|
|
|
## 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
|