# dioxuslabs/dioxus architecture

> Architecture diagram of the GitHub repository dioxuslabs/dioxus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dioxuslabs/dioxus
- Repository: https://github.com/dioxuslabs/dioxus

## Overview

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: [`packages/core`](https://github.com/dioxuslabs/dioxus/tree/main/packages/core) (Core), [`packages/web`](https://github.com/dioxuslabs/dioxus/tree/main/packages/web) (Web), [`packages/cli`](https://github.com/dioxuslabs/dioxus/tree/main/packages/cli) (CLI), [`packages/fullstack-core`](https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack-core) (FS Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring"]
  node_rsx["RSX<br/>syntax macro"]
  node_core_macro["Core Macro<br/>component macro"]
  node_router_macro["Router Macro<br/>route macro"]
  node_fullstack_macro["Fullstack Macro<br/>server-fn macro"]
  node_wasm_split_macro["Wasm Split<br/>split macro"]
end

subgraph group_runtime["Runtime"]
  node_dioxus_fa["Dioxus<br/>workspace facade"]
  node_core["Core<br/>reactive runtime"]
  node_signals["Signals<br/>state primitive"]
  node_hooks["Hooks<br/>hook APIs"]
  node_stores["Stores<br/>derived state"]
  node_html["HTML Events<br/>shared event types"]
end

subgraph group_rendering["Renderers"]
  node_web["Web<br/>browser renderer"]
  node_desktop["Desktop<br/>native webview"]
  node_native_dom["Native DOM<br/>native renderer"]
  node_native["Native"]
  node_ssr["SSR<br/>server renderer"]
  node_liveview["Liveview<br/>server-driven ui"]
end

subgraph group_fullstack["Fullstack"]
  node_fullstack_core["FS Core<br/>transport core"]
  node_fullstack["Fullstack<br/>client transport"]
  node_fullstack_server["FS Server<br/>server runtime"]
end

subgraph group_tooling["Tooling"]
  node_cli["CLI<br/>build orchestrator"]
  node_asset_resolver["Assets<br/>asset resolver"]
  node_manganis["Manganis<br/>asset packaging"]
  node_hotreload["Hot Reload<br/>incremental dev"]
  node_interpreter["Interpreter<br/>mutation eval"]
end

subgraph group_platform["Platform"]
end

subgraph group_examples["Examples & Tests"]
  node_playwright["Playwright<br/>e2e tests"]
end

node_rsx -->|"builds UI"| node_core
node_core_macro -->|"generates"| node_core
node_router_macro -->|"builds routes"| node_core
node_router_macro -->|"uses events"| node_html
node_fullstack_macro -->|"emits fns"| node_fullstack_core
node_wasm_split_macro -->|"splits code"| node_interpreter
node_core -->|"reacts to"| node_signals
node_hooks -->|"wraps"| node_signals
node_hooks -->|"attaches to"| node_core
node_stores -->|"subscribes"| node_signals
node_core -->|"dispatches"| node_html
node_web -->|"consumes mutations"| node_core
node_web -->|"maps events"| node_html
node_desktop -->|"hosts"| node_web
node_desktop -->|"applies updates"| node_core
node_native_dom -->|"writes mutations"| node_core
node_native -->|"hosts"| node_native_dom
node_ssr -->|"renders from"| node_core
node_liveview -->|"mirrors state"| node_core
node_fullstack_core -->|"pairs with"| node_ssr
node_fullstack -->|"encodes requests"| node_fullstack_core
node_fullstack_server -->|"serves transport"| node_fullstack_core
node_fullstack_server -->|"serves html"| node_ssr
node_cli -->|"resolves assets"| node_asset_resolver
node_cli -->|"packages assets"| node_manganis
node_cli -->|"drives dev loop"| node_hotreload
node_cli -->|"executes mutations"| node_interpreter
node_manganis -->|"feeds web assets"| node_web
node_manganis -->|"feeds native assets"| node_desktop
node_playwright -->|"validates"| node_web
node_playwright -->|"validates"| node_fullstack_server

click node_dioxus_fa "https://github.com/dioxuslabs/dioxus/tree/main/packages/dioxus"
click node_rsx "https://github.com/dioxuslabs/dioxus/tree/main/packages/rsx"
click node_core_macro "https://github.com/dioxuslabs/dioxus/tree/main/packages/core-macro"
click node_router_macro "https://github.com/dioxuslabs/dioxus/tree/main/packages/router-macro"
click node_fullstack_macro "https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack-macro"
click node_wasm_split_macro "https://github.com/dioxuslabs/dioxus/tree/main/packages/wasm-split/wasm-split-macro"
click node_core "https://github.com/dioxuslabs/dioxus/tree/main/packages/core"
click node_signals "https://github.com/dioxuslabs/dioxus/tree/main/packages/signals"
click node_hooks "https://github.com/dioxuslabs/dioxus/tree/main/packages/hooks"
click node_stores "https://github.com/dioxuslabs/dioxus/tree/main/packages/stores"
click node_html "https://github.com/dioxuslabs/dioxus/tree/main/packages/html"
click node_web "https://github.com/dioxuslabs/dioxus/tree/main/packages/web"
click node_desktop "https://github.com/dioxuslabs/dioxus/tree/main/packages/desktop"
click node_native_dom "https://github.com/dioxuslabs/dioxus/tree/main/packages/native-dom"
click node_native "https://github.com/dioxuslabs/dioxus/tree/main/packages/native"
click node_ssr "https://github.com/dioxuslabs/dioxus/tree/main/packages/ssr"
click node_liveview "https://github.com/dioxuslabs/dioxus/tree/main/packages/liveview"
click node_fullstack_core "https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack-core"
click node_fullstack "https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack"
click node_fullstack_server "https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack-server"
click node_cli "https://github.com/dioxuslabs/dioxus/tree/main/packages/cli"
click node_asset_resolver "https://github.com/dioxuslabs/dioxus/tree/main/packages/asset-resolver"
click node_manganis "https://github.com/dioxuslabs/dioxus/tree/main/packages/manganis/manganis"
click node_hotreload "https://github.com/dioxuslabs/dioxus/tree/main/packages/rsx-hotreload"
click node_interpreter "https://github.com/dioxuslabs/dioxus/tree/main/packages/interpreter"
click node_playwright "https://github.com/dioxuslabs/dioxus/tree/main/packages/playwright-tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rsx,node_core_macro,node_router_macro,node_fullstack_macro,node_wasm_split_macro,node_playwright toneBlue
class node_dioxus_fa,node_core,node_signals,node_hooks,node_stores,node_html toneAmber
class node_web,node_desktop,node_native_dom,node_native,node_ssr,node_liveview toneMint
class node_fullstack_core,node_fullstack,node_fullstack_server toneRose
class node_cli,node_asset_resolver,node_manganis,node_hotreload,node_interpreter toneIndigo
```

## Components

### Authoring

Compile-time RSX, component, routing, and config macros.

- [RSX](https://github.com/dioxuslabs/dioxus/tree/main/packages/rsx): syntax macro · Declarative UI syntax parser and code generation entrypoint. · `packages/rsx`
- [Core Macro](https://github.com/dioxuslabs/dioxus/tree/main/packages/core-macro): component macro · Component and props macro expansion for framework components. · `packages/core-macro`
- [Router Macro](https://github.com/dioxuslabs/dioxus/tree/main/packages/router-macro): route macro · Generates routable trees, route metadata, and navigation scaffolding. · `packages/router-macro`
- [Fullstack Macro](https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack-macro): server-fn macro · Compile-time support for typed server functions and fullstack plumbing. · `packages/fullstack-macro`
- [Wasm Split](https://github.com/dioxuslabs/dioxus/tree/main/packages/wasm-split/wasm-split-macro): split macro · 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](https://github.com/dioxuslabs/dioxus/tree/main/packages/dioxus): workspace facade · Top-level workspace and public facade crate that ties the framework together. · `packages/dioxus`
- [Core](https://github.com/dioxuslabs/dioxus/tree/main/packages/core): reactive runtime · Virtual DOM, reconciliation, scopes, scheduler, tasks, and runtime orchestration. · `packages/core`
- [Signals](https://github.com/dioxuslabs/dioxus/tree/main/packages/signals): state primitive · Signal, memo, and reactive data primitives used by the runtime. · `packages/signals`
- [Hooks](https://github.com/dioxuslabs/dioxus/tree/main/packages/hooks): hook APIs · Reusable state, effect, async, and context hook layer built on signals and core. · `packages/hooks`
- [Stores](https://github.com/dioxuslabs/dioxus/tree/main/packages/stores): derived state · Store and subscription abstractions for structured reactive data. · `packages/stores`
- [HTML Events](https://github.com/dioxuslabs/dioxus/tree/main/packages/html): shared event types · Cross-platform event, input, geometry, and attribute contract for renderers. · `packages/html`

### Renderers

Backend-specific targets for web, desktop, native, SSR, and liveview.

- [Web](https://github.com/dioxuslabs/dioxus/tree/main/packages/web): browser renderer · Browser DOM renderer with hydration, history, events, and JS interop. · `packages/web`
- [Desktop](https://github.com/dioxuslabs/dioxus/tree/main/packages/desktop): native webview · Desktop app host with windowing, IPC, menus, tray, and webview integration. · `packages/desktop`
- [Native DOM](https://github.com/dioxuslabs/dioxus/tree/main/packages/native-dom): native renderer · Native mutation writer and event bridge for non-browser rendering paths. · `packages/native-dom`
- [Native](https://github.com/dioxuslabs/dioxus/tree/main/packages/native): native host · Application host and renderer integration for native targets. · `packages/native`
- [SSR](https://github.com/dioxuslabs/dioxus/tree/main/packages/ssr): server renderer · Server-side HTML rendering and hydration template generation. · `packages/ssr`
- [Liveview](https://github.com/dioxuslabs/dioxus/tree/main/packages/liveview): server-driven ui · Server-driven UI runtime with pooled sessions and transport adapters. · `packages/liveview`

### Fullstack

Server-function, transport, and server-side rendering pipeline.

- [FS Core](https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack-core): transport core · Fullstack request encoding, transport, history, streaming, and error plumbing. · `packages/fullstack-core`
- [Fullstack](https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack): client transport · Client-side fullstack request helpers and payload encoders. · `packages/fullstack`
- [FS Server](https://github.com/dioxuslabs/dioxus/tree/main/packages/fullstack-server): server runtime · Server-side fullstack launcher, SSR integration, server functions, and streaming. · `packages/fullstack-server`

### Tooling

CLI, bundling, assets, hot reload, and packaging.

- [CLI](https://github.com/dioxuslabs/dioxus/tree/main/packages/cli): build orchestrator · Workspace build, serve, bundle, check, and codegen orchestration. · `packages/cli`
- [Assets](https://github.com/dioxuslabs/dioxus/tree/main/packages/asset-resolver): asset resolver · Asset discovery and resolution for web and native targets. · `packages/asset-resolver`
- [Manganis](https://github.com/dioxuslabs/dioxus/tree/main/packages/manganis/manganis): asset packaging · Asset embedding, CSS/image/JS handling, and platform packaging bridge. · `packages/manganis/manganis`
- [Hot Reload](https://github.com/dioxuslabs/dioxus/tree/main/packages/rsx-hotreload): incremental dev · RSX hot reload and targeted patch generation for fast development loops. · `packages/rsx-hotreload`
- [Interpreter](https://github.com/dioxuslabs/dioxus/tree/main/packages/interpreter): mutation eval · JavaScript/native mutation execution and hydration/patch support. · `packages/interpreter`

### Examples & Tests

Representative apps and end-to-end validation suites.

- [Playwright](https://github.com/dioxuslabs/dioxus/tree/main/packages/playwright-tests): e2e tests · Browser-driven integration suite covering web, routing, hydration, and fullstack flows. · `packages/playwright-tests`

## Connections

- 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.
