How dioxuslabs/dioxus works
1. Repository shape
This is a Rust workspace for the Dioxus UI framework, split into many crates under packages/, plus example apps under examples/ and integration tests under packages/playwright-tests/. The workspace is not a single app; it is the framework, its compiler/macro layer, its runtimes, its platform renderers, and its CLI.
2. Authoring layer: RSX and macros
App code is written in Dioxus’s rsx! syntax and compiled through macro crates like packages/rsx, packages/core-macro, packages/html-internal-macro, packages/router-macro, packages/fullstack-macro, and packages/wasm-split-macro. These crates turn declarative UI into Rust AST/code at compile time, and also enforce route parsing, props generation, and other static checks.
3. Reactive application core
packages/core, packages/signals, packages/hooks, and packages/stores implement the reactive runtime: scopes, signals, memoization, effects, tasks, context, and diffing. This is the state/update engine that all renderers share. The main data flow is user events or async work updating signals, which schedules re-render/diff work in the core runtime.
4. Virtual DOM and event model
packages/core owns the virtual DOM and reconciliation logic, while packages/html defines the cross-platform event and attribute types used by components. The HTML crate is the shared contract for DOM-like events, input data, geometry, file data, and element metadata, so renderers can translate platform events into framework events consistently.
5. Renderer boundary: platform-specific output
Rendering is split by target:
- packages/web renders to browser DOM and handles hydration, browser events, history, and JS interop.
- packages/desktop wraps webview/native desktop concerns, windowing, IPC, shortcuts, tray, and native eval.
- packages/native-dom and packages/native support native renderer paths and application hosting.
- packages/ssr renders HTML on the server for pre-rendering and hydration.
- packages/liveview provides a server-driven UI model with adapters and pooled sessions.
The shared boundary is the virtual DOM/mutation stream coming out of core and going into a concrete backend.
6. Fullstack/server-function pipeline
Fullstack support is split into packages/fullstack, packages/fullstack-core, packages/fullstack-server, and the examples/07-fullstack/* apps. This layer handles server functions, request/response encoding, streaming, SSE, websockets, forms, headers, redirects, and error transport. The framework can move logic between client and server while preserving typed payloads and route-aware behavior.
7. Routing and navigation
packages/router provides the runtime router, route contexts, navigation hooks, link components, history integration, and outlet nesting. packages/router-macro generates the route tree and route metadata from types/annotations. Navigation state flows through router contexts into the renderer and, for web/fullstack, into browser history and SSR.
8. Assets, bundling, and build-time optimization
Static assets are handled by packages/manganis and packages/asset-resolver, with CSS/image/JS handling and asset embedding. packages/cli is the build/bundle/serve orchestrator and includes optimization passes in packages/cli/src/opt, plus integration points like esbuild, tailwind, and wasm-bindgen/wasm-opt. This is the boundary where source code is turned into runnable web, desktop, or mobile deliverables.
9. Hot reload and incremental development
packages/rsx-hotreload and packages/interpreter support fast dev loops: updating RSX structure, patching mutations, and evaluating targeted JS/native mutations without a full rebuild. The CLI’s serve path and the web/desktop runtimes are the main consumers of this infrastructure.
10. Platform packaging and native integration
Mobile and native packaging is spread across the CLI assets and renderer crates: Android Gradle/Kotlin templates, iOS Swift/SwiftPM assets, macOS plist templates, and desktop launch/webview code. packages/manganis/manganis and packages/desktop are important here because they bridge Rust app code to platform-native packaging and runtime APIs.
11. Documentation, examples, and validation
The examples/ tree demonstrates every major subsystem: UI composition, state, async, routing, fullstack, APIs, integrations, and native plugins. packages/playwright-tests contains end-to-end browser tests for routing, hydration, hot patching, fullstack behavior, and platform-specific cases. The repo also includes many crate-level unit/integration tests that validate macros, diffing, signals, SSR, and router behavior.
12. How a request/update typically flows
A component written with rsx! compiles through macros into runtime structures, runs inside the core reactive system, and emits mutations/diff results. Those mutations are consumed by the chosen backend: web DOM, desktop webview/native window, SSR HTML, or liveview transport. If the app uses fullstack/server functions, requests cross the client/server boundary through typed transport layers, and if assets are involved, the CLI and asset crates package them into the target artifact.
Main entry points: core Core · web Web · cli CLI · fullstack-core FS Core
Components 26
Authoring
Compile-time RSX, component, routing, and config macros.
- RSX · Declarative UI syntax parser and code generation entrypoint.
packages/rsx - Core Macro · Component and props macro expansion for framework components.
packages/core-macro - Router Macro · Generates routable trees, route metadata, and navigation scaffolding.
packages/router-macro - Fullstack Macro · Compile-time support for typed server functions and fullstack plumbing.
packages/fullstack-macro - Wasm Split · Macro support for splitting client and server WASM code paths.
packages/wasm-split/wasm-split-macro
Runtime
Reactive core, signals, stores, and shared state machinery.
- Dioxus · Top-level workspace and public facade crate that ties the framework together.
packages/dioxus - Core · Virtual DOM, reconciliation, scopes, scheduler, tasks, and runtime orchestration.
packages/core - Signals · Signal, memo, and reactive data primitives used by the runtime.
packages/signals - Hooks · Reusable state, effect, async, and context hook layer built on signals and core.
packages/hooks - Stores · Store and subscription abstractions for structured reactive data.
packages/stores - HTML Events · Cross-platform event, input, geometry, and attribute contract for renderers.
packages/html
Renderers
Backend-specific targets for web, desktop, native, SSR, and liveview.
- Web · Browser DOM renderer with hydration, history, events, and JS interop.
packages/web - Desktop · Desktop app host with windowing, IPC, menus, tray, and webview integration.
packages/desktop - Native DOM · Native mutation writer and event bridge for non-browser rendering paths.
packages/native-dom - Native · Application host and renderer integration for native targets.
packages/native - SSR · Server-side HTML rendering and hydration template generation.
packages/ssr - Liveview · Server-driven UI runtime with pooled sessions and transport adapters.
packages/liveview
Fullstack
Server-function, transport, and server-side rendering pipeline.
- FS Core · Fullstack request encoding, transport, history, streaming, and error plumbing.
packages/fullstack-core - Fullstack · Client-side fullstack request helpers and payload encoders.
packages/fullstack - FS Server · Server-side fullstack launcher, SSR integration, server functions, and streaming.
packages/fullstack-server
Tooling
CLI, bundling, assets, hot reload, and packaging.
- CLI · Workspace build, serve, bundle, check, and codegen orchestration.
packages/cli - Assets · Asset discovery and resolution for web and native targets.
packages/asset-resolver - Manganis · Asset embedding, CSS/image/JS handling, and platform packaging bridge.
packages/manganis/manganis - Hot Reload · RSX hot reload and targeted patch generation for fast development loops.
packages/rsx-hotreload - Interpreter · JavaScript/native mutation execution and hydration/patch support.
packages/interpreter
Examples & Tests
Representative apps and end-to-end validation suites.
- Playwright · Browser-driven integration suite covering web, routing, hydration, and fullstack flows.
packages/playwright-tests
Connections 31
- RSX → Core: builds UI · RSX expands into runtime structures consumed by the core renderer pipeline.
- Core Macro → Core: generates · Component macros emit props and component glue for core runtime usage.
- Router Macro → Core: builds routes · Route metadata and nested trees feed runtime navigation and outlets.
- Router Macro → HTML Events: uses events · Route/link components rely on shared event and attribute contracts.
- Fullstack Macro → FS Core: emits fns · Macro expansion produces typed server-function plumbing and payload bindings.
- Wasm Split → Interpreter: splits code · Split points inform targeted client/server mutation and loading behavior.
- Core → Signals: reacts to · Core scheduling and re-rendering are driven by signal updates.
- Hooks → Signals: wraps · Hooks build higher-level state and async patterns on signals.
- Hooks → Core: attaches to · Hooks integrate with scope lifecycle, effects, and suspense in core.
- Stores → Signals: subscribes · Stores expose structured reactive data backed by subscriptions.
- Core → HTML Events: dispatches · Core event handling uses shared HTML event and input types.
- Web → Core: consumes mutations · Browser renderer applies virtual DOM mutations from core.
- Web → HTML Events: maps events · Web translates DOM events into framework event types.
- Desktop → Web: hosts · Desktop builds on webview-style rendering and browser-like app surfaces.
- Desktop → Core: applies updates · Desktop receives framework mutations through the same core boundary.
- Native DOM → Core: writes mutations · Native DOM backend consumes the shared mutation stream from core.
- Native → Native DOM: hosts · Native runtime wraps the native DOM renderer and application lifecycle.
- SSR → Core: renders from · SSR produces HTML from the same virtual DOM and component tree.
- Liveview → Core: mirrors state · Liveview uses core-driven UI updates over a server transport.
- FS Core → SSR: pairs with · Fullstack server-side plumbing integrates with SSR output and document handling.
- Fullstack → FS Core: encodes requests · Client-side helpers encode payloads and transport requests through core fullstack types.
- FS Server → FS Core: serves transport · Server runtime handles request decoding, streaming, and response transport.
- FS Server → SSR: serves html · Server runtime combines SSR with fullstack document generation.
- CLI → Assets: resolves assets · CLI build and serve paths use asset discovery and resolution.
- CLI → Manganis: packages assets · CLI integrates asset embedding and platform packaging support.
- CLI → Hot Reload: drives dev loop · Serve and patch commands use hot reload infrastructure.
- CLI → Interpreter: executes mutations · CLI dev and build flows invoke interpreter-based patch evaluation.
- Manganis → Web: feeds web assets · Packaged assets are consumed by browser-target builds.
- Manganis → Desktop: feeds native assets · Asset packaging supplies desktop/native runtime resources.
- Playwright → Web: validates · End-to-end tests exercise web rendering, routing, hydration, and patching.
- Playwright → FS Server: validates · Browser tests cover server-function and streaming flows.