// becomes these calls
React.createElement(div, { class: "abc" }, \[React.createText("hello world")\]);
// This markup
Hello world
// becomes these calls
React.createElement(div, { class: "abc" }, \[React.createText("hello world")\]);
This means for every new element in your tree, the transpiled JS is allocating several objects, arrays, and complex structures between _every_ render. Thereâs no wonder why React isnât on the top of the performance charts! In Rust, itâs generally not best practice to generate so many heap-allocated objects.
Heck, there was even a very popular reddit post talking about this problem.
[âWorried about âmodernâ Rust GUI librariesâ](https://www.reddit.com/r/rust/comments/yd9ngs/worried_about_modern_rust_gui_libraries/)
In Dioxus, we noticed this early on and decided to see if we could reuse all the heap allocations instead of just tossing them out. Inspired by the work on Dodrio, Dioxus is implemented using a bump allocator and double-buffering, just like many high-performance GPU APIs.
When you create a div, or a piece of text, or anything in Dioxus, it simply gets allocated inside a bump arena that gets reset when diffed. No cleanup, no extra heap allocations, just steady-state reuse of pre-allocated memory.
This is fast. Really fast. And when coupled with automatic component memoization, itâs really easy to write Dioxus apps that are memory efficient and faster than React.
Great, case-closed, thatâs it, right?
Well, no. Dioxus still wasnât nearly as fast as Svelte, Sycamore, SolidJS, or even InfernoJS. Weâve optimized a bunch of tiny things, like string caching, batched DOM manipulations, faster PartialEq, diffing, and pretty much everything you could think of.
Except, weâre creating new objects, still in the heap, and doing a lot of diffing work. In the words of the creator of Svelte,
> But you know what would be even faster? _Not doing that._
To really make Dioxus faster, we need to make it do less work - or, at the very least, less work at runtime. SolidJS does this by thrusting you into this world of signals. We love signals! They might even come to Dioxus at some point (aka Preact signals). But, in the world where we still care about providing `&mut T` from `use_hook` , we need to find a new solution that doesnât require rewriting your React apps to use signals.
Well, weâre working in Rust, weâve got const, macros, custom PartialEq⊠letâs see if we can move some of this work to compile time.
To build a Dioxus app, you pretty much have to use the `rsx!` proc macro. We unfortunately donât support a builder API or alternatives. Thereâs a lot of good reasons to do this: performance, forward compatibility, tooling, ergonomics, etc.
A block of `rsx!` might look like this:
rsx! {
div {
h1 {"Glorious Counter"}
p { "Count: {val}" }
button { onclick: move |\_| val += 1, "Increment" }
button { onclick: move |\_| val \-= 1, "Decrement" }
}
}
rsx! {
div {
h1 {"Glorious Counter"}
p { "Count: {val}" }
button { onclick: move |\_| val += 1, "Increment" }
button { onclick: move |\_| val \-= 1, "Decrement" }
}
}
If you look closely, youâll notice that the entire tree is declared within the macro. There arenât elements being created at compile time, except for the dynamic text within the paragraph element. In React, youâd have to create every element from scratch, one-by-one, every time. But in Dioxus, we can do better.
The new technique Dioxus uses is to split each `rsx!` call into a static `Template` and a list of dynamic nodes. For the above `rsx!` call, this might look like
static THIS\_TEMPLATE: Template \= Template { /\* \*/ };
VNode {
template: THIS\_TEMPLATE,
dynamic\_nodes: \[\
Text(format\_args!("Count: {val}")\
\]
}
static THIS\_TEMPLATE: Template \= Template { /\* \*/ };
VNode {
template: THIS\_TEMPLATE,
dynamic\_nodes: \[\
Text(format\_args!("Count: {val}")\
\]
}
Now, on every render, we only create the single dynamic node. When we go to diff the VNode, we only need to diff that one text node too. So now, instead of 11 comparisons (9 elements and 2 attributes) we have one comparison. Diffing this template takes 90% less time than before! This is a huge win! Our app can be 10x bigger for the same diffing cost. And the results speak for themselves. Combined with the integration of [Sledgehammer](https://crates.io/crates/sledgehammer)
, Dioxus is pushing the limits of what the React model can reasonably achieve.
The React team also agrees that React can be better. Thatâs why theyâve started working on an experimental compiler for React.
[https://reactjs.org/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.html](https://reactjs.org/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.html)
The plan here is to cache these elements and only update them when variables inside the _component_ change. However, React-Forget still doesnât fix the underlying issue of node creation, memory usage, or anything of the other things compile-time memoization achieves.
Templates make diffing the tree faster, but they can also make building the UI faster too. Both SolidJS and LitHTML take advantage of this hack to achieve fantastic performance.
With support from the renderer, Dioxus can actually serialize these parsed RSX templates and let the renderer do all the caching.
Before, if we wanted to assemble a tree of nodes from an iterator, weâd have to do a ton of tedious work, creating each list item part by part.
// This tree
ul {
(0..len).map(|id| rsx!{
li {
h3 { "user" }
div { "hello {id}" }
}
})
}
// item one...
Edit::CreateElement("li")
Edit::CreateElement("h3")
Edit::CreateText("user")
Edit::AppendChildren(1)
Edit::CreateElement("div")
Edit::CreateText("hello 0", 2)
Edit::AppendChildren(1)
Edit::AppendChildren(2)
// item two...
Edit::CreateElement("li")
Edit::CreateElement("h3")
Edit::CreateText("user")
Edit::AppendChildren(1)
Edit::CreateElement("div")
Edit::CreateText("hello 0", 2)
Edit::AppendChildren(1)
Edit::AppendChildren(2)
// and so on until we attach all the li to the ul
Edit::AppendChildren(len)
// This tree
ul {
(0..len).map(|id| rsx!{
li {
h3 { "user" }
div { "hello {id}" }
}
})
}
// item one...
Edit::CreateElement("li")
Edit::CreateElement("h3")
Edit::CreateText("user")
Edit::AppendChildren(1)
Edit::CreateElement("div")
Edit::CreateText("hello 0", 2)
Edit::AppendChildren(1)
Edit::AppendChildren(2)
// item two...
Edit::CreateElement("li")
Edit::CreateElement("h3")
Edit::CreateText("user")
Edit::AppendChildren(1)
Edit::CreateElement("div")
Edit::CreateText("hello 0", 2)
Edit::AppendChildren(1)
Edit::AppendChildren(2)
// and so on until we attach all the li to the ul
Edit::AppendChildren(len)
With templates, we can serialize the tree and pass it to the renderer:
static TEMPLATE\_HTML \= "
";
Edit::SaveTemplate("demo.rs:5:1", TEMPLATE\_HTML);
Now, whenever we create the list elements, itâs as simple as cloning some nodes that already exist and precisely modifying just a small part
Edit::LoadTemplate("demo.rs:5:1");
Edit::HydateText(0, "hello 0");
Edit::LoadTemplate("demo.rs:5:1");
Edit::HydateText(0, "hello 0");
For the tiny case weâre showing here, the benefit might seem limited. However, for real-world apps with lots of elements, custom styles, and all sorts of extra metadata, this caching system is immensely powerful and extremely performant.
Now that weâre working with the mindset of templates, we can start to build new functionality previously locked behind the old model.
One amazing feature added to Dioxus using the new template model is hot reloading. You can now modify your running Dioxus app without recompiling, provided you add, remove, or modify elements inside of `rsx!` . This mechanism works for _any_ renderer too, since each renderer has to implement the same protocol to manage edits.
Not only can templates be cached inside of a renderer, they can be modified after-the-fact. The renderer is smart enough to track down the instance of every template node on the page and apply the same patches.
Another addition to Dioxus 0.3 is the new LiveView renderer. Much like its counterpart Phoenix LiveView, Dioxus LiveView enables entirely server-rendered apps and components while shipping minimal JS to the client. In the Liveview model, minimizing latency and bandwidth is crucial to keeping apps snappy, especially for lower-end clients.
Now, instead of sending hundreds or thousands of edits to the client to render things like lists and complex markup, Dioxus packages all the templates the client will use inside of the HTML shipped to the client. A sample HTML document that might be sent from the server to the client may look like this:
userhello \_id\_
userhello \_id\_
Notice how the templates are collected during SSR and inserted into the header. The only edits sent over the network from the server to the client are commands to create/remove template nodes and to precisely modify just the nodes that changed. Fast, simple, and scalable!
The other technique that SolidJS uses to achieve faster SSR performance is combining pre-rendered portions of templates together through string concatenation. Since the template is known at compile time, we can break it up into smaller chunks and just stitch them together during rendering. No need to build and traverse huge element trees!
// Cached template segments:
PreRendered("
Hello world 1 -->".into(),),
Node(0,),
PreRendered(
"<-- Hello world 2
Hello world 1 -->".into(),),
Node(0,),
PreRendered(
"<-- Hello world 2
nest 1
nest 2
".into(),
),
Node(1,),
Node(2,),
PreRendered("
".into(),)
Even with all the innovations here, itâs still very important to remember that Dioxus still takes after React. No matter how many tweaks, optimizations, and improvements we make to Dioxus, you can still shoot yourself in the foot with the classic React footguns.
These include
* Unkeyed lists
* Poor use of memoization and comparisons
* Misuse of use\_effect
* âGod componentsâ that do everything
and a whole host of other issues that you might not find in frameworks like Solid and Sycamore.
That being said, since Dioxus relies on a VirtualDom, it can be used as the primary state system for any renderer. And we have a ton of options for renderers:
* Desktop (webview)
* Mobile (webview)
* Web
* TUI
* Skia
* LiveView
* Blitz (WGPU)
* SSR + Hydration
* Static site generation
* VR/AR (coming soon!)
Note that all this work is being done for Dioxus 0.3 and hasnât yet been released as a major version. Weâre still dogfooding these changes to make sure no new bugs have slipped through. If you want these changes released sooner rather than later, feel free to build something with `main` and let us know!
* Discord
* Github
* Reddit Post
On this page
------------
* [Dioxus shares Reactâs DNA](https://dioxuslabs.com/blog/templates-diffing/#dioxus-shares-reacts-dna)
* [Overcoming the warts of React](https://dioxuslabs.com/blog/templates-diffing/#overcoming-the-warts-of-react)
* [Making Dioxus faster by doing less work](https://dioxuslabs.com/blog/templates-diffing/#making-dioxus-faster-by-doing-less-work)
* [Taking it a step further](https://dioxuslabs.com/blog/templates-diffing/#taking-it-a-step-further)
* [What does this enable?](https://dioxuslabs.com/blog/templates-diffing/#what-does-this-enable)
* [Hot Reloading](https://dioxuslabs.com/blog/templates-diffing/#hot-reloading)
* [Performant LiveView](https://dioxuslabs.com/blog/templates-diffing/#performant-liveview)
* [Faster Server-Side-Rendering (SSR)](https://dioxuslabs.com/blog/templates-diffing/#faster-server-side-rendering-ssr)
* [Disclaimer](https://dioxuslabs.com/blog/templates-diffing/#disclaimer)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
[Back to blog](https://dioxuslabs.com/blog/)
Going fulltime on Dioxus
========================
May 5, 2023 - Jonathan Kelley
### Dioxus is now my full time job! I'm so excited to be able to work on this full time.
> Jan 5, 2023
> [@jkelleyrtp](https://github.com/jkelleyrtp)
Hey folks, weâre going to deviate from the typical release post or technical discussion and talk about the future of Dioxus. If youâre new here, Dioxus is a UI library for Rust that supports web, desktop, mobile, liveview, TUI, and more. Our goal is to simplify app development, combining projects like React, Electron, Flutter, NextJS, InkJS, and Phoenix under one unified stack.
Iâm happy to announce that Iâm now working on Dioxus Labs full time. Thanks to the generous support of Futurewei, Satellite.im, the GitHub Accelerator program, and several amazing individuals, Dioxus Labs is now able to employ both myself and top contributors like ealmloff full time.
Over the past year, Dioxus has grown significantly. Weâve made huge strides in pushing forward the Rust frontend ecosystem. Some of the amazing innovations in this space include hot-reloading, syn-based autoformatting, and dioxus-liveview. Built on top of these innovations are breakthrough projects like Sledgehammer, Taffy, Freya, and Blitz. We want to continue innovating while also maturing Dioxus on all fronts.
Going full time on open source is a huge jump. It takes a lot of courage to leave a company as great as Cloudflare. Being independent truly means independent - no work colleagues, no free snacks, no transit card, no beautiful office, and no company-sponsored health insurance. That being said, Iâm eternally grateful to have the opportunity to pursue Dioxus Labs with my entire passion. We are committed to helping developers build better apps.
We have big plans for the future. Hereâs a rough sketch of what the future holds for Dioxus:
* Massively overhauled docs with tutorial videos and one-click-deploy example projects
* Stable support for `async` components, suspense boundaries, and error boundaries
* Stable release of Blitz (our HTML/CSS renderer built on Vello) with an open API
* A deployment and release management platform for Dioxus-based apps
* An overhaul of the Dioxus Router with support for many NextJS features
* A standard library of cross-platform functionality (GPS/notifications)
* Better DevTool including VirtualDom visualization, live state inspection, and visual editing
* Support for panic recovery and bundle splitting in rustc for `wasm32-unknown-unknown`
Thereâs a lot more on the roadmap. If youâre at all interested in contributing to Dioxus, let us know in the community discord, and weâll be there to help. If youâre interested in supporting the project to help us grow, please reach out.
Again, a huge thanks to our wonderful sponsors and an even bigger thanks to the Rust community who have used and contributed to Dioxus over the past year.
Yours truly,
Jonathan Kelley
On this page
------------
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
[Back to blog](https://dioxuslabs.com/blog/)
Dioxus 0.2
==========
March 9, 2022 - Jonathan Kelley
### Just over two months in, and we already have a ton of awesome changes to Dioxus!
Thanks to these amazing folks for their financial support on OpenCollective:
* [@t1m0t](https://github.com/t1m0t)
* [@alexkirsz](https://github.com/t1m0t)
* [@freopen](https://github.com/freopen)
* [@DannyMichaels](https://github.com/DannyMichaels)
* [@SweetLittleMUV](https://github.com/Fatcat560)
Thanks to these amazing folks for their code contributions:
* [@mrxiaozhuox](https://github.com/mrxiaozhuox)
* [@autarch](https://github.com/autarch)
* [@FruitieX](https://github.com/FruitieX)
* [@t1m0t](https://github.com/t1m0t)
* [@ealmloff](https://github.com/ealmloff)
* [@oovm](https://github.com/oovm)
* [@asaaki](https://github.com/asaaki)
Just over two months in, and we already have a ton of awesome changes to Dioxus!
Dioxus is a recently-released library for building interactive user interfaces (GUI) with Rust. It is built around a Virtual DOM, making it portable for the web, desktop, server, mobile, and more. Dioxus looks and feels just like React, so if you know React, then you'll feel right at home.
fn app(cx: Scope) -> Element {
let mut count = use\_state(&cx, || 0);
cx.render(rsx! { h1 { "Count: {count}" } button { onclick: move |\_| count += 1, "+" } button { onclick: move |\_| count -= 1, "-" } })
}
fn app(cx: Scope) -> Element {
let mut count = use\_state(&cx, || 0);
cx.render(rsx! { h1 { "Count: {count}" } button { onclick: move |\_| count += 1, "+" } button { onclick: move |\_| count -= 1, "-" } })
}
A _ton_ of stuff happened in this release; 550+ commits, 23 contributors, 2 minor releases, and 6 backers on Open Collective.
Some of the major new features include:
* We now can render into the terminal, similar to Ink.JS - a huge thanks to [@ealmloff](https://github.com/ealmloff)
* We have a new router in the spirit of React-Router [@autarch](https://github.com/autarch)
* We now have Fermi for global state management in the spirit of [Recoil.JS](https://recoiljs.org/)
* Our desktop platform got major upgrades, getting closer to parity with Electron [@mrxiaozhuox](https://github.com/mrxiaozhuox)
* Our CLI tools now support HTML-to-RSX translation for converting 3rd party HTML into Dioxus [@mrxiaozhuox](https://github.com/mrxiaozhuox)
* Dioxus-Web is sped up by 2.5x with JS-based DOM manipulation (3x faster than React)
We also fixed and improved a bunch of stuff - check out the full list down below.
When Dioxus was initially released, we had very simple support for logging Dioxus elements out as TUI elements. In the past month or so, [@ealmloff](https://github.com/ealmloff)
really stepped up and made the new crate a reality.
The new TUI renderer even supports mouse movements, keyboard input, async tasks, borders, and a ton more.
We totally revamped the router, switching away from the old yew-router approach to the more familiar [React-Router](http://reactrouter.com/)
. It's less type-safe but provides more flexibility and support for beautiful URLs.
Apps with routers are _really_ simple now. It's easy to compose the "Router", a "Route", and "Links" to define how your app is laid out:
fn app(cx: Scope) -> Element {
cx.render(rsx! { Router { onchange: move |\_| log::info!("Route changed!"), ul { Link { to: "/", li { "Go home!" } } Link { to: "users", li { "List all users" } } Link { to: "blog", li { "Blog posts" } } } Route { to: "/", "Home" } Route { to: "/users", "User list" } Route { to: "/users/:name", User {} } Route { to: "/blog", "Blog list" } Route { to: "/blog/:post", BlogPost {} } Route { to: "", "Err 404 Route Not Found" } } })
}
fn app(cx: Scope) -> Element {
cx.render(rsx! { Router { onchange: move |\_| log::info!("Route changed!"), ul { Link { to: "/", li { "Go home!" } } Link { to: "users", li { "List all users" } } Link { to: "blog", li { "Blog posts" } } } Route { to: "/", "Home" } Route { to: "/users", "User list" } Route { to: "/users/:name", User {} } Route { to: "/blog", "Blog list" } Route { to: "/blog/:post", BlogPost {} } Route { to: "", "Err 404 Route Not Found" } } })
}
We're also using hooks to parse the URL parameters and segments so you can interact with the router from anywhere deeply nested in your app.
#\[derive(Deserialize)\]
struct Query { name: String }
fn BlogPost(cx: Scope) -> Element {
let post = use\_route(&cx).segment("post")?; let query = use\_route(&cx).query::()?;
cx.render(rsx!{ "Viewing post {post}" "Name selected: {query}" })
}
#\[derive(Deserialize)\]
struct Query { name: String }
fn BlogPost(cx: Scope) -> Element {
let post = use\_route(&cx).segment("post")?; let query = use\_route(&cx).query::()?;
cx.render(rsx!{ "Viewing post {post}" "Name selected: {query}" })
}
Give a big thanks to [@autarch](https://github.com/autarch)
for putting in all the hard work to make this new router a reality.
The Router guide is [available here](https://dioxuslabs.com/nightly/router/)
- thanks to [@dogedark](https://github.com/dogedark)
.
Managing state in your app can be challenging. Building global state management solutions can be even more challenging. For the first big attempt at building a global state management solution for Dioxus, we chose to keep it simple and follow in the footsteps of the [Recoil.JS](http://recoiljs.org/)
project.
Fermi uses the concept of "Atoms" for global state. These individual values can be get/set from anywhere in your app. Using state with Fermi is basically as simple as `use_state`.
// Create a single value in an "Atom"
static TITLE: Atom<&str> = |\_| "Hello";
// Read the value from anywhere in the app, subscribing to any changes
fn app(cx: Scope) -> Element {
let title = use\_read(&cx, TITLE); cx.render(rsx!{ h1 { "{title}" } Child {} })
}
// Set the value from anywhere in the app
fn Child(cx: Scope) -> Element {
let set\_title = use\_set(&cx, TITLE); cx.render(rsx!{ button { onclick: move |\_| set\_title("goodbye"), "Say goodbye" } })
}
// Create a single value in an "Atom"
static TITLE: Atom<&str> = |\_| "Hello";
// Read the value from anywhere in the app, subscribing to any changes
fn app(cx: Scope) -> Element {
let title = use\_read(&cx, TITLE); cx.render(rsx!{ h1 { "{title}" } Child {} })
}
// Set the value from anywhere in the app
fn Child(cx: Scope) -> Element {
let set\_title = use\_set(&cx, TITLE); cx.render(rsx!{ button { onclick: move |\_| set\_title("goodbye"), "Say goodbye" } })
}
For internal components, explicitly declaring props structs can become tedious. That's why we've built the new `component` macro. This macro lets you inline your props definition right into your component function arguments.
Simply add the `component` macro to your component:
#\[component\]
fn Child<'a>(
cx: Scope, name: String, age: String, onclick: EventHandler<'a, ClickEvent>
) -> Element {
cx.render(rsx!{ button { "Hello, {name}" "You are {age} years old" onclick: move |evt| onclick.call(evt) } })
}
#\[component\]
fn Child<'a>(
cx: Scope, name: String, age: String, onclick: EventHandler<'a, ClickEvent>
) -> Element {
cx.render(rsx!{ button { "Hello, {name}" "You are {age} years old" onclick: move |evt| onclick.call(evt) } })
}
You won't be able to document each field or attach attributes so you should refrain from using it in libraries.
Sometimes you don't want to specify _every_ value in a component's props, since there might a lot. That's why the `Props` macro now supports optional fields. You can use a combination of `default`, `strip_option`, and `optional` to tune the exact behavior of properties fields.
#\[derive(Props, PartialEq)\]
struct ChildProps {
#\[props(default = "client")\] name: String,
#\[props(default)\] age: Option,
#\[props(optional)\] age: Option,
}
// then to use the accompanying component
rsx!{
Child { name: "asd", }
}
#\[derive(Props, PartialEq)\]
struct ChildProps {
#\[props(default = "client")\] name: String,
#\[props(default)\] age: Option,
#\[props(optional)\] age: Option,
}
// then to use the accompanying component
rsx!{
Child { name: "asd", }
}
We've changed how DOM patching works in Dioxus-Web; now, all of the DOM manipulation code is written in TypeScript and shared between our web, desktop, and mobile runtimes.
On an M1-max, the "create-rows" operation used to take 45ms. Now, it takes a mere 17ms - 3x faster than React. We expect an upcoming optimization to bring this number as low as 3ms.
Under the hood, we have a new string interning engine to cache commonly used tags and values on the Rust < -> JS boundary, resulting in significant performance improvements.
Overall, Dioxus apps are even more snappy than before.
Before and after: 
A very welcome change, thanks AGAIN to [@mrxiaozhuox](https://github.com/mrxiaozhuox)
is support for imperatively controlling the desktop window from your Dioxus code.
A bunch of new methods were added:
* Minimize and maximize window
* Close window
* Focus window
* Enable devtools on the fly
And more!
In addition, Dioxus Desktop now autoresolves asset locations, so you can easily add local images, JS, CSS, and then bundle it into an .app without hassle.
You can now build entirely borderless desktop apps:
Thanks to the amazing work by [@mrxiaozhuox](https://github.com/mrxiaozhuox)
, our CLI tool is fixed and working better than ever. The Dioxus-CLI sports a new development server, an HTML to RSX translation engine, a `cargo fmt`\-style command, a configuration scheme, and much more.
Unlike its counterpart, `Trunk.rs`, the dioxus-cli supports running examples and tests, making it easier to test web-based projects and showcase web-focused libraries.
Working with async isn't the easiest part of Rust. To help improve things, we've upgraded async support across the board in Dioxus.
First, we upgraded the `use_future` hook. It now supports dependencies, which let you regenerate a future on the fly as its computed values change. It's never been easier to add datafetching to your Rust Web Apps:
fn RenderDog(cx: Scope, breed: String) -> Element {
let dog\_request = use\_future(&cx, (breed,), |(breed,)| async move { reqwest::get(format!("https://dog.ceo/api/breed/{}/images/random", breed)) .await .unwrap() .json::() .await });
cx.render(match dog\_request.value() { Some(Ok(url)) => rsx!{ img { url: "{url}" } }, Some(Err(url)) => rsx!{ span { "Loading dog failed" } }, None => rsx!{ "Loading dog..." } })
}
fn RenderDog(cx: Scope, breed: String) -> Element {
let dog\_request = use\_future(&cx, (breed,), |(breed,)| async move { reqwest::get(format!("https://dog.ceo/api/breed/{}/images/random", breed)) .await .unwrap() .json::() .await });
cx.render(match dog\_request.value() { Some(Ok(url)) => rsx!{ img { url: "{url}" } }, Some(Err(url)) => rsx!{ span { "Loading dog failed" } }, None => rsx!{ "Loading dog..." } })
}
Additionally, we added better support for coroutines. You can now start, stop, resume, and message with asynchronous tasks. The coroutine is automatically exposed to the rest of your app via the Context API. For the vast majority of apps, Coroutines can satisfy all of your state management needs:
fn App(cx: Scope) -> Element {
let sync\_task = use\_coroutine(&cx, |rx| async move { connect\_to\_server().await; let state = MyState::new();
while let Some(action) = rx.next().await { reduce\_state\_with\_action(action).await; } });
cx.render(rsx!{ button { onclick: move |\_| sync\_task.send(SyncAction::Username("Bob")), "Click to sync your username to the server" } })
}
fn App(cx: Scope) -> Element {
let sync\_task = use\_coroutine(&cx, |rx| async move { connect\_to\_server().await; let state = MyState::new();
while let Some(action) = rx.next().await { reduce\_state\_with\_action(action).await; } });
cx.render(rsx!{ button { onclick: move |\_| sync\_task.send(SyncAction::Username("Bob")), "Click to sync your username to the server" } })
}
We've covered the major headlining features, but there were so many more!
* A new router @autarch
* Fermi for global state management
* Translation of docs and Readme into Chinese @mrxiaozhuox
* 2.5x speedup by using JS-based DOM manipulation (3x faster than React)
* Beautiful documentation overhaul
* InlineProps macro allows definition of props within a component's function arguments
* Improved dev server, hot reloading for desktop and web apps [@mrxiaozhuox](https://github.com/mrxiaozhuox)
* Templates: desktop, web, web/hydration, Axum + SSR, and more [@mrxiaozhuox](https://github.com/mrxiaozhuox)
* Web apps ship with console \_error \_panic \_hook enabled, so you always get tracebacks
* Enhanced Hydration and server-side-rendering (recovery, validation)
* Optional fields for component properties
* Introduction of the `EventHandler` type
* Improved use \_state hook to be closer to react
* Improved use \_ref hook to be easier to use in async contexts
* New use \_coroutine hook for carefully controlling long-running async tasks
* Prevent Default attribute
* Provide Default Context allows injection of global contexts to the top of the app
* push \_future now has a spawn counterpart to be more consistent with rust
* Add gap and gap \_row attributes [@FruitieX](https://github.com/FruitieX)
* File Drag n Drop support for Desktop
* Custom handler support for desktop
* Forms now collect all their values in oninput/onsubmit
* Async tasks now are dropped when components unmount
* Right-click menus are now disabled by default
* Windows support improved across the board
* Linux support improved across the board
* Bug in Calculator example
* Improved example running support
A ton more! Dioxus is now much more stable than it was at release!
* [Styled Components macro](https://github.com/Zomatree/Revolt-Client/blob/master/src/utils.rs#14-27)
[@Zomatree](https://github.com/Zomatree)
* [Dioxus-Websocket hook](https://github.com/FruitieX/dioxus-websocket-hooks)
[@FruitieX](https://github.com/FruitieX)
* [Home automation server app](https://github.com/FruitieX/homectl)
[@FruitieX](https://github.com/FruitieX)
* [Video Recording app](https://github.com/rustkid/recorder)
* [Music streaming app](https://github.com/autarch/Crumb/tree/master/web-frontend)
[@autarch](https://github.com/autarch)
* [NixOS dependancy installation](https://gist.github.com/FruitieX/73afe3eb15da45e0e05d5c9cf5d318fc)
[@FruitieX](https://github.com/FruitieX)
* [Vercel Deploy Template](https://github.com/lucifer1004/dioxus-vercel-demo)
[@lucifer1004](https://github.com/lucifer1004)
* [Render Katex in Dioxus](https://github.com/oovm/katex-wasm)
* [Render PrismJS in Dioxus](https://github.com/oovm/prism-wasm)
* [Compile-time correct TailwindCSS](https://github.com/houseabsolute/tailwindcss-to-rust)
* [Autogenerate tailwind CSS](https://github.com/oovm/tailwind-rs)
* [Heroicons library](https://github.com/houseabsolute/dioxus-heroicons)
* [RSX -> HTML translator app](https://dioxus-convert.netlify.app/)
* [Toast Support](https://github.com/mrxiaozhuox/dioxus-toast)
* New Examples: forms, routers, linking, tui, and more!
Dioxus is still under rapid, active development. We'd love for you to get involved! For the next release, we're looking to add:
* Native WGPU renderer support
* A query library like react-query
* Multiwindow desktop app support
* Full LiveView integrations for Axum, Warp, and Actix
* A builder pattern for elements (no need for rsx!)
* Autoformatting of rsx! code (like cargo fmt)
* Improvements to the VSCode Extension
If you're interested in building an app with Dioxus, make sure to check us out on:
* [Github](https://github.com/dioxusLabs/dioxus)
* [Reddit](http://reddit.com/r/dioxus/)
* [Discord](https://discord.gg/XgGxMSkvUM)
* [Twitter](https://twitter.com/dioxuslabs)
On this page
------------
* [A New Renderer: Your terminal!](https://dioxuslabs.com/blog/release-020/#a-new-renderer-your-terminal)
* [New Router](https://dioxuslabs.com/blog/release-020/#new-router)
* [Fermi for Global State Management](https://dioxuslabs.com/blog/release-020/#fermi-for-global-state-management)
* [Inline Props Macro](https://dioxuslabs.com/blog/release-020/#inline-props-macro)
* [Props optional fields](https://dioxuslabs.com/blog/release-020/#props-optional-fields)
* [Dioxus Web Speed Boost](https://dioxuslabs.com/blog/release-020/#dioxus-web-speed-boost)
* [Dioxus Desktop Window Context](https://dioxuslabs.com/blog/release-020/#dioxus-desktop-window-context)
* [CLI Tool](https://dioxuslabs.com/blog/release-020/#cli-tool)
* [Async Improvements](https://dioxuslabs.com/blog/release-020/#async-improvements)
* [All New Features](https://dioxuslabs.com/blog/release-020/#all-new-features)
* [Fixes](https://dioxuslabs.com/blog/release-020/#fixes)
* [Community Additions](https://dioxuslabs.com/blog/release-020/#community-additions)
* [Looking Forward](https://dioxuslabs.com/blog/release-020/#looking-forward)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
[Back to blog](https://dioxuslabs.com/blog/)
Dioxus 0.3
==========
February 8, 2023 - Jonathan Kelley
### The next big release of Dioxus is here! Templates, autoformatting, multiwindow support, and more!
If youâre new here: Dioxus (dyeâąoxâąus) is a library for building React-like user interface in Rust. Dioxus supports a ton of targets: web, desktop, mobile, TUI, and more. On the web it renders via the DOM and on desktop and mobile you can choose between the WebView DOM, WGPU, or Skia.
Dioxus 0.3 is bringing a _lot_ of fantastic new features:
* Massive performance improvements
* Hot reloading for web and desktop
* Autoformatting for RSX via `dioxus fmt`
* New LiveView renderer
* Input widgets for TUI
* Lua plugin system for CLI and overhaul of CLI
* Multi window desktop apps and direct access to Tao/Wry
* General improvements to RSX (if chains, for loops, boolean attributes, any values)
* Rusty event types with support for complex techniques like file uploading
* Skia renderer and WGPU renderer
* Chinese and Portuguese translations
* A new landing page
This release represents an absolutely massive jump forward for the Dioxus ecosystem. We hope to ship future features more quickly into stable now that many of the desired breaking changes have been incorporated into the core library.
Weâve made huge changes underpinning the architecture of Dioxus. The significance of these changes is hard to describe in this simple release document, but we did write a blog post about it [here](https://dioxuslabs.com/blog/templates-diffing/)
. Now, Dioxus performance is on par with of SolidJS.
Additionally, weâve reworked how desktop apps stream edits from the native thread into the webview, greatly improving performance.
Dioxus can now update how your app looks without recompiling the underlying Rust code. For developers who choose to write their user interfaces with the RSX macro, the Dioxus development server will automatically update the appearance of a running app whenever the macro body is modified.
Weâve found hot reloading to significantly speed up development cycles, making it faster than ever to iterate your app.
Note that hot reloading works by interpreting the body of RSX macro calls. If the hot reloading engine detects a modification unrelated to RSX, then it will force a full refresh of the app.
Another widely requested feature - autoformatting - is now built into the Dioxus CLI and VSCode Extension. Using the same interpreter engine in hot reloading, your code can now be formatted automatically. This saves a ton of time and ensures consistency between code commits.
Autoformatting can be used via the VSCode Extension which will autoformat as you code.
Or directly for use in CI or non-vscode editors with the `dioxus fmt` command.
Autoformatting respects some simple rustfmt features but is still in its early stages. If you find any quirks or disagree with the formatting style, feel free to file an issue.
Dioxus 0.3 marks the first official release of dedicated tooling for LiveView. LiveView is a new web-app development paradigm that combines the simplicity of server-side rendering with the rich interactivity of the single-page-application.
Because thereâs no frontend build step or need for a dedicated backend, writing LiveView apps is easy. LiveView lets you freely mix database access into your frontend code, saving the hassle of a dedicated backend. LiveView is the fastest way to build a complete app in Rust.
async fn main() {
let router \= Router::new()
.route("/", get(move || dioxus\_liveview::body(addr))
.route("/app", get(move |ws| dioxus\_liveview::render(ws));
axum::Server::bind("127.0.0.1".parse().unwrap())
.serve(router.into\_make\_service()) .await;
}
fn app(cx: Scope) -> Element {
let posts \= use\_db\_query(cx, RECENT\_POSTS);
render! {
for post in posts {
Post { key: "{post.id}", data: post }
}
}
}
async fn main() {
let router \= Router::new()
.route("/", get(move || dioxus\_liveview::body(addr))
.route("/app", get(move |ws| dioxus\_liveview::render(ws));
axum::Server::bind("127.0.0.1".parse().unwrap())
.serve(router.into\_make\_service()) .await;
}
fn app(cx: Scope) -> Element {
let posts \= use\_db\_query(cx, RECENT\_POSTS);
render! {
for post in posts {
Post { key: "{post.id}", data: post }
}
}
}
Up to this point, Dioxus rendered into the terminal using just static elements. Now, with the release of Dioxus 0.3, weâre shipping a collection of input widgets for common utilities like buttons, sliders, text inputs, checkboxes, and more. These same widgets provide a basis of functionality for the native renderers we mention below.
The Dioxus VirtualDom and tao/wry event loop now share the same scheduler, allowing full control of the window and event loop from within your desktop and mobile app. This unlocks everything a typical tauri app might have access to, allowing Dioxus to share more code with the rest of the Tauri ecosystem.
One big advantage of this is the ability to open and close multiple windows from within your Dioxus app. With access to the event loop, you can even get a raw window handle, allowing alternative rendering engines like OpenGL or WGPU.
Weâve expanded what can be considered a component. Lowercase components are now accepted in the rsx macro provided that they either
* Use the path syntax (ie `module::component`)
* Container an underscore character
This is a similar restriction as found in other frameworks. Note that you still cannot define a one-word component without referencing it via path syntax. Weâre hoping to resolve this soon, but itâs not a very easy problem to solve.
header {} â
module::header {} â
my\_header {} â
header {} â
module::header {} â
my\_header {} â
Weâve made the rsx macro a lot more flexible with some new features to simplify lists and if statements.
Before, if you wanted to render a list, youâd need to create an iterator and map it to rsx. Now, we apply an automatic transformation of any `for` loop into an iterator. This should make lists more readable!
for dog in doggos {
div { key: "{dog.id}", "Dog: {dog.name}" }
}
for dog in doggos {
div { key: "{dog.id}", "Dog: {dog.name}" }
}
Dioxus 0.3 delivers on another commonly requested feature: native (non-web browser) rendering. This new update brings a very young, very unstable, but surprisingly capable WGPU renderer. This renderer is the culmination of many months of work: collaboration with the Bevy team to revive Taffy (flexbox), integration of the new Vello renderer, and research into highly efficient incremental screen patching.
The renderer is very raw but already capable of rendering HTML, CSS, and responding to user input. Weâre actively working on adding accessibility support using the work done by EGUI as inspiration.
While not exactly a Dioxus Labs project, we wanted to make sure to call out the new Freya editor for Dioxus which uses Skia instead of Vello. Freya takes a different approach from Dioxus-Native in that instead of adhering to HTML and CSS, it sets its own styling and layout strategy. This has a different learning curve - you canât take your CSS knowledge with you, but you get a styling system better designed for the job.
Freya is already an amazing piece of technology and has support for things like camera input and infinite canvas.
A common complaint with Dioxusâ event system is its reliance on imperfect web standards. For Dioxus 0.3, we overhauled the public API for events to be more âRusty.â Instead of shipping our own types like keyboard keys, we now provide an API comfortable for the everyday Rustacean. You can now do mouse position math with `euclid`, match on keys native to `keyboard-types`, and get helpful docs with cargo-doc. Dioxus also now provides better support for file upload and drag-and-drop operations by downcasting the native event type if it exists.
Note that the old JS-like API is still available (but deprecated) and will be phased out in a future release of Dioxus.
The CLI has been overhauled with a ton of new features and improved ergonomics. One major improvement to the CLI is the addition of a Lua-based plugin system. In the future we to expand the plugin system to any WASI-compatible modules but have simply opted for Lua support in the short term while we figure out the API.
The community seems to really enjoy Dioxus! And they want their friends to know about Dioxus, too! But, our guides have not been available in every language that developers want. In this release, weâre adding two new languages to our guide:
* Chinese provided by [`@mrxiaozhuox`](https://github.com/mrxiaozhuox)
* Portuguese provided by [`@whoeverdidthis`](https://github.com/whoeverdidthis)
If you havenât already noticed, our homepage is cleaner, more direct, and a bit more eye-catching. Check it out if you havenât!
As part of our translation and Rust-ification work, [`@renis`](https://github.com/renis)
has overhauled our guide to be more familiar for Rust developers. This skips some of the boilerplate (IE install Rust) and gets straight into the action of building Dioxus apps.
* Styled components
* Opinionated starter pack
* Icon pack
* Caesar cyhper
* LED Strip controller
* GTK Renderer
* Formalize
* Story diagrammer
* Table crate
* Dioxus Helmet
* Skia renderer
* Use fetch
* Bevy Integration
On this page
------------
* [Hot Reloading](https://dioxuslabs.com/blog/release-030/#hot-reloading)
* [Autoformatting](https://dioxuslabs.com/blog/release-030/#autoformatting)
* [LiveView and LiveComponents](https://dioxuslabs.com/blog/release-030/#liveview-and-livecomponents)
* [TUI Input Widgets](https://dioxuslabs.com/blog/release-030/#tui-input-widgets)
* [Multi-window Desktop Apps](https://dioxuslabs.com/blog/release-030/#multi-window-desktop-apps)
* [Lowercase components](https://dioxuslabs.com/blog/release-030/#lowercase-components)
* [For Loops, If Chains, and more flexible RSX](https://dioxuslabs.com/blog/release-030/#for-loops-if-chains-and-more-flexible-rsx)
* [Preliminary WGPU renderer](https://dioxuslabs.com/blog/release-030/#preliminary-wgpu-renderer)
* [Skia Renderer](https://dioxuslabs.com/blog/release-030/#skia-renderer)
* [Completing support for cross-platform events](https://dioxuslabs.com/blog/release-030/#completing-support-for-cross-platform-events)
* [Lua Plugin System for CLI](https://dioxuslabs.com/blog/release-030/#lua-plugin-system-for-cli)
* [Translations](https://dioxuslabs.com/blog/release-030/#translations)
* [A new landing page and better docs](https://dioxuslabs.com/blog/release-030/#a-new-landing-page-and-better-docs)
* [Community Projects](https://dioxuslabs.com/blog/release-030/#community-projects)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
[Back to blog](https://dioxuslabs.com/blog/)
Dioxus 0.4
==========
August 1, 2023 - Jonathan Kelley
### Server Functions, Suspense, Enum Router, Overhauled Docs, Bundler, Android Support, and more!
Welcome back, get your snacks, Dioxus 0.4 just dropped.
If youâre new here: Dioxus (dyeâąoxâąus) is a library for building React-like user interface in Rust. Dioxus supports a ton of targets: web, desktop, mobile, TUI, and more.
Dioxus 0.4 is adding support for the next frontier: the server backend.
You can now write your entire fullstack web app in one file.
The gist of this release:
* Server functions
* Server-compatible suspense
* Overhauled (and beautiful!) interactive documentation
* Overhauled and supercharged new router
* First-party support for Android with new getting started guides
* Backend-agnostic hooks for common app uses cases
* Desktop Hot Reloading
* Tauri-bundle built into the Dioxus CLI
* Polish, bug fixes, stability, testing, and more!
Before we dive right into the bulk of this release, we want to make sure everyone knows that Dioxus Labs now has weekly office hours, every Friday at 9am PST.
These are held on the community Discord - with an invite here:
[Join the Dioxus Labs Discord Server!](https://discord.gg/XgGxMSkvUM)
In the office hours you can get help with your app, learn how to contribute, get feedback on code, and [help shape the roadmap.](https://www.notion.so/Dioxus-Labs-Public-Roadmap-771939f47d13423abe2a2195b5617555?pvs=21)
We hope to see you there!
These days, every cool UI library has some sort of backend framework to do server stuff. This could be interacting with a database, uploading files, working with websockets, you name it. With Dioxus 0.4, weâre adding our first backend solution: Server Functions.
Server Functions are functions annotated with the `server` procedural macro that generates an RPC client and server for your app. With a single function declaration, you get both the server endpoint _and_ the client required to interact with the endpoint.
For example, take this simple Server Function. Weâre using the awesome [turbosql](https://github.com/trevyn/turbosql)
crate by [trevyn](https://github.com/trevyn)
to interact with a sqlite database to load a personâs username.
#\[server\]
async fn get\_username() -> Result {
// Using turbosql to extract some data from the DB
Ok(select!(String "SELECT name FROM person")?)
}
#\[server\]
async fn get\_username() -> Result {
// Using turbosql to extract some data from the DB
Ok(select!(String "SELECT name FROM person")?)
}
The `server` macro will generate a different helper function depending on the configuration flags of your project. If you build your project for the backend ( `server`), then your endpoint will be automatically injected into any axum/salvo/warp router created with `dioxus_fullstack`. However, if you build your project with any other feature flag, like, `client`, then the macro generates the _call_ to the server.
This approach makes it easy to incrementally add new backend functionality to your app. Of course, this has some disadvantages - the backend is rather tightly coupled to the frontend - but for most apps, Server Functions will be a huge productivity win.
Server Functions are agnostic to the backend framework youâre using, and support a number of generic operations common across axum, warp, and salvo. For instance, you can extract any header from the request, guarding on things like valid headers and cookies:
use axum::{TypedHeader, headers::UserAgent};
use dioxus\_fullstack::extract;
#\[server\]
fn log\_user\_agent() -> ServerFnResult {
let user\_agent: TypedHeader \= extract().await?;
Ok(())
}
use axum::{TypedHeader, headers::UserAgent};
use dioxus\_fullstack::extract;
#\[server\]
fn log\_user\_agent() -> ServerFnResult {
let user\_agent: TypedHeader \= extract().await?;
Ok(())
}
You can attach middleware either at the server level or individually on server functions. The new fullstack utilities work seamlessly with [Tower](https://docs.rs/tower/latest/tower/index.html)
, so any server function can be annotated with a middleware.
// Add a timeout middleware to the server function that will return
// an error if the function takes longer than 1 second to execute
use std::time::Duration;
use tower\_http::timeout::TimeoutLayer;
use tokio::time::sleep;
#\[server\]
#\[middleware(TimeoutLayer::new(Duration::from\_secs(1)))\]
pub async fn timeout() -> ServerFnResult {
sleep(Duration::from\_secs(2)).await;
Ok(())
}
// Add a timeout middleware to the server function that will return
// an error if the function takes longer than 1 second to execute
use std::time::Duration;
use tower\_http::timeout::TimeoutLayer;
use tokio::time::sleep;
#\[server\]
#\[middleware(TimeoutLayer::new(Duration::from\_secs(1)))\]
pub async fn timeout() -> ServerFnResult {
sleep(Duration::from\_secs(2)).await;
Ok(())
}
Combining all these concepts together, you can quickly add features like Authentication to your fullstack app. Weâve put together a [simple axum-auth example for you to get started](https://github.com/dioxuslabs/dioxus/blob/main/packages/fullstack/examples/axum-auth/src/main.rs)
.
Our goal with Server Functions is to lay the foundation for our final vision of Dioxus: a fullstack, crossplatform, fully typed, and lightning fast toolkit for building, deploying, monitoring, and scaling any app you can dream of. With one ecosystem, you can quickly build complete apps that run on desktop, mobile, web with a type-safe backend to boot.
One feature that has been missing in Dioxus since its release is the ability to wait for futures to complete before generating the final server-side-rendered HTML. Before, the expectation was that youâd load any data _ahead of time,_ and pass in the data via Root Props. We quickly learned this caused issues with scalability: you might not want to fetch every piece of props depending on the route.
To solve this, weâre adding future-compatible `Suspense` - now integrated with Dioxus Fullstack and Server Functions. Suspense is freely available to components via the `cx.suspend()` method. Calling `suspend` will tell Dioxus that this particular component is blocking the completion of the final render due to a pending future. The most basic usage of Suspense is pausing rendering until a data fetch has been completed:
fn Username(cx: Scope) -> Element {
let username \= use\_future(cx, (), |\_| get\_username());
// Try to extract the current value of the future
let Some(username) \= username.value() else {
// Early return and mark this component as suspended
return cx.suspend();
}
render! { "Username: {username}")
}
fn Username(cx: Scope) -> Element {
let username \= use\_future(cx, (), |\_| get\_username());
// Try to extract the current value of the future
let Some(username) \= username.value() else {
// Early return and mark this component as suspended
return cx.suspend();
}
render! { "Username: {username}")
}
Now, we can do datafetching _inside_ components, greatly simplifying our project structure. With the new `use_server_future` hook, we can persist the result of the fetch between server render and client render, allowing hydration to work seamlessly.
fn Dashboard(cx: Scope) -> Element {
// use\_server\_future will persist the result of this call during SSR
let ip \= use\_server\_future(cx, (), |\_| get\_server\_ip())?;
render!{ "The edge node is {ip}" }
}
// When used on the server, this is just a simple function call
#\[server\]
async fn get\_server\_ip() -> Result {
Ok(reqwest::get("https://httpbin.org/ip").await?.text().await?)
}
fn Dashboard(cx: Scope) -> Element {
// use\_server\_future will persist the result of this call during SSR
let ip \= use\_server\_future(cx, (), |\_| get\_server\_ip())?;
render!{ "The edge node is {ip}" }
}
// When used on the server, this is just a simple function call
#\[server\]
async fn get\_server\_ip() -> Result {
Ok(reqwest::get("https://httpbin.org/ip").await?.text().await?)
}
With inline datafetching, we can greatly simplify the amount of work required to build fullstack apps. In this diagram of a Dioxus app with suspense, we can see that suspended components are marked yellow. When their futures completed, Dioxus will continue rendering them, cascading into their children until all futures have been resolved.
Adopting suspense and fullstack should be easy. Now, when you go to render the app, you can simply call `wait_for_suspense()` before pre-rendering the markup:
let mut app \= VirtualDom::new(app\_fn);
// Start the futures
app.rebuild();
// Wait for suspended futures to complete
app.wait\_for\_suspense();
// Now render the app out
dioxus\_ssr::prerender(&app);
let mut app \= VirtualDom::new(app\_fn);
// Start the futures
app.rebuild();
// Wait for suspended futures to complete
app.wait\_for\_suspense();
// Now render the app out
dioxus\_ssr::prerender(&app);
Note that this is not 100% equivalent to Reactâs suspense as itâs not currently possible to render loading states or error boundaries. These features are currently experimental and will be stabilized during the 0.4 release cycle.
Since the initial release of Dioxus, weâve had a very simple App Router, inspired by the older versions of React Router. Most UI toolkits these days provide a Router object that interacts with the browserâs router, and to date, Dioxusâ router has been pretty simple.
In the beginning we opted for simplicity and flexibility. The old router let you create route trees with just components. This router was easy to add new routes to and easy to compose.
pub fn app(cx: Scope) -> Element {
render! { Router {
Nav {}
Route { to: "/", Homepage {} }
Route { to: "/awesome", Awesome {}}
Route { to: "/learn", Learn {} }
Route { to: "/tutorials/:id", Tutorial {} }
Route { to: "/blog", BlogList {} }
Route { to: "/blog/going-fulltime", GoingFulltime {} }
Route { to: "/blog/release-030", Release03 {} }
Route { to: "", Err404 {} }
} Footer {}
}
}
pub fn app(cx: Scope) -> Element {
render! { Router {
Nav {}
Route { to: "/", Homepage {} }
Route { to: "/awesome", Awesome {}}
Route { to: "/learn", Learn {} }
Route { to: "/tutorials/:id", Tutorial {} }
Route { to: "/blog", BlogList {} }
Route { to: "/blog/going-fulltime", GoingFulltime {} }
Route { to: "/blog/release-030", Release03 {} }
Route { to: "", Err404 {} }
} Footer {}
}
}
However, after thinking about the new features we wanted to add to Dioxus, we realized that this router design wouldnât cut it in the future. We were lacking many crucial features like nested routes and type-safe URLs.
So, we designed a new router built around the Rust `enum`. Now, you assemble your appâs route by deriving the `Routable` trait for a given enum. Routes are simply enum variants! Even better, everything is 100% typesafe. No longer can you craft invalid URLs - saving your apps from a whole host of problems.
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize, Debug)\]
enum Route {
#\[route("/")\]
#\[redirect("/platforms", || Route::Homepage {})\]
Homepage {},
#\[route("/awesome")\]
Awesome {},
#\[route("/learn")\]
Learn {},
#\[route("/tutorials/:id")\]
Tutorial { id: usize },
#\[route("/blog")\]
BlogList {},
#\[route("/blog/:post")\]
BlogPost { post: String },
#\[route("/:..segments")\]
Err404 { segments: Vec },
}
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize, Debug)\]
enum Route {
#\[route("/")\]
#\[redirect("/platforms", || Route::Homepage {})\]
Homepage {},
#\[route("/awesome")\]
Awesome {},
#\[route("/learn")\]
Learn {},
#\[route("/tutorials/:id")\]
Tutorial { id: usize },
#\[route("/blog")\]
BlogList {},
#\[route("/blog/:post")\]
BlogPost { post: String },
#\[route("/:..segments")\]
Err404 { segments: Vec },
}
To render the new router, pass in your appâs Route enum as the generic type in the Router, and Dioxus will render the right component, given that the enum variant.
fn app(cx: Scope) -> Element {
render! { Router:: {} }
}
fn app(cx: Scope) -> Element {
render! { Router:: {} }
}
The `#[derive(Routable)]` will automatically generate the `render` function for your Router. The Router will render the right route given that a similarly named component is in scope. You can override this yourself, or just stick with the default. The simplest app using the new router would look something like this:
// 1. Declare our app's routes
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[route("/")\]
Homepage {},
}
// 2. Make sure we have a component in scope that matches the enum variant
fn Homepage(cx: Scope) -> Element {
render! { "Welcome home!" }
}
// 3. Now render our app, using the Router and Route
fn app(cx: Scope) -> Element {
render! { Router:: {} }
}
// 1. Declare our app's routes
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[route("/")\]
Homepage {},
}
// 2. Make sure we have a component in scope that matches the enum variant
fn Homepage(cx: Scope) -> Element {
render! { "Welcome home!" }
}
// 3. Now render our app, using the Router and Route
fn app(cx: Scope) -> Element {
render! { Router:: {} }
}
Passing in attributes from the route itself is easy too. The `Routable` macro will accept any fields that implement `FromStr`, so you can easily add attributes, queries, and named parameters to your app.
// Declare our app's routes
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[route("/blog/:post")\]
BlogPost { post: String },
}
#\[component\]
fn BlogPost(cx: Scope, post: String) {
render!{ "Currently viewing: {post}" }
}
// Declare our app's routes
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[route("/blog/:post")\]
BlogPost { post: String },
}
#\[component\]
fn BlogPost(cx: Scope, post: String) {
render!{ "Currently viewing: {post}" }
}
Likewise, you can catch 404s using the trailing segments syntax.
// Declare our app's routes
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[route("/:..segments")\]
Err404 { segments: Vec },
}
// Declare our app's routes
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[route("/:..segments")\]
Err404 { segments: Vec },
}
Another exciting feature is layouts. Weâre borrowing this concept from popular frameworks like Remix and Next.JS. Layouts make it easy to wrap Route components together in a shared set of components. A common use case is wrapping your app in a Header, Footer, or Navbar. Without layouts, youâd have a lot of code duplication
fn Home(cx: Scope) -> Element {
render! {
Header {}
Navbar {}
div { "actual home content" }
Footer {}
}
}
fn Blog(cx: Scope) -> Element {
render! {
Header {}
Navbar {}
div { "actual blog content" }
Footer {}
}
}
fn Home(cx: Scope) -> Element {
render! {
Header {}
Navbar {}
div { "actual home content" }
Footer {}
}
}
fn Blog(cx: Scope) -> Element {
render! {
Header {}
Navbar {}
div { "actual blog content" }
Footer {}
}
}
Now, with layouts, you can declare your layout in the Route enum itself.
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[layout(HeaderFooterNav)\]
#\[route("/")\]
Home {},
#\[route("/blog/")\]
Blog {},
}
// Wrap the rendered content of the Router with a header, navbar, and footer
fn HeaderFooterNav(cx: Scope) -> Element {
render! {
Header {}
Navbar {}
Outlet:: {}
Footer {}
}
}
#\[derive(Clone, Routable, PartialEq, Eq, Serialize, Deserialize)\]
enum Route {
#\[layout(HeaderFooterNav)\]
#\[route("/")\]
Home {},
#\[route("/blog/")\]
Blog {},
}
// Wrap the rendered content of the Router with a header, navbar, and footer
fn HeaderFooterNav(cx: Scope) -> Element {
render! {
Header {}
Navbar {}
Outlet:: {}
Footer {}
}
}
The new router was an absolutely massive amount of work, spearheaded by @TeFiLeDo, improved by @ealmloff, and made possible thanks to community members like @stephenandary and @attilio-oliva.
Itâs about time we revamped our documentation. When we launched, the original docs were pretty good, at least for a 0.1 crate. Now, we have over 16 crates in the main repo with another half dozen scattered around the github organization. New users deserve a better introduction experience.
To start, we revamped our landing page. Short, sweet, to the point.
At the top of the page, youâll see a new search bar. You can search for anything in our docs with just a `ctrl+/` . This new search functionality uses a [new search crate we designed and built](https://github.com/dioxusLabs/dioxus-search)
. `Dioxus-search` is fully crossplatform and ready to use in your next Dioxus app.
Selecting any of the search results will take you straight to the docs page without bouncing out to an external mdbook.
Weâve added a bunch more content to the docs, including new pages like:
* Building a hackernews clone from scratch
* Setup guides for mobile
* Suggestions for useful crates
* How to bundle your app
* Working with server functions
The best part? The docs are interactive! Examples like the `hello-world` and even the `hackernews` clone come to life from within the docs page.
We also moved the `awesome` dioxus page from GitHub to the docsite, so you can explore the various crates that other developers have submitted as âawesome.â
The new docs leverage many of the amazing new features from the router, including:
To date, Dioxus has provided first-party support for mobile via iOS, but our Android support has been rather spotty and untested. In this release, we finally added iOS and Android testing to our suite of continuous integration. To round off mobile support, weâve added a [mobile-specific getting started guide](https://dioxuslabs.com/learn/0.4/getting_started/mobile)
with a walkthrough on setting up platform-specific dependencies, handling basic cross-compilation, and booting up a mobile simulator. Weâve also fixed some bugs in upstream libraries like Tauriâs Tao which gives Dioxus its window-creation capabilities.
iOS Demo:
Android Demo:
Another great contribution from the community: Dioxus desktop now provides functionality for managing the âcloseâ behavior of windows in your app. We support three modes now:
* Closing the last window kills the app
* Closing the last window doesnât kill the app
* Closing the last window simply hides the window (so the window can be cmd-tabbed back)
The use\_eval hook allows you to run snippets of Javascript in your Dioxus application when needed. @doge has made some improvements that make this hook has significantly more powerful. The new version of the hook is compatible between the desktop, web, and Liveview renderers. It also allows you to send messages to and from Javascript asynchronously. This makes it possible to listen for Javascript events that Dioxus doesnât officially support like the intersection observer API.
use dioxus::prelude::\*;
fn main() {
dioxus\_desktop::launch(app);
}
fn app(cx: Scope) -> Element {
let eval \= use\_eval(cx);
let future \= use\_future(cx, (), |\_| {
to\_owned!\[eval\]; async move {
// Eval some javascript
let eval \= eval(
r#"dioxus.send("Hi from JS!");
let msg = await dioxus.recv(); console.log(msg); return "hello world";"#,
) .unwrap();
// Send messages into the running javascript
eval.send("Hi from Rust!".into()).unwrap();
// Receive messages from the javascript
let res \= eval.recv().await.unwrap();
// Wait for it to complete
println!("{:?}", eval.await);
res } });
render!{ "{future.value():?}" }
}
use dioxus::prelude::\*;
fn main() {
dioxus\_desktop::launch(app);
}
fn app(cx: Scope) -> Element {
let eval \= use\_eval(cx);
let future \= use\_future(cx, (), |\_| {
to\_owned!\[eval\]; async move {
// Eval some javascript
let eval \= eval(
r#"dioxus.send("Hi from JS!");
let msg = await dioxus.recv(); console.log(msg); return "hello world";"#,
) .unwrap();
// Send messages into the running javascript
eval.send("Hi from Rust!".into()).unwrap();
// Receive messages from the javascript
let res \= eval.recv().await.unwrap();
// Wait for it to complete
println!("{:?}", eval.await);
res } });
render!{ "{future.value():?}" }
}
This release also introduces a new onmounted event that provides access to elements after they are created in a cross platform way. The onmounted event makes it possible to:
* Scroll to an element
* Read the size of an element
* Focus an element
* Get the platform specific element
use dioxus::prelude::\*;
fn main() {
dioxus\_desktop::launch(app);
}
fn app(cx: Scope) -> Element {
let header\_element \= use\_state(cx, || None);
cx.render(rsx!( div { h1 { onmounted: move |cx| {
header\_element.set(Some(cx.inner().clone()));
}, "Scroll to top example"
}
for i in 0..40 {
div { "Item {i}" }
}
button { onclick: move |\_| {
if let Some(header) \= header\_element.as\_ref() { header.scroll\_to(ScrollBehavior::Smooth);
} }, "Scroll to top"
} } ))
}
use dioxus::prelude::\*;
fn main() {
dioxus\_desktop::launch(app);
}
fn app(cx: Scope) -> Element {
let header\_element \= use\_state(cx, || None);
cx.render(rsx!( div { h1 { onmounted: move |cx| {
header\_element.set(Some(cx.inner().clone()));
}, "Scroll to top example"
}
for i in 0..40 {
div { "Item {i}" } }
button { onclick: move |\_| {
if let Some(header) \= header\_element.as\_ref() { header.scroll\_to(ScrollBehavior::Smooth);
} }, "Scroll to top"
} } ))
}
We made a small tweak to the CLI this release to rename the CLI from `dioxus` to `dx`. This is a tiny change but has a few benefits:
* Itâs faster to type
* It emphasizes the _developer experience_ of Dioxus
* It keeps our tooling agnostic to other projects that might want to take advantage of features like hotreloading, autoformatting, wasm-pack, tailwind integration, plugins, and more.
To install the new CLI, use the same old instructions:
cargo install dioxus\-cli \--force
cargo install dioxus\-cli \--force
Yet another small tweak the CLI: you can now use `dx serve` on desktop apps with hot reloading enabled! Using the same hot reloading engine that powers web, `dx serve` can now modify your currently-running desktop without causing a full rebuild. In the event that we canât hot reload a particular change, then `dx serve` will shutdown the app and restart it with the new changes applied.
So far, the CLI has supported useful commands like `dx fmt` , `dx build` , `dx serve` . Until date, we havenât provided a command to build a final distributable image of your app. In 0.4, weâre incorporating cargo-bundle support into the Dioxus CLI. Now, from the Dioxus CLI, you can bundle your app using the same configuration options as the Tauri bundler, making it easy to migrate existing projects over. `dx bundle` supports bundling apps for macOS, iOS, Windows, and Linux (.deb, .rpm).
This is a great place for new contributors to help flesh out the ecosystem!
The Dioxus CLI has a new helper command: `dx check`. Thanks to the work from community member @eventualbuddha, `dx check` will now identify and help mitigate issues like hooks being called inside conditionals and loops.
These lints make it easier for newcomers to Dioxus to get started, especially if theyâre not super familiar with React.
As part of improving stability and fixing bugs, weâve made some improvements to the VSCode Extension.
* We fixed a bug with activation events where the extension wouldnât activate until one of the commands were manually fired
* We fixed a handful of autoformatting bugs around event handlers
* Weâve moved the code for the extension out of the CLI and into a small WebAssembly binary so you donât need the CLI installed and version matched
The extension is a great place for new contributors to dive into the Dioxus codebase!
* Several SSR and Hydration bugs were fixed including escaping text, and
* We have improved testing around Dioxus. We have added end to end tests for each platform and fuzzing tests for core libraries.
* Fix the provide context docs
* Fix trait bounds on generics with component
* Fix hot reloading in a workspace
* Fix anchor link for block-level elements
* Fix Guide link in README
* Fix new Clippy lints
* Fix event bubbling within a single template
* Fix panic when waking future on shutdown
* Fix style attributes in SSR
* Fix more complex workspaces with hot reloading
* Fix non-bubbling listener hydration
* Hotfix wry segfaulting
* Fix dangerous\_inner\_html with SSR
* Fix Linux Wry dependencies
* Fix native core dependencies in a different direction than the pass direction
* Fix raw attribute values in SSR
* fix: Update logos and custom assets example
* Fix non-ascii string decoding
* fix rng in svg dice example
* Fix clippy in the generic component example
* fix: change crossterm poll timeout to 10ms from 1s
* Fix HTML to RSX conversions example
* Fix LiveView Tokio features
* Fix non-bubbling event propagation
* Fix selected and checked with boolean attributes
* Fix form events with select multiple
* Fix click and input events on desktop
* Fix the link to tui widgets in the guide
* Fix duplicate example and test names
* fix router book link
* Fix web events starting on a text node
* Fix links in Liveview
* Fix URL encoded desktop assets
* Fix ssr guide examples
* Fix hot reloading with namespaces
* Add initial\_value attribute & fix static special attribute handling
* Fix liveview interpreter JS
* Fix autoformatting raw strings
* Fix panic when events trigger on placeholders
* fix: Remove dbg that was causing TUI rendering problems
* Fix restarting MacOs hot reloading after a forced exit
* Fix `cargo doc`
* Fix: Remove play button from guide example
* Fix: bump liveview salvo version to 0.44.1. (#1124)
* fix: Remove conflicting rustfmt config for cli
* fix(docs): Fix dioxus-hooks crate description
* Fix CLI testing issue
* Fix boolean attributes with raw boolean values
* fix: Properly drop UseFuture's values to avoid leaking memory
* Fix the onload event
* fix: Fix stop\_propagation example
* Fix playwrite tests
* Fix playwright fullstack clippy
* fix: readme awesome link
* fix: Remove duplicated doc links and improved some descriptions
* Fix the issue of duplicate unique ID for atoms using `newtype`.
* fix(cli): improve error message for invalid config
* fix: Update use\_ref docs
* Fix playwright (again) and move the playwright stuff into the playwright directory
* Fix: dont use bumpslab anymore, just box scopestates
* Fix race condition in use\_future
* Fix use\_future always spawning a new task and never updating
* Fix route prerendering
* fix: Use correct cfg for file\_watcher feature in dioxus-hot-reload
* docs(clean): fix copy-paste docs from `build`
* fix: Update use\_coroutine example
* fix(playwright): remove unnecessary `await`s
* Fix all broken examples
* Fix root component suspense
On this page
------------
* [Server Functions](https://dioxuslabs.com/blog/release-040/#server-functions)
* [Suspense](https://dioxuslabs.com/blog/release-040/#suspense)
* [Enum Router](https://dioxuslabs.com/blog/release-040/#enum-router)
* [New and beautiful interactive docs](https://dioxuslabs.com/blog/release-040/#new-and-beautiful-interactive-docs)
* [Android Support, iOS fixes, Getting Started Guide for Mobile](https://dioxuslabs.com/blog/release-040/#android-support-ios-fixes-getting-started-guide-for-mobile)
* [Window-Close Behavior](https://dioxuslabs.com/blog/release-040/#window-close-behavior)
* [Bidirectional Eval](https://dioxuslabs.com/blog/release-040/#bidirectional-eval)
* [New onmount event](https://dioxuslabs.com/blog/release-040/#new-onmount-event)
* [Renaming dioxus-cli to dx](https://dioxuslabs.com/blog/release-040/#renaming-dioxus-cli-to-dx)
* [Hot Reloading for Desktop](https://dioxuslabs.com/blog/release-040/#hot-reloading-for-desktop)
* [Dioxus-Bundle](https://dioxuslabs.com/blog/release-040/#dioxus-bundle)
* [Dioxus-Check](https://dioxuslabs.com/blog/release-040/#dioxus-check)
* [VSCode Extension Updates](https://dioxuslabs.com/blog/release-040/#vscode-extension-updates)
* [General Fixes](https://dioxuslabs.com/blog/release-040/#general-fixes)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
[Back to blog](https://dioxuslabs.com/blog/)
Dioxus 0.5
==========
March 21, 2024 - Jonathan Kelley
### A signal rewrite, zero unsafe, no lifetimes, unified launch, and more!
Here at Dioxus Labs, we have an unofficial rule: only one rewrite per year.
Our last rewrite brought some amazing features: templates, hot reloading, and insane performance. However, donât be mistaken, rewrites are scary, time consuming, and a huge gamble. We started this new rewrite on January 1st of 2024, completed it by Feburary 1st, and then spent another month and a half writing tests, squashing bugs, and polishing documentation. Rewrites are absolutely not for the faint of heart.
If youâre new here, Dioxus (dyeâąoxâąus) is a library for building GUIs in Rust. Originally, I built Dioxus as a rewrite of Yew with the intention of supporting proper server-side-rendering. Eventually, Dioxus got popular, we got some amazing sponsors, and I went full time. Weâve grown from a team of 1 (me) to a team of 4(!) - pulled entirely from the wonderful Dioxus community.
Now, Dioxus is something a little different. Real life, actual companies are shipping web apps, desktop apps, and mobile apps with Dioxus. What was once just a fun little side project powers a small fraction of apps out in the wild. We now have lofty goals of simplifying the entire app development ecosystem. Web, Desktop, Mobile, all end-to-end typesafe, blazing fast, living under one codebase. The dream!
With 0.5 we took a hard look at how Dioxus would need to change to achieve those goals. The request we got from the community was clear: make it simpler, make it robust, make it polished.
This is probably the biggest release of Dioxus ever, with so many new features, bug fixes, and improvements that I canât list them all. We churned over 100,000 lines of code (yes, 100,000+) with over 1,400 commits between 0.4.3 and 0.5.0. Hereâs a quick overview:
* Complete rewrite of `dioxus-core`, removing all unsafe code
* Abandoning `use_state` and `use_ref` for a clone-free `Signal`\-based API
* Removal of all lifetimes and the `cx: Scope` state
* A single, unified `launch` function that starts your app for any platform
* Asset hot reloading that supports Tailwind and Vanilla CSS
* Rewrite of events, allowing access to the native `WebSys` event types
* Extension of components with element properties (IE a Link now takes all of `` properties)
* Integrated Error Boundaries and Server Futures with Suspense integration
* 5x faster desktop reconciliation and custom asset handlers for streaming bytes
* Streaming server functions and Fullstack hot reloading
* Tons of QoL improvements, bug fixes, and more!
đĄ If you are updating from Dioxus 0.4, a [`migration guide`](https://dioxuslabs.com/learn/0.5/migration)
is available
To make Dioxus simpler, we wanted to remove lifetimes entirely. Newcomers to rust are easily scared off by lifetime issues, and even experienced Rustaceans find wading through obtuse error messages exhausting.
In Dioxus 0.1-0.4, every value in a component lives for a `'bump` lifetime. This lifetime lets you easily use hooks, props and the scope within event listeners without cloning anything. It was the chief innovation that made Dioxus so much easier to use than Yew when it was released.
// Scope and Element have the lifetime 'bump
fn OldDioxusComponent(cx: Scope) -> Element {
// hook has the lifetime 'bump
let mut state \= use\_state(cx, || 0);
cx.render(rsx! { button { // The closure has the lifetime 'bump which means you don't
// need to clone hook before you move it into the closure
onclick: move |\_event| \*state += 1,
} })
}
// Scope and Element have the lifetime 'bump
fn OldDioxusComponent(cx: Scope) -> Element {
// hook has the lifetime 'bump
let mut state \= use\_state(cx, || 0);
cx.render(rsx! { button { // The closure has the lifetime 'bump which means you don't
// need to clone hook before you move it into the closure
onclick: move |\_event| \*state += 1,
} })
}
This works great for hooks _most_ of the time. The lifetime lets you omit a bunch of manual clones every time you want to use a value inside an EventHandler (onclick, oninput, etc).
However, the lifetime doesnât work for futures. Futures in Dioxus need to be `'static` which means you always need to clone values before you use them in the future. Since a future might need to run while the component is rendering, it canât share the componentâs lifetime.
// Scope and Element have the lifetime 'bump
fn OldDioxusComponent(cx: Scope) -> Element {
// state has the lifetime 'bump
let state \= use\_state(cx, || 0);
cx.spawn({ // Because state has the lifetime 'bump, we need to clone it to make it
// 'static before we move it into the 'static future
let state \= state.clone(); async move {
println!("{state}");
} });
// ...
}
// Scope and Element have the lifetime 'bump
fn OldDioxusComponent(cx: Scope) -> Element {
// state has the lifetime 'bump
let state \= use\_state(cx, || 0);
cx.spawn({ // Because state has the lifetime 'bump, we need to clone it to make it
// 'static before we move it into the 'static future
let state \= state.clone(); async move {
println!("{state}");
} });
// ...
}
If you donât clone the value, you will run into an error like this:
4 | fn OldDioxusComponent(cx: Scope) -\> Element { | -- | | | \`cx\` is a reference that is only valid in the function body | has type \`&'1 Scoped<'1\>\`
...
8 | / cx.spawn(async move {
9 | | println!("{state}");
10 | | });
| | ^ | | | | |\_\_\_\_\_\_\`cx\` escapes the function body here | argument requires that \`'1\` must outlive \`'static\`
4 | fn OldDioxusComponent(cx: Scope) -\> Element { | -- | | | \`cx\` is a reference that is only valid in the function body | has type \`&'1 Scoped<'1\>\`
...
8 | / cx.spawn(async move {
9 | | println!("{state}");
10 | | });
| | ^ | | | | |\_\_\_\_\_\_\`cx\` escapes the function body here | argument requires that \`'1\` must outlive \`'static\`
The error complains that `cx` must outlive `'static` without mentioning the hook at all which can be very confusing.
Dioxus 0.5 fixes this issue by first removing scopes and the `'bump` lifetime and then introducing a new `Copy` state management solution called signals. Here is what the component looks like in Dioxus 0.5:
// Element has no lifetime, and you don't need a Scope
fn NewComponent() -> Element {
// state is 'static and Copy, even if the inner value you store is not Copy
let mut state \= use\_signal(|| 0);
// State is already 'static and Copy, so it is copied into the future automatically
spawn(async move {
println!("{state}");
});
rsx! { button { // The closure has the lifetime 'static, but state is copy so you don't need to clone into the closure
onclick: move |\_event| state += 1,
} }
}
// Element has no lifetime, and you don't need a Scope
fn NewComponent() -> Element {
// state is 'static and Copy, even if the inner value you store is not Copy
let mut state \= use\_signal(|| 0);
// State is already 'static and Copy, so it is copied into the future automatically
spawn(async move {
println!("{state}");
});
rsx! { button { // The closure has the lifetime 'static, but state is copy so you don't need to clone into the closure
onclick: move |\_event| state += 1,
} }
}
While this might seem like a rather innocuous change, it has an impressively huge impact on how easy it is to write new components. Iâd say building a new Dioxus app is about 2-5x easier with this change alone.
In the new version of Dioxus, scopes and the `'bump` lifetime have been removed! This makes declaring a component and using runtime functions within that component much easier:
You can now declare a component by just accepting your props directly instead of a scope parameter
#\[component\]
fn MyComponent(name: String) -> Element {
rsx! { "Hello {name}!" }
}
#\[component\]
fn MyComponent(name: String) -> Element {
rsx! { "Hello {name}!" }
}
And inside that component, you can use runtime functions directly
spawn(async move {
tokio::time::sleep(Duration::from\_millis(100)).await;
// You can even use runtime functions inside futures and event handlers!
let context: i32 \= consume\_context();
});
spawn(async move {
tokio::time::sleep(Duration::from\_millis(100)).await;
// You can even use runtime functions inside futures and event handlers!
let context: i32 \= consume\_context();
});
Now that lifetimes are gone, `Element`s are `'static` which means you can use them in hooks or even provide them through the context API. This makes some APIs like [virtual lists in Dioxus](https://github.com/matthunz/dioxus-lazy)
significantly easier. We expect more interesting APIs to emerge from the community now that you donât need to be a Rust wizard to implement things like virtualization and offscreen rendering.
Removing the `'bump` lifetime along with the scope gave us a chance to remove a lot of unsafe from Dioxus. **dioxus-core 0.5 contains no unsafe code đ**
Thereâs still a tiny bit of unsafe floating around various dependencies that we plan to remove throughout the 0.5 release cycle, but way less: all quite simple to cut or unfortunately necessary due to FFI.
Dioxus 0.5 introduces Signals as the core state primitive for components. Signals have two key advantages over the existing `use_state` and `use_ref` hooks: They are always `Copy` and they donât require manual subscriptions.
`Signal` is `Copy`, even if the inner `T` values is not. This is enabled by our new [generational-box](https://crates.io/crates/generational-box)
crate (implemented with zero unsafe). Signals can even optionally be `Send+Sync` if you need to move them between threads, removing the need for a whole class of specialized state management solutions.
The combination of `Copy + Send + Sync` Signals, and static components makes it incredibly easy to move state to anywhere you need it:
fn Parent() -> Element {
// We use a sync signal here so that we can use it in other threads,
// but you could use a normal signal if you have !Send data
let mut state \= use\_signal\_sync(|| 0);
spawn(async move {
// Signals have a ton of helper methods that make them easy to work with.
// You can call a signal like a function to get the current value
let value: i32 \= state();
});
// Because signals can be sync, we can copy them into threads easily
std::thread::spawn(move || {
loop {
std::thread::sleep(Duration::from\_millis(100));
println!("{state}");
} });
rsx! { button { // You can easily move it into an event handler just like use\_state
onclick: move |\_| state += 1
} }
}
fn Parent() -> Element {
// We use a sync signal here so that we can use it in other threads,
// but you could use a normal signal if you have !Send data
let mut state \= use\_signal\_sync(|| 0);
spawn(async move {
// Signals have a ton of helper methods that make them easy to work with.
// You can call a signal like a function to get the current value
let value: i32 \= state();
});
// Because signals can be sync, we can copy them into threads easily
std::thread::spawn(move || {
loop {
std::thread::sleep(Duration::from\_millis(100));
println!("{state}");
} });
rsx! { button { // You can easily move it into an event handler just like use\_state
onclick: move |\_| state += 1
} }
}
With `Copy` state, weâve essentially bolted on a light form of garbage collection into Rust that uses component lifecycles as the triggers for dropping state. From a memory perspective, this is basically the same as 0.4, but with the added benefit of not needing to explicitly `Clone` anything.
Signals are smarter about what components rerun when they are changed. A component will only rerun if you read the value of the signal in the component (not in an async task or event handler). In this example, only the child will re-render when the button is clicked because only the child component is reading the signal:
fn Parent() -> Element {
let mut state \= use\_signal(|| 0);
rsx! { button { onclick: move |\_| state += 1, "increment" }
Child { state }
}
}
#\[component\]
fn Child(state: Signal) -> Element {
rsx! { "{state}" }
}
fn Parent() -> Element {
let mut state \= use\_signal(|| 0);
rsx! { button { onclick: move |\_| state += 1, "increment" } Child { state }
}
}
#\[component\]
fn Child(state: Signal) -> Element {
rsx! { "{state}" }
}
Smarter subscriptions let us merge several different hooks into signals. For example, we were able to remove an entire crate dedicated to state management: Fermi. Fermi provided what was essentially a `use_state` API where statics were used as keys. This meant you could declare some global state, and then read it in your components:
static COUNT: Atom \= Atom::new(|| 0);
fn Demo(cx: Scope) -> Element {
let mut count \= use\_read\_atom(cx, &COUNT);
rsx! { "{count}" }
}
static COUNT: Atom \= Atom::new(|| 0);
fn Demo(cx: Scope) -> Element {
let mut count \= use\_read\_atom(cx, &COUNT);
rsx! { "{count}" }
}
Since fermi didnât support smart subscriptions, you had to explicitly declare use the right `use_read`/ `use_write` hooks to subscribe to the value. In Dioxus 0.5, we just use signals, eliminating the need for any sort of external state management solution altogether.
// You can use a lazily initialized signal called
// GlobalSignal in static instead of special Fermi atoms
static COUNT: GlobalSignal \= Signal::global(|| 0);
// Using the GlobalSignal is just the same as any other signal!
// No need for use\_read or use\_write
fn Demo() -> Element {
rsx! { "{COUNT}" }
}
// You can use a lazily initialized signal called
// GlobalSignal in static instead of special Fermi atoms
static COUNT: GlobalSignal \= Signal::global(|| 0);
// Using the GlobalSignal is just the same as any other signal!
// No need for use\_read or use\_write
fn Demo() -> Element {
rsx! { "{COUNT}" }
}
Signals even work with the context API, so you can quickly share state between components in your app:
fn Parent() -> Element {
// Create a new signal and provide it to the context API
// without a special use\_shared\_state hook
let mut state \= use\_context\_provider(|| Signal::new(0));
rsx! { button { onclick: move |\_| state += 1, "Increment" }
Child {}
}
}
fn Child() -> Element {
// Get the state from the context API
let state \= use\_context::>();
rsx! { "{state}" }
}
fn Parent() -> Element {
// Create a new signal and provide it to the context API
// without a special use\_shared\_state hook
let mut state \= use\_context\_provider(|| Signal::new(0));
rsx! { button { onclick: move |\_| state += 1, "Increment" } Child {}
}
}
fn Child() -> Element {
// Get the state from the context API
let state \= use\_context::>();
rsx! { "{state}" }
}
Smart subscriptions also apply to hooks. Hooks like `use_future` and `use_memo` will now automatically add signals you read inside the hook to the dependencies of the hook:
// You can use a lazily initialized signal called GlobalSignal in static instead of special Fermi atoms
static COUNT: GlobalSignal \= Signal::global(|| 0);
fn App() -> Element {
// Because we read COUNT inside the memo, it is automatically added to the memo's dependencies
// If we change COUNT, then the memo knows it needs to rerun
let memo \= use\_memo(move || COUNT() / 2);
rsx! { "{memo}" }
}
// You can use a lazily initialized signal called GlobalSignal in static instead of special Fermi atoms
static COUNT: GlobalSignal \= Signal::global(|| 0);
fn App() -> Element {
// Because we read COUNT inside the memo, it is automatically added to the memo's dependencies
// If we change COUNT, then the memo knows it needs to rerun
let memo \= use\_memo(move || COUNT() / 2);
rsx! { "{memo}" }
}
As part of our asset system overhaul, we implemented hot reloading of CSS files in the asset directory. If a CSS file appears in your RSX, the `dx` CLI will watch that file and immediately stream its updates to the running app. This works for Web, Desktop, and Fullstack, with mobile support coming in a future mobile-centric update.
When combined with the Tailwind watcher, we now support hot reloading of Tailwind CSS! On top of that, we also support IDE hinting of Tailwind classes in VSCode with a [custom regex extension](https://github.com/tailwindlabs/tailwindcss/discussions/7073)
Whatâs even niftier is that you can stream these changes to several devices at once, unlocking simultaneous hot reloading across all devices that you target:
Since its release, Dioxus has used a synthetic event system to create a cross platform event API. Synthetic events can be incredibly useful to make events work across platforms and even serialize them across the network, but they do have some drawbacks.
Dioxus 0.5 finally exposes the underlying event type for each platform along with a trait with a cross platform API. This has two advantages:
1. You can get whatever information you need from the platform event type or pass that type to another library:
fn Button() -> Element {
rsx! { button { onclick: move |event| {
let web\_sys\_event: web\_sys::MouseEvent \= event.web\_event(); web\_sys::console::log\_1(&web\_sys\_event.related\_target.into());
} } }
}
fn Button() -> Element {
rsx! { button { onclick: move |event| {
let web\_sys\_event: web\_sys::MouseEvent \= event.web\_event(); web\_sys::console::log\_1(&web\_sys\_event.related\_target.into());
} } }
}
1. Dioxus can bundle split code for events apps donât use. For a hello world example, this shrinks the gzipped size ~ 25%!
Again, this seems like a small change on the surface, but opens up dozens of new use cases and possible libraries you can build with Dioxus.
đĄ The [Dioxus optimization guide](https://dioxuslabs.com/learn/0.5/cookbook/optimizing#build-configuration)
has tips to help you make the smallest possible bundle
Dioxus 0.5 introduces a new cross platform API to launch your app. This makes it easy to target multiple platforms with the same application. Instead of pulling in a separate renderer package, you can now enable a feature on the Dioxus crate and call the launch function from the prelude:
\[dependencies\]
dioxus \= "0.5"
\[features\]
default \= \[\]
desktop \= \["dioxus/desktop"\]
fullstack \= \["dioxus/fullstack"\]
server \= \["dioxus/axum"\]
web \= \["dioxus/web"\]
\[dependencies\]
dioxus \= "0.5"
\[features\]
default \= \[\]
desktop \= \["dioxus/desktop"\]
fullstack \= \["dioxus/fullstack"\]
server \= \["dioxus/axum"\]
web \= \["dioxus/web"\]
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| rsx!{ "hello world" })
}
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| rsx!{ "hello world" })
}
With that single application, you can easily target:
\# Desktop
dx serve --platform desktop
\# SPA web
dx serve --platform web
\# Or a fullstack application
dx serve --platform fullstack
\# Desktop
dx serve --platform desktop
\# SPA web
dx serve --platform web
\# Or a fullstack application
dx serve --platform fullstack
The CLI is now smart enough to automatically pass in the appropriate build features depending on the platform youâre targeting.
Currently assets in Dioxus (and web applications in general) can be difficult to get right. Links to your asset can easily get out of date, the link to your asset can be different between desktop and web applications, and you need to manually add assets you want to use into your bundled application. In addition to all of that, assets can be a huge performance bottleneck.
Lets take a look at the Dioxus Mobile guide in the docsite as an example:
The 0.4 mobile guide takes 7 seconds to load and transfers 9 MB of resources. The page has 6 different large image files which slows down the page loading times significantly. We could switch to a more optimized image format like `avif` , but manually converting every screenshot is tedious and time consuming.
Lets take a look at the 0.5 mobile guide with the new asset system:
The new mobile guide takes less than 1 second to load and requires only 1/3 of the resources with the exact same images!
Dioxus 0.5 introduces a new asset system called [manganis](https://github.com/DioxusLabs/manganis)
. Manganis integrates with the CLI to check, bundle and optimize assets in your application. The API is currently unstable so the asset system is currently published as a separate crate. In the new asset system, you can just wrap your assets in the `mg!` macro and they will automatically be picked up by the CLI. You can read more about the new asset system in the [manganis docs](https://docs.rs/crate/manganis/latest)
.
As we continue to iterate on the 0.5 release, we plan to add hot reloading to manganis assets, so you can interactively add new the features to your app like CSS, images, Tailwind classes, and more without forcing a complete reload.
Dioxus implements several optimizations to make diffing rendering fast. [Templates](https://dioxuslabs.com/blog/templates-diffing)
let Dioxus skip diffing on any static parts of the rsx macro. However, diffing is only one side of the story. After you create a list of changes you need to make to the DOM, you need to apply them.
We developed [sledgehammer](https://github.com/ealmloff/sledgehammer_bindgen)
for Dioxus Web to make applying those mutations as fast as possible. It makes manipulating the DOM from Rust almost as [fast as native JavaScript](https://krausest.github.io/js-framework-benchmark/2023/table_chrome_114.0.5735.90.html)
.
In Dioxus 0.5, we apply that same technique to apply changes across the network as fast as possible. Instead of using JSON to communicate changes to the Desktop and LiveView renderers, Dioxus 0.5 uses a binary protocol.
For render intensive workloads, the new renderer takes only 1/5 the time to apply the changes in the browser with 1/2 the latency. Here is one of the benchmarks we developed while working on the new binary protocol. In Dioxus 0.4, the renderer was constantly freezing. In Dioxus 0.5, it runs smoothly:
**Dioxus 0.4**
**Dioxus 0.5**
One common pattern when creating components is providing some additional functionality to a specific element. When you wrap an element, it is often useful to provide some control over what attributes are set in the final element. Instead of manually copying over each attribute from the element, Dioxus 0.5 supports extending specific elements and spreading the attributes into an element:
#\[derive(Props, PartialEq, Clone)\]
struct Props {
// You can extend a specific element or global attributes
#\[props(extends \= img)\] attributes: Vec,
}
fn ImgPlus(props: Props) -> Element {
rsx! { // You can spread those attributes into any element
img { ..props.attributes }
}
}
fn app() -> Element {
rsx! { ImgPlus {
// You can use any attributes you would normally use on the img element
width: "10px",
height: "10px",
src: "https://example.com/image.png",
} }
}
#\[derive(Props, PartialEq, Clone)\]
struct Props {
// You can extend a specific element or global attributes
#\[props(extends \= img)\] attributes: Vec,
}
fn ImgPlus(props: Props) -> Element {
rsx! { // You can spread those attributes into any element
img { ..props.attributes }
}
}
fn app() -> Element {
rsx! { ImgPlus {
// You can use any attributes you would normally use on the img element
width: "10px",
height: "10px",
src: "https://example.com/image.png",
} }
}
Another huge quality-of-life feature we added was the ability to use shorthand struct initialization syntax to pass attributes into elements and components. We got tired of passing `class: class` everywhere and decided to finally implement this long awaited feature, at the expense of some code breakage. Now, itâs super simple to declare attributes from props:
#\[component\]
fn ImgPlus(class: String, id: String, src: String) -> Element {
rsx! { img { class, id, src } }
}
#\[component\]
fn ImgPlus(class: String, id: String, src: String) -> Element {
rsx! { img { class, id, src } }
}
This feature works for anything implementing `IntoAttribute`, meaning signals also benefit from shorthand initialization. While signals as attributes donât yet skip diffing, we plan to add this as a performance optimization throughout the 0.5 release cycle.
Another amazing feature added this cycle was attribute merging. When working with libraries like Tailwind, youâll occasionally want to make certain attributes conditional. Before, you had to format the attribute using an empty string. Now, you can simply add an extra attribute with a conditional, and the attribute will be merged using a space as a delimiter:
#\[component\]
fn Blog(enabled: bool) -> Element {
rsx! { div { class: "bg-gray-200 border rounded shadow",
class: if enabled { "text-white" }
} }
}
#\[component\]
fn Blog(enabled: bool) -> Element {
rsx! { div { class: "bg-gray-200 border rounded shadow",
class: if enabled { "text-white" } } }
}
This is particularly important when using libraries like Tailwind where attributes need to be parsed at compile time but also dynamic at runtime. This syntax integrates with the Tailwind compiler, removing the runtime overhead for libraries like tailwind-merge.
Dioxus 0.5 supports the latest version of [the server functions crate](https://crates.io/crates/server_fn)
which supports streaming data. Server functions can now choose to stream data to or from the client. This makes it easier to do a whole class of tasks on the server.
Creating a streaming server function is as easy as defining the output type and returning a TextStream from the server function. Streaming server functions are great for updating the client during any long running task.
We built an AI text generation example here: [https://github.com/ealmloff/dioxus-streaming-llm](https://github.com/ealmloff/dioxus-streaming-llm)
that uses Kalosm and local LLMS to serve what is essentially a clone of OpenAIâs ChatGPT endpoint on commodity hardware.
#\[server(output \= StreamingText)\]
pub async fn mistral(text: String) -> Result {
let text\_generation\_stream \= todo!();
Ok(TextStream::new(text\_generation\_stream))
}
#\[server(output \= StreamingText)\]
pub async fn mistral(text: String) -> Result {
let text\_generation\_stream \= todo!();
Ok(TextStream::new(text\_generation\_stream))
}
Side note, the AI metaframework used here - Kalosm - is maintained by the Dioxus core team member ealmloff, and his AI GUI app Floneum is built with Dioxus!
The CLI now supports a `fullstack` platform with hot reloading and parallel builds for the client and sever. You can now serve your fullstack app with the `dx` command:
dx serve
\# Or with an explicit platform
dx serve --platform fullstack
dx serve
\# Or with an explicit platform
dx serve --platform fullstack
[https://github.com/DioxusLabs/dioxus/pull/1505](https://github.com/DioxusLabs/dioxus/pull/1505)
[`@DonAlonzo`](https://github.com/DonAlonzo)
added LiveView support for the router in Dioxus 0.5. The router will now work out of the box with your LiveView apps!
[https://github.com/DioxusLabs/dioxus/pull/1719](https://github.com/DioxusLabs/dioxus/pull/1719)
[`@willcrichton`](https://github.com/willcrichton)
added support for custom asset handlers to Dioxus Desktop. Custom asset handlers let you efficiently stream data from your rust code into the browser without going through JavaScript. This is great for high bandwidth communication like [video streaming](https://github.com/DioxusLabs/dioxus/pull/1727)
:
Now, you can do things like work with gstreamer or webrtc and pipe data directly into the webview without needing to encode/decode frames by hand.
This is a bit smaller of a tweak, but now we properly support file drops for Desktop:
Previously we just gave you the option to intercept filedrops but now itâs natively integrated into the event system
Error handling: You can use error boundaries and the throw trait to easily handle errors higher up in your app
Dioxus provides a much easier way to handle errors: throwing them. Throwing errors combines the best parts of an error state and early return: you can easily throw an error with `?`, but you keep information about the error so that you can handle it in a parent component.
You can call `throw` on any `Result` type that implements `Debug` to turn it into an error state and then use `?` to return early if you do hit an error. You can capture the error state with an `ErrorBoundary` component that will render the a different component if an error is thrown in any of its children.
fn Parent() -> Element {
rsx! { ErrorBoundary {
handle\_error: |error| rsx! {
"Oops, we encountered an error. Please report {error} to the developer of this application"
}, ThrowsError {}
} }
}
fn ThrowsError() -> Element {
let name: i32 \= use\_hook(|| "1.234").parse().throw()?;
todo!()
}
fn Parent() -> Element {
rsx! { ErrorBoundary {
handle\_error: |error| rsx! {
"Oops, we encountered an error. Please report {error} to the developer of this application"
}, ThrowsError {}
} }
}
fn ThrowsError() -> Element {
let name: i32 \= use\_hook(|| "1.234").parse().throw()?;
todo!()
}
You can even nest `ErrorBoundary` components to capture errors at different levels of your app.
fn App() -> Element {
rsx! { ErrorBoundary {
handle\_error: |error| rsx! {
"Hmm, something went wrong. Please report {error} to the developer"
}, Parent {}
} }
}
fn Parent() -> Element {
rsx! { ErrorBoundary {
handle\_error: |error| rsx! {
"The child component encountered an error: {error}"
}, ThrowsError {}
} }
}
fn ThrowsError() -> Element {
let name: i32 \= use\_hook(|| "1.234").parse().throw()?;
todo!()
}
fn App() -> Element {
rsx! { ErrorBoundary {
handle\_error: |error| rsx! {
"Hmm, something went wrong. Please report {error} to the developer"
}, Parent {}
} }
}
fn Parent() -> Element {
rsx! { ErrorBoundary {
handle\_error: |error| rsx! {
"The child component encountered an error: {error}"
}, ThrowsError {}
} }
}
fn ThrowsError() -> Element {
let name: i32 \= use\_hook(|| "1.234").parse().throw()?;
todo!()
}
This pattern is particularly helpful whenever your code generates a non-recoverable error. You can gracefully capture these "global" error states without panicking or handling state for each error yourself.
We shipped hot reloading in 0.3, added it to Desktop in 0.4, and now weâre finally enabling it by default in 0.5. By default, when you `dx serve` your app, hot reloading is enabled in development mode.
Additionally, weâve drastically improved the developer experience of building desktop apps. When we canât hot reload the app and have to do a full recompile, we now preserve the state of the open windows and resume that state. This means your app wonât block your entire screen on every edit and it will maintain its size and position, leading to a more magical experience. Once youâve played with it, you can never go back - itâs that good.
With this update, our newest core team member Miles put serious work into overhauling documentation and our templates. We now have templates to create new Dioxus apps for Web, Desktop, Mobile, TUI, and Fullstack under one command.
We also updated the default app you get when using `dx new` to be closer to the traditional create-react-app. The template is now seeded with assets, CSS, and some basic deploy configuration. Plus, it includes links to useful resources like dioxus-std, the VSCode Extension, docs, tutorials, and more.
The Dioxus Community is something special: discord members marc and Doge have been hard at working updating important ecosystem crates for the 0.5 release. With this release, important crates like icons, charts, and the Dioxus-specific standard library are ready to use right out the gate. The `Dioxus Community` project is a new GitHub organization that keeps important crates up-to-date even when the original maintainers step down. If you build a library for Dioxus, weâll be happy to help maintain it, keeping it at what is essentially âTier 2â support.
At a certain point we had to stop adding new features to this release. Thereâs plenty of cool projects on the horizon:
* Stabilizing and more deeply integrating the asset system
* Bundle splitting the outputted `.wasm` directly - with lazy components
* Islands and resumable interactivity (serializing signals!)
* Server components and merging LiveView into Fullstack
* Enhanced Devtools (potentially featuring some AI!) and testing framework
* Complete Mobile overhaul
* Fullstack overhaul with WebSocket, SSE, progressive forms, and more
Weâre not going to say much about this now, but hereâs a sneak peek at âBlitz 2.0â⊠weâre finally integrating servo into Blitz so you can render natively with WGPU using the same CSS engine that powers Firefox. To push this effort forward, weâve brought the extremely talented Nico Burns (the wizard behind our layout library Taffy) on full time. More about this later, but hereâs a little demo of [google.com](https://google.com/)
being rendered at 900 FPS entirely on the GPU:
Admittedly the current iteration is not quite there (google.com is in fact a little wonky) but weâre progressing rapidly here and are quickly approaching something quite usable. The repo is here if you want to take a look and get involved:
[https://github.com/jkelleyrtp/stylo-dioxus](https://github.com/jkelleyrtp/stylo-dioxus)
Well, thatâs it for the new features. We mightâve missed a few things (thereâs so much new!). If you find Dioxus as exciting as we do, weâd love your help to completely transform app development. Weâd love contributions including:
* Translating docs into your native language
* Attempting âGood First Issuesâ
* Improving our documentation
* Contributing to the CLI
* Help answer questions from the discord community
Thatâs it! Weâre super grateful for the community support and excited for the rest of 2024.
Build cool things! âïž
On this page
------------
* [Lifetime Problems](https://dioxuslabs.com/blog/release-050/#lifetime-problems)
* [Goodbye scopes and lifetimes!](https://dioxuslabs.com/blog/release-050/#goodbye-scopes-and-lifetimes)
* [Removal of all Unsafe in Core](https://dioxuslabs.com/blog/release-050/#removal-of-all-unsafe-in-core)
* [Signals!](https://dioxuslabs.com/blog/release-050/#signals)
* [Copy state](https://dioxuslabs.com/blog/release-050/#copy-state)
* [Smarter subscriptions](https://dioxuslabs.com/blog/release-050/#smarter-subscriptions)
* [CSS Hot Reloading](https://dioxuslabs.com/blog/release-050/#css-hot-reloading)
* [Event System Rewrite](https://dioxuslabs.com/blog/release-050/#event-system-rewrite)
* [Cross platform launch](https://dioxuslabs.com/blog/release-050/#cross-platform-launch)
* [Asset System Beta](https://dioxuslabs.com/blog/release-050/#asset-system-beta)
* [5x Faster Desktop Rendering](https://dioxuslabs.com/blog/release-050/#5x-faster-desktop-rendering)
* [Spreading props](https://dioxuslabs.com/blog/release-050/#spreading-props)
* [Shorthand attributes](https://dioxuslabs.com/blog/release-050/#shorthand-attributes)
* [Multi-line attribute merging](https://dioxuslabs.com/blog/release-050/#multi-line-attribute-merging)
* [Server function streaming](https://dioxuslabs.com/blog/release-050/#server-function-streaming)
* [Fullstack CLI platform](https://dioxuslabs.com/blog/release-050/#fullstack-cli-platform)
* [LiveView router support](https://dioxuslabs.com/blog/release-050/#liveview-router-support)
* [Custom Asset Handlers](https://dioxuslabs.com/blog/release-050/#custom-asset-handlers)
* [Native File Handling](https://dioxuslabs.com/blog/release-050/#native-file-handling)
* [Error handling](https://dioxuslabs.com/blog/release-050/#error-handling)
* [Hot reloading by default and âdevelopâ mode for Desktop](https://dioxuslabs.com/blog/release-050/#hot-reloading-by-default-and-develop-mode-for-desktop)
* [Updates to the Dioxus template](https://dioxuslabs.com/blog/release-050/#updates-to-the-dioxus-template)
* [Dioxus-Community and Dioxus-std](https://dioxuslabs.com/blog/release-050/#dioxus-community-and-dioxus-std)
* [Coming soon](https://dioxuslabs.com/blog/release-050/#coming-soon)
* [Sneak Peek: Dioxus-Blitz revival using Servo](https://dioxuslabs.com/blog/release-050/#sneak-peek-dioxus-blitz-revival-using-servo)
* [How can you contribute?](https://dioxuslabs.com/blog/release-050/#how-can-you-contribute)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
[Back to blog](https://dioxuslabs.com/blog/)
Dioxus 0.6
==========
December 9, 2024 - Jonathan Kelley
### Massive Tooling Improvements: Mobile Simulators, Magical Hot-Reloading, Interactive CLI, and more!
Today we're releasing Dioxus 0.6!
Dioxus is a framework for building fullstack web, desktop, and mobile apps with a single codebase. Our goal is to build a "Flutter but better." Dioxus focuses on first-class fullstack web support, type-safe server/client communication, and blazing fast performance.
With this release, we focused on making Dioxus easier to use, improving the developer experience, and fixing bugs.
Headlining the release is a complete overhaul of the Dioxus CLI:
* **[`dx serve` for mobile](https://dioxuslabs.com/blog/release-060#android-and-ios-support-for-dx-serve)
**: Serve your app on Android and iOS simulators and devices.
* **[Magical Hot-Reloading](https://dioxuslabs.com/blog/release-060#completely-revamped-hot-reloading)
**: Hot-Reloading of formatted strings, properties, and nested `rsx!{}`.
* **[Interactive CLI](https://dioxuslabs.com/blog/release-060#interactive-command-line-tools)
**: Rewrite of the Dioxus CLI with a new, interactive UX inspired by Astro.
* **[Inline Stack Traces](https://dioxuslabs.com/blog/release-060#inline-wasm-stacktraces-and-tracing-integration)
**: Capture WASM panics and logs directly into your terminal.
* **[Server Functions for Native](https://dioxuslabs.com/blog/release-060#fullstack-desktop-and-mobile)
**: Inline Server RPC for Desktop and Mobile apps.
We also improved the developer experience across the entire framework, fixing long standing bugs and improving tooling:
* **[Toasts and Loading Screens](https://dioxuslabs.com/blog/release-060#toasts-and-loading-screens)
**: New toasts and loading screens for web apps in development.
* **[Improved Autocomplete](https://dioxuslabs.com/blog/release-060#completely-revamped-autocomplete)
**: Massively improved autocomplete of RSX.
* **[`asset!` Stabilization](https://dioxuslabs.com/blog/release-060#stabilizing-manganis-asset-system)
**: Stabilizing our linker-based asset system integrated for native apps.
* **[Streaming HTML](https://dioxuslabs.com/blog/release-060#suspense-and-html-streaming-for-the-web)
**: Stream `Suspense` and `Error` Boundaries from the server to the client.
* **[SSG and ISG](https://dioxuslabs.com/blog/release-060#static-site-generation-and-isg)
**: Support for Static Site Generation and Incremental Static Regeneration.
* **[Error Handling with `?`](https://dioxuslabs.com/blog/release-060#question-mark-error-handling)
**: Use `?` to handle errors in event handlers, tasks, and components.
* **[Meta Elements](https://dioxuslabs.com/blog/release-060#document-elements-title---link---stylesheet--and-meta-)
**: New `Head`, `Title`, `Meta`, and `Link` elements for setting document attributes.
* **[Synchronous `prevent_default`](https://dioxuslabs.com/blog/release-060#synchronous-prevent-default)
**: Handle events synchronously across all platforms.
* **[`onresize` Event Handler](https://dioxuslabs.com/blog/release-060#tracking-size-with-onresize)
**: Track an element's size without an IntersectionObserver.
* **[`onvisible` Event Handler](https://dioxuslabs.com/blog/release-060#tracking-visibility-with-onvisible)
**: Track an element's visibility without an IntersectionObserver.
* **[WGPU Integration](https://dioxuslabs.com/blog/release-060#hybrid-wgpu-overlays)
**: Render Dioxus as an overlay on top of WGPU surfaces and child windows.
* **[`dx bundle` for Web, iOS, and Android](https://dioxuslabs.com/blog/release-060#web-ios-and-android-bundle-support)
**: Complete `dx bundle` support for every platform.
* **[`json` mode](https://dioxuslabs.com/blog/release-060#json-output-for-ci--cli)
**: Emit CLI messages as JSON for use by 3rd party tools and CI/CD pipelines.
* **[New Templates](https://dioxuslabs.com/blog/release-060#new-starter-templates)
**: Three new starter templates for cross-platform apps.
* **[Nightly Tutorial and Guides](https://dioxuslabs.com/blog/release-060#nightly-docs-tutorials-and-new-guides)
**: New tutorials and guides for Dioxus 0.6 and beyond.
* **[Binary Patching Prototype](https://dioxuslabs.com/blog/release-060#preview-of-in-place-binary-patching)
**: Prototype of our new pure Rust hot-reloading engine.
Dioxus 0.6 is our biggest release ever: over 350 pull requests merged and hundreds of issues closed. We shipped 0.6 with a few goals:
* Dramatically improve the quality of hot-reloading, autocomplete, and asset bundling.
* Make the Dioxus CLI more robust and easier to use.
* Inline our mobile tooling into the dioxus CLI for 1st-class mobile support.
Since this post is quite long, we made a quick video highlighting new features, bugs fixed, and a quick tour of everything you can do with Dioxus now:
Dioxus 0.6 is shipping with a completely overhauled CLI experience! Weâve completely rewritten the CLI to support a ton of new features and improve stability:
The new CLI sports live progress bars, animations, an interactive filter system, the ability to change log levels on the fly, and more.
The CLI rewrite alone took more than half this release cycle. We went through several different design iterations and solved tons of bugs along the way. A few of the highlights:
* You can manually rebuild your app by pressing `r`
* You can toggle the log level of the CLI output on the fly and even inspect Cargo internal logs
* We output all internal logs of the CLI so you can debug any issues
* We capture logs for WASM tracing and panics
* We dropped the `outdir` concept and instead use `target/dx` for all output.
* Inline support for iOS and Android emulators.
You can install the new CLI using [cargo binstall](https://github.com/cargo-bins/cargo-binstall)
with `cargo binstall [[email protected]](https://dioxuslabs.com/cdn-cgi/l/email-protection) --force`.
With Dioxus 0.6, the dioxus CLI supports `dx serve --platform ios/android` out of the box! đ
While Dioxus has always had mobile support, the Rust tooling for mobile has been extremely unstable. Users constantly ran into issues with tools like [`cargo-mobile`](https://github.com/BrainiumLLC/cargo-mobile)
and [`cargo-mobile2`](https://github.com/tauri-apps/cargo-mobile2)
. These tools, while useful, take a different architectural approach than what is a good fit for Dioxus.
With this release, we wrote our entire mobile tooling system from scratch. Now, you can go from `dx new` to `dx serve --platform ios` in a matter of seconds.
The Android and iOS simulator targets support all the same features as desktop: hot-reloading, fast rebuilds, asset bundling, logging, etc. Dioxus is also the only Rust framework that supports `main.rs` for mobile - no other tools have supported the same `main.rs` for every platform until now.
Our inline mobile support requires no extra configurations, no manual setup for Gradle, Java, Cocoapods, and no other 3rd party tooling. If you already have the Android NDK or iOS Simulator installed, you currently are less than 30 seconds away from a production-ready mobile app written entirely in Rust.
The simplest Dioxus 0.6 Mobile app is tiny:
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| rsx! { "hello dioxus! đ§Ź" });
}
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| rsx! { "hello dioxus! đ§Ź" });
}
Especially, when compared to v0.5 which required you to migrate your app to a `cdylib` and manually set up the binding layer:
// no main allowed! - must expose a \`start\_app\` function
#\[no\_mangle\]
#\[inline(never)\]
#\[cfg(any(target\_os \= "android", target\_os \= "ios"))\]
pub extern "C" fn start\_app() {
#\[cfg(target\_os \= "android")\]
{ tao::android\_binding!(
com\_dioxuslabs, app\_name, WryActivity,
wry::android\_setup, \_start\_app ); wry::android\_binding!(com\_dioxuslabs, app\_name);
}
// need to manually catch panics!
#\[cfg(target\_os \= "ios")\]
stop\_unwind(|| main())
}
#\[cfg(any(target\_os \= "android", target\_os \= "ios"))\]
fn stop\_unwind T, T>(f: F) -> T {
match std::panic::catch\_unwind(std::panic::AssertUnwindSafe(f)) {
Ok(t) \=> t, Err(err) \=> {
eprintln!("attempt to unwind out of \`rust\` with err: {:?}", err);
std::process::abort() } }
}
// no main allowed! - must expose a \`start\_app\` function
#\[no\_mangle\]
#\[inline(never)\]
#\[cfg(any(target\_os \= "android", target\_os \= "ios"))\]
pub extern "C" fn start\_app() {
#\[cfg(target\_os \= "android")\]
{ tao::android\_binding!(
com\_dioxuslabs, app\_name, WryActivity,
wry::android\_setup, \_start\_app ); wry::android\_binding!(com\_dioxuslabs, app\_name);
}
// need to manually catch panics!
#\[cfg(target\_os \= "ios")\]
stop\_unwind(|| main())
}
#\[cfg(any(target\_os \= "android", target\_os \= "ios"))\]
fn stop\_unwind T, T>(f: F) -> T {
match std::panic::catch\_unwind(std::panic::AssertUnwindSafe(f)) {
Ok(t) \=> t, Err(err) \=> {
eprintln!("attempt to unwind out of \`rust\` with err: {:?}", err);
std::process::abort() } }
}
While 1st-class support for mobile platforms is quite exciting, there are certainly many limitations: the Rust mobile ecosystem is nascent, we donât have great ways of configuring the many platform-specific build flags, and there isnât a particularly great Rust/Java interop story.
If you're interested in helping us build out mobile support, please join us on [Discord](https://discord.gg/XgGxMSkvUM)
.
We shipped massive improvements to the hot-reloading engine powering Dioxus. Our internal goal was to iterate on the Dioxus Docsite with zero full rebuilds.
This means we needed to add support for a number of new hot-reloading engine changes:
* Hot-reload formatted strings
* Hot-reload nested rsx blocks
* Hot-reload component properties and simple Rust expressions
* Hot-reload mobile platforms and their bundled assets
The new hot-reloading engine almost feels like magic - you can quickly iterate on new designs - and even modify simple Rust code! - without waiting for full rebuilds:
The new engine allows you to modify formatted strings anywhere in your `rsx`: in text blocks, element attributes, and even on component properties.
#\[component\]
fn Counter(count: i32, class\_ext: String) -> Element {
rsx! { // Instantly hot-reload these formatted strings
button { class: "btn-{class\_ext}", "Count {count}" }
// Even hot-reload formatted strings as props on components
Component { text: "btn-{class\_exit}" }
}
}
#\[component\]
fn Counter(count: i32, class\_ext: String) -> Element {
rsx! { // Instantly hot-reload these formatted strings
button { class: "btn-{class\_ext}", "Count {count}" }
// Even hot-reload formatted strings as props on components
Component { text: "btn-{class\_exit}" } }
}
The same tooling that enables component props reloading also works with _any Rust literal!_ You can hot-reload numbers, booleans, and strings on component prop boundaries.
fn LoopIt() -> Element {
rsx! { // Change either prop without causing a full rebuild
Link {
to: "google.com",
enabled: false
} }
}
fn LoopIt() -> Element {
rsx! { // Change either prop without causing a full rebuild
Link {
to: "google.com",
enabled: false
} }
}
The new hot-reloading engine also brings nested rsx hot-reloading support. The contents of `for` loops, `if` statements, and component bodies all now participate in hot-reloading:
fn LoopIt() -> Element {
rsx! { for x in 0..10 {
// modifying the body of this loop is hot-reloadable!
li { "{x}" }
}
Counter {
// component children also get hot-reloaded
div { "These div contents get hot-reloaded too!" }
} }
}
fn LoopIt() -> Element {
rsx! { for x in 0..10 {
// modifying the body of this loop is hot-reloadable!
li { "{x}" } }
Counter {
// component children also get hot-reloaded
div { "These div contents get hot-reloaded too!" } } }
}
You can now move and clone Rust expressions between contexts, allowing you to re-use components and formatted strings between element properties without a full rebuild.
fn LoopIt() -> Element {
rsx! { // If we start with this formatted text
"Thing1 {a}"
// we can add this formatted text on the fly
"Thing2 {a}"
}
}
fn LoopIt() -> Element {
rsx! { // If we start with this formatted text
"Thing1 {a}"
// we can add this formatted text on the fly
"Thing2 {a}"
}
}
These changes are supported in all platforms: web, desktop, and mobile.
You can now hot-reload RSX and Assets on iOS and Android apps in addition to the classic web and desktop platforms.
The new hot-reloading feels like magic and we encourage you to try it out!
Another huge overhaul in Dioxus 0.6: greatly improved autocomplete of `rsx! {}`. Our old implementation of `rsx! {}` suffered from poor integration with tools like Rust-analyzer which provide language-server integration for your code. If the input to the macro wasnât perfectly parsable, we failed to generate any tokens at all, meaning rust-analyzer couldnât jump in to provide completions.
The work to fix this was immense. Macro parsing libraries like `syn` donât provide great facilities for âpartial parsingâ Rust code which is necessary for implementing better errors and autocomplete. We had to rewrite the entire internals of `rsx! {}` to support partial parsing of `rsx! {}` , but finally, in 0.6, weâre able to provide stellar autocomplete. Not only can we autocomplete Rust code in attribute positions, but with a few tricks, weâre able to automatically insert the appropriate braces next to element names:
The autocomplete experience is much nicer now, with all attributes, elements, components, and inline Rust code benefiting from the overhauled experience. All Rust expressions participate in proper Rust-analyzer autocomplete and we're even able to provide warnings when `rsx!{}` input is malformed instead of panicking.
Along with the rewrite of the CLI, we shipped a `tracing` integration for WASM apps that captures panics and logs and sends them `dx` in your terminal. When you build your app with debug symbols, stack traces directly integrate with your editor, allowing you to jump directly to the troublesome files from within your terminal.
Thanks to this integration, we now have much nicer logging around fullstack apps, showing status codes, fetched assets, and other helpful information during development. With the toggle-able verbosity modes, you can now inspect the internal logs of the CLI itself, making it easier to debug issues with tooling to understand what exactly `dx` is doing when it builds your app. Simply type `v` to turn on âverboseâ mode and `t` to turn on âtraceâ mode for more helpful logs:
As part of our CLI overhaul, we wanted to provide better feedback for developers when building web apps. Dioxus 0.6 will now show Popup Toasts and Loading Screens for web apps in development mode.
Now, when your app is building, Dioxus will render a loading screen with the current progress of the build:
Additionally, once the app is rebuilt, youâll receive a toast indicating the status of the build:
Additionally, we properly integrated server functions with native apps. Server functions finally work out-of-the-box when targeting desktop and mobile:
By default, in development, we set the server function endpoint to be localhost, so in production you need to make sure to point the functions to your deployed server:
fn main() {
#\[cfg(feature \= "production")\]
server\_fn::client::set\_server\_url("app.endpoint.com");
dioxus::launch(app)
}
fn main() {
#\[cfg(feature \= "production")\]
server\_fn::client::set\_server\_url("app.endpoint.com");
dioxus::launch(app)
}
We introduced our new asset system, [Manganis](https://github.com/DioxusLabs/manganis)
, in an alpha state with the 0.5 release. Dioxus 0.6 stabilizes the asset system and fixes several bugs and performance issues. You can try out the new [linker based asset system](https://github.com/DioxusLabs/manganis/pull/30)
 by including an `asset!` anywhere in your code. It will automatically be optimized and bundled across all platforms:
rsx! {
img { src: asset!("/assets/image.png") }
}
rsx! {
img { src: asset!("/assets/image.png") }
}
Manganis is a crucial step in supporting assets cross-platform, and specifically, through dependencies. Previously, if an upstream library wanted to export an asset like an image or a stylesheet, your app would need to manually add those assets in your `assets` folder. This gets complex and messy when libraries generate CSS: many classes are duplicated and might even conflict with each other. Now, all CSS collected by the `asset!()` macro is processed via our build pipeline, benefiting from minification and deduplication. Libraries can include their stylesheets and images and components and you can be guaranteed that those assets make it bundled into your app:
fn app() -> Element {
rsx! { cool\_icons::SomeCoolImage {}
}
}
// in a distant library....
mod cool\_icons {
pub fn SomeCoolImage() -> Element {
rsx! { img { src: asset!("/assets/some\_cool\_image.png") }
} }
}
fn app() -> Element {
rsx! { cool\_icons::SomeCoolImage {}
}
}
// in a distant library....
mod cool\_icons {
pub fn SomeCoolImage() -> Element {
rsx! { img { src: asset!("/assets/some\_cool\_image.png") }
} }
}
Even better, assets like images are automatically optimized to generate thumbnails and more optimized formats. This can cut huge amounts of data from your site - AVIF and Webp can reduce file sizes by up to 90%. A funny note - platforms like Vercel actually [provide paid products for image optimization](https://vercel.com/docs/image-optimization)
while Manganis can do this for you, for free, at build time!
Additionally, manganis automatically hashes the images and modifies the generated asset name, allowing for better integration with CDNs and browser caching.
Manganis can handle a wide variety of formats - applying optimizations to assets like CSS, JavaScript, images, videos, and more.
In Dioxus 0.5, we released Manganis in âalphaâ status - and in 0.6 weâre stabilizing it. Weâve adjusted the API, so youâll need to update any existing code that already uses it. Our new implementation is much more reliable, solving many of the bugs users were running into after the 0.5 release.
Our new system leverages _the linker_ to extract asset locations from the compiled binary. This is a rather advanced technique and took a while to get right, but we believe itâs a more robust solution in the long term. If youâre interested in integrating Manganis into your libraries and apps (like say, Bevy!), we have a guide just for that.
Async is a core component of any UI framework. Dioxus provides hooks to handle async state. You can start a future and handle the loading and resolved states within the component:
fn Article() -> Element {
// Use resource starts a future and returns the current state
let article \= use\_resource(fetch\_article);
rsx! { // You can \`match\` the state of the future.
match article() {
Some(article) \=> rsx! { "{article}" },
None \=> rsx! { p { "Loading..." } }
} }
}
fn Article() -> Element {
// Use resource starts a future and returns the current state
let article \= use\_resource(fetch\_article);
rsx! { // You can \`match\` the state of the future.
match article() {
Some(article) \=> rsx! { "{article}" }, None \=> rsx! { p { "Loading..." } } } }
}
This works ok if you have a single future, but it quickly gets messy when combining many futures into one UI:
#\[component\]
fn Article() -> Element {
// Use resource starts a future in the background and returns the current state
let Some(title) \= use\_resource(fetch\_title).cloned() else {
return rsx! { "loading..." }
};
let Some(article) \= use\_resource(fetch\_article).cloned() else {
return rsx! { "loading..." }
};
let Some(category) \= use\_resource(move || article.title()).cloned() else {
return rsx! { "loading..." }
};
rsx! { Title { "{title}" }
Body { category, article }
}
}
#\[component\]
fn Article() -> Element {
// Use resource starts a future in the background and returns the current state
let Some(title) \= use\_resource(fetch\_title).cloned() else {
return rsx! { "loading..." } };
let Some(article) \= use\_resource(fetch\_article).cloned() else {
return rsx! { "loading..." } };
let Some(category) \= use\_resource(move || article.title()).cloned() else {
return rsx! { "loading..." } };
rsx! { Title { "{title}" } Body { category, article }
}
}
In addition to hooks, we need a way to display a different state when async is loading. Dioxus 0.6 introduces a new core primitive for async UI called suspense boundaries. A suspense boundary is a component that renders a placeholder when any child component is loading:
rsx! {
SuspenseBoundary {
fallback: |context: SuspenseContext| rsx! {
// Render a loading placeholder if
// any child component is "suspended"
"Loading..."
}, Article {}
}
}
rsx! {
SuspenseBoundary {
fallback: |context: SuspenseContext| rsx! {
// Render a loading placeholder if
// any child component is "suspended"
"Loading..."
}, Article {}
}
}
In any child component, you can simply bubble up the pending state with `?` to pause rendering until the future is finished:
fn Article() -> Element {
let title \= use\_resource(fetch\_title).suspend()?;
let article \= use\_resource(fetch\_article).suspend()?;
let category \= use\_resource(move || article.title()).suspend()?;
// Since we bubbled up all the pending futures with \`?\` we can just
// handle the happy path in the component
rsx! { Title { "{title}" }
Body { category, article }
}
}
fn Article() -> Element {
let title \= use\_resource(fetch\_title).suspend()?;
let article \= use\_resource(fetch\_article).suspend()?;
let category \= use\_resource(move || article.title()).suspend()?;
// Since we bubbled up all the pending futures with \`?\` we can just
// handle the happy path in the component
rsx! { Title { "{title}" } Body { category, article }
}
}
Along with suspense boundaries, dioxus fullstack also supports streaming each suspense boundary in from the server. Instead of waiting for the whole page to load, dioxus fullstack streams in each chunk with the resolved futures as they finish:
Many of these features are quite cutting-edge and are just now being rolled out in frameworks in the JavaScript ecosystem. Getting the details right for Dioxus was quite difficult. We wanted to support both the fullstack web as well as native desktop and mobile apps. These two platforms often have competing design considerations. Fortunately, suspense also works for desktop and mobile, allowing you to emulate web-like data fetching patterns for native apps.
As part of our work on streaming, we also wanted to support another cutting-edge web feature: incremental static generation (ISG) and its cousin static site generation (SSG).
Static site generation is a technique used by many web frameworks like Jekyll, Hugo, or Zola, to emit static `.html` not reliant on JavaScript. Sites like blogs and portfolios typically use static site generation since platforms like GitHub Pages allow hosting static sites for free. In fact, this very docsite uses Dioxus SSG deployed to GitHub Pages! SSG helps improve SEO and speed up load times for your users.
In Dioxus 0.6, we now support static-site-generation out of the box for all fullstack projects. Simply add a server function to your app called `static_routes` that returns the list of routes that `dx` should generate:
#\[server(endpoint \= "static\_routes", output \= server\_fn::codec::Json)\]
async fn static\_routes() -> Result, ServerFnError> {
Ok(Route::static\_routes()
.into\_iter() .map(|route| route.to\_string())
.collect::>())
}
#\[server(endpoint \= "static\_routes", output \= server\_fn::codec::Json)\]
async fn static\_routes() -> Result, ServerFnError> {
Ok(Route::static\_routes()
.into\_iter() .map(|route| route.to\_string())
.collect::>())
}
Now, when you want to emit your static `.html`, add the `--ssg` flag to `dx build`:
dx build \--platform web \--ssg
dx build \--platform web \--ssg
Static-site-generation is built on a new feature in Dioxus called incremental-site-generation (ISG). ISG is a technique similar to static-site-generation where the server generates pages on demand and caches them on the system filesystem. This allows the server to cache huge amounts of pages (for something like a schoolâs facebook directory or an e-commerce site with thousands of products) that get periodically invalidated. ISG is a somewhat advanced technique but is required to enable when using static-site-generation:
fn main() {
dioxus::LaunchBuilder::new()
.with\_cfg(server\_only! { ServeConfig::builder()
// turn on incremental site generation with the .incremental() method
.incremental(IncrementalRendererConfig::new())
.build() .unwrap() }) .launch(|| { rsx! { Router:: {}
} })
}
fn main() {
dioxus::LaunchBuilder::new()
.with\_cfg(server\_only! { ServeConfig::builder()
// turn on incremental site generation with the .incremental() method
.incremental(IncrementalRendererConfig::new())
.build() .unwrap() }) .launch(|| { rsx! { Router:: {}
} })
}
We will likely be changing these APIs in future releases, but we are eager to let users experiment with these new features to simplify the existing static site setup.
To date, itâs been rather cumbersome to do seemingly simple JavaScript operations in Dioxus. Due to our cross-platform nature, we need to find solutions to simple problems in ways that work for web, desktop, and mobile with a single abstraction.
With Dioxus 0.6, weâre providing special elements under the `document` namespace that make it possible to interact with the HTML `document` object without needing to write extra JavaScript.
Now, to set the `title` of your HTML document, simply use the `document::Title {}` component:
use dioxus::prelude::\*;
use dioxus::document::Title;
fn main() {
dioxus::launch(|| rsx! { Title { "WebAssembly rocks!" }
h1 { "A site dedicated to webassembly" }
})
}
use dioxus::prelude::\*;
use dioxus::document::Title;
fn main() {
dioxus::launch(|| rsx! { Title { "WebAssembly rocks!" } h1 { "A site dedicated to webassembly" } })
}
And accordingly, the title of the page will update:
Similarly, with `Link` , `Stylesheet` , and `Style`, you can include elements that automatically get merged into the documentâs `` element. During server side rendering, these links get collected, deduplicated, and minified. With these built-in `document` components, youâre now guaranteed that your `` element is properly set for pre-loading heavy assets like stylesheets and external JavaScript.
fn app() -> Element {
rsx! { Title { "WebAssembly rocks!" }
Stylesheet { href: asset!("/assets/main.css") }
h1 { "A site dedicated to webassembly" }
}
}
fn app() -> Element {
rsx! { Title { "WebAssembly rocks!" } Stylesheet { href: asset!("/assets/main.css") }
h1 { "A site dedicated to webassembly" } }
}
With this release, weâve made the transition where `Element` is no longer an `Option` but rather a `Result`. This means weâre _finally_ able to open up the use of typical Rust error handling in components:
fn Slider() -> Element {
let value: f64 \= "1234".parse()?;
rsx! { Handle { offset: value }
}
}
fn Slider() -> Element {
let value: f64 \= "1234".parse()?;
rsx! { Handle { offset: value }
}
}
The new `RenderError` acts like anyhowâs `Error` type that can take in any `dyn std::Error` type and propagate it upwards to the nearest error boundary.
fn Input() -> Element {
rsx! { ErrorBoundary {
handle\_error: |errors| rsx! {
h3 { "Oops, we encountered an error.!" }
pre { "Please report {errors:?} to the developers." }
}, Slider {}
} }
}
fn Input() -> Element {
rsx! { ErrorBoundary {
handle\_error: |errors| rsx! {
h3 { "Oops, we encountered an error.!" } pre { "Please report {errors:?} to the developers." } }, Slider {}
} }
}
Whatâs even better: the `?` syntax also works in EventHandlers, so you can quickly add things like server functions to your app without worrying about manual error handling:
fn Counter() -> Element {
let mut data \= use\_signal(|| Data::default());
rsx! { button { onclick: move |\_| async move {
// the \`?\` automatically throws this error upwards
data.set(request\_server\_data().await?);
Ok(())
}, "{data}"
} }
}
fn Counter() -> Element {
let mut data \= use\_signal(|| Data::default());
rsx! { button { onclick: move |\_| async move {
// the \`?\` automatically throws this error upwards
data.set(request\_server\_data().await?);
Ok(())
}, "{data}"
} }
}
This new syntax lets Suspense and HTML-streaming return errors while rendering that donât bring down the entire page.
In addition to being able to access the native event type, Dioxus 0.6 also makes all event handling synchronous. Previously, all event handling in Dioxus had to occur outside the normal browser event handling flow to support platforms like `dioxus-desktop` which need to communicate over an interprocess communication (IPC) layer with the host webview. With this release, weâve finally figured out how to enable blocking communication for `dioxus-desktop` and can finally make event handling synchronous!
As such, we no longer need the special `dioxus_prevent_default` attribute and you can directly call `event.prevent_default()`.
fn Form() -> Element {
rsx! { button { // we no longer need this!
dioxus\_prevent\_default: "onclick",
// instead we can just call .prevent\_default()
onclick: move |evt| {
evt.prevent\_default(); todos.write().remove(&id);
}, } }
}
fn Form() -> Element {
rsx! { button { // we no longer need this!
dioxus\_prevent\_default: "onclick",
// instead we can just call .prevent\_default()
onclick: move |evt| {
evt.prevent\_default(); todos.write().remove(&id);
}, } }
}
This now makes it possible to implement `prevent_default` conditionally which has previously been a limitation with Dioxus. Components like `Link {}` now exhibit behavior exactly aligned with their native counterparts, solving long-standing issues with Dioxus apps.
Thanks to the community, we now have two special handlers _not_ found in the HTML spec: `onvisible` and `onresize`. These handlers are âspecialâ dioxus handlers that automatically sets up an `IntersectionObserver` which previously required JavaScript.
You can now implement rich interactions with little hassle:
fn app() -> Element {
let mut items \= use\_signal(|| 100);
rsx! { // Adding a value will cause the \`div\` to be re-rendered with an extra div
button { onclick: move |\_| items += 1, "Add one" }
div { // This will be called when the \`div\` is resized
onresize: move |data| {
tracing::info!("resized to {:#?}", data.get\_border\_box\_size().unwrap());
},
for x in 0..items() {
div { "{x}" }
} } }
}
fn app() -> Element {
let mut items \= use\_signal(|| 100);
rsx! { // Adding a value will cause the \`div\` to be re-rendered with an extra div
button { onclick: move |\_| items += 1, "Add one" }
div { // This will be called when the \`div\` is resized
onresize: move |data| {
tracing::info!("resized to {:#?}", data.get\_border\_box\_size().unwrap());
},
for x in 0..items() {
div { "{x}" } } } }
}
In addition to `onresize`, we now have a special handler _not_ found in the HTML spec: `onvisible`.
fn app() -> Element {
rsx! { div { onvisible: move |data| {
println!("visible!");
} "Hello world!"
} }
}
fn app() -> Element {
rsx! { div { onvisible: move |data| {
println!("visible!");
} "Hello world!"
} }
}
This makes it possible to add rich animations to your app without needing to write custom JavaScript.
This release also brings the "child window" feature for Dioxus desktop which lets you overlay native Dioxus apps on existing windows. This makes it simple to integrate Dioxus as an overlay over other renderers like WGPU and OpenGL:
We added support for web and mobile with `dx bundle`. Previously, `dx bundle` only worked for desktop apps. Now you can bundle for a wide variety of targets:
* macOS (.app, .dmg)
* Windows (.exe, .msi)
* Linux (.deb, .rpm, .appimage)
* Android (.apk)
* iOS (.ipa, .app)
* Web (.appimage, /public folder)
As part of our overhaul with the CLI, weâre also shipping a `json-output` mode. Now, when you pass `--json-output` to Dioxus commands, you will receive the logging in json format:
This is particularly important for users of `dx bundle` who want to automatically upload the their bundles to their hosting provider of choice. You can easily combine the output of `dx` with a tool like `jq` to extract important information like bundle outputs with a simple one-liner:
Dioxus 0.6 ships with three new starter templates for cross-platform apps. Each template is a fully-featured, production-ready app that you can use as a starting point for your own Dioxus apps.
* Bare-Bones: A bare-bones starter template with no styling, assets, or structure.
* Jumpstart: A starter template with a basic structure, components, and a few pages.
* Workspace: A starter template with separate crates for web, desktop, and mobile.
These are baked directly into the `dx new` command - simply run `dx new` and follow the prompts to select the template you want.
As usual with these large releases, Dioxus 0.6 features a rather sizable overhaul to the documentation. Weâve completely overhauled the tutorial to be less heavy on code. The new tutorial focuses on basics like including assets and deploying to production.
The docsite now includes all âmodernâ versions of Dioxus inline: 0.3, 0.4, 0.5, and 0.6 are all accessible under the same top-level website. Previously, we linked out to different MDbooks which eventually became a hassle. Now, you can simply switch between each version inline:
The inline version switcher means weâll now be able to publish documentation for alpha releases of Dioxus, hopefully making your life easier as we ship new features for the future. The new docs also feature small quality-of-life upgrades like breadcrumbs:
as well as new codeblocks with interactive examples:
While working on the new hot-reloading engine, we experimented with adding proper hot-reloading of Rust code to Dioxus apps. The work here was inspired by Andrew Kelleyâs âin-place-binary-patchingâ goal for Zig. Unfortunately, we didnât have a chance to productionize the prototype for this release (way too many features already!) but we did put together a [small prototype](https://github.com/jkelleyrtp/ipbp)
:
We likely wonât have the time to ship true Rust hot-reloading in 0.7, but stay tuned for early next year!
Not every change gets a particularly large section in the release notes, but we did land several new features and refactors.
* System tray support: we now have proper support for System Trays again, thanks to a wonderful community contribution.
* Custom event loops: you can provide your own event loop, making it possible to use Dioxus in contexts where you already have other windows.
* `dioxus-document`: we split out our `document` abstraction so any renderer can implement the `Document` trait to integrate with `Title {}`, `Script {}` , and `eval`
* `dioxus-history`: we also split out our `history` abstraction so other renderers can benefit from `Link` and `Router` without needing a dedicated feature flag on `dioxus-router`
* `eval` API was simplified to allow `.recv::().await` on evals, making interoperating with JavaScript easier.
* `dx fmt` now supports `#[rustfmt::skip]` attributes, respects `rustfmt.toml` settings, and is generally more reliable
Generally there are few huge breaking changes in this release. However, we did change a few APIs that might break your existing apps but are easy to fix.
* `asset!()` syntax changes
* `eval()` API small changes
* migrating to `prevent_default()`
* migrating from VNode::None to `rsx! {}` for empty nodes
Weâve assembled a [migration guide](https://dioxuslabs.com/learn/0.6/migration/)
to help.
Thatâs it for this release! We addressed countless issues including bundling bugs, spurious hot-reloads, and compatibility with unusual platforms and editors.
Dioxus 0.6 has been in alpha for quite a while, and weâre very thankful for all the testing the community has done to make this the most polished release yet. Itâs quite difficult to run a large open source project such a wide scope. This release took _much_ longer to get out than we wanted - consuming two release cycles instead of just one.
We focused hard this release to polish up as many rough edges as possible. Our continuous integration and deployment is in a much nicer place. Weâre finally able to release nightly versions of documentation and the alpha release system has worked well for users eager to test out new features and bug fixes.
Unfortunately, this release contained many connected pieces which made it hard to release incrementally. Systems like assets integrate tightly with CLI tooling and cross-platform support: to get one configuration right you need to test them all. With 0.6 behind us, the future seems much more âincrementalâ which should let us release major versions with faster cadence.
We plan to keep 0.6 around for a while. Instead of shipping new features for a while, we're excited to make tutorial videos, write documentation, fix bugs, improve performance, and work with the community. The Dioxus team wants to spend time building our own apps!
That being said, we do have a few major items planned for Dioxus 0.7 and beyond:
* Rust hot-reloading with binary patching
* Integrating wasm bundle splitting with the router
* `dx deploy` to a hosted deploy platform (Fly.io, AWS, Cloudflare, etc.)
Weâre also hiring - if you want to come build Dioxus with me in San Francisco (or remote) please reach out!
We want to extend a huge thank-you to everyone who helped test and improve this release. We saw an incredible number of contributors fix bugs and add features. Special thanks to:
[@ASR-ASU](https://github.com/ASR-ASU)
- [@Aandreba](https://github.com/Aandreba)
- [@Andrew15-5](https://github.com/Andrew15-5)
- [@DogeDark](https://github.com/DogeDark)
- [@Klemen2](https://github.com/Klemen2)
- [@LeWimbes](https://github.com/LeWimbes)
- [@LeoDog896](https://github.com/LeoDog896)
- [@MrGVSV](https://github.com/MrGVSV)
- [@Rahul721999](https://github.com/Rahul721999)
- [@Septimus](https://github.com/Septimus)
- [@Tahinli](https://github.com/Tahinli)
- [@WilliamRagstad](https://github.com/WilliamRagstad)
- [@ahqsoftwares](https://github.com/ahqsoftwares)
- [@airblast-dev](https://github.com/airblast-dev)
- [@alilosoft](https://github.com/alilosoft)
- [@azamara](https://github.com/azamara)
- [@chungwong](https://github.com/chungwong)
- [@d3rpp](https://github.com/d3rpp)
- [@daixiwen](https://github.com/daixiwen)
- [@dependabot](https://github.com/dependabot)
- [@ealmloff](https://github.com/ealmloff)
- [@hackartists](https://github.com/hackartists)
- [@hardBSDk](https://github.com/hardBSDk)
- [@houseme](https://github.com/houseme)
- [@i123iu](https://github.com/i123iu)
- [@ilaborie](https://github.com/ilaborie)
- [@imgurbot12](https://github.com/imgurbot12)
- [@jacklund](https://github.com/jacklund)
- [@jingchanglu](https://github.com/jingchanglu)
- [@luveti](https://github.com/luveti)
- [@marc2332](https://github.com/marc2332)
- [@matthunz](https://github.com/matthunz)
- [@nayo0513](https://github.com/nayo0513)
- [@opensource-inemar-net](https://github.com/opensource-inemar-net)
- [@oskardotglobal](https://github.com/oskardotglobal)
- [@panglars](https://github.com/panglars)
- [@pyrrho](https://github.com/pyrrho)
- [@ribelo](https://github.com/ribelo)
- [@rogusdev](https://github.com/rogusdev)
- [@ryo33](https://github.com/ryo33)
- [@samtay](https://github.com/samtay)
- [@sknauff](https://github.com/sknauff)
- [@srid](https://github.com/srid)
- [@tigerros](https://github.com/tigerros)
- [@tpoliaw](https://github.com/tpoliaw)
- [@uzytkownik](https://github.com/uzytkownik)
On this page
------------
* [Interactive Command Line Tools](https://dioxuslabs.com/blog/release-060/#interactive-command-line-tools)
* [Android and iOS support for dx serve](https://dioxuslabs.com/blog/release-060/#android-and-ios-support-for-dx-serve)
* [Completely Revamped Hot-Reloading](https://dioxuslabs.com/blog/release-060/#completely-revamped-hot-reloading)
* [Completely Revamped Autocomplete](https://dioxuslabs.com/blog/release-060/#completely-revamped-autocomplete)
* [Inline WASM stacktraces and tracing integration](https://dioxuslabs.com/blog/release-060/#inline-wasm-stacktraces-and-tracing-integration)
* [Toasts and Loading Screens](https://dioxuslabs.com/blog/release-060/#toasts-and-loading-screens)
* [Fullstack Desktop and Mobile](https://dioxuslabs.com/blog/release-060/#fullstack-desktop-and-mobile)
* [Stabilizing Manganis asset!() system](https://dioxuslabs.com/blog/release-060/#stabilizing-manganis-asset-system)
* [Suspense and HTML Streaming for the Web](https://dioxuslabs.com/blog/release-060/#suspense-and-html-streaming-for-the-web)
* [Static Site Generation and ISG](https://dioxuslabs.com/blog/release-060/#static-site-generation-and-isg)
* [Document Elements: Title {} , Link {} , Stylesheet , and Meta {}](https://dioxuslabs.com/blog/release-060/#document-elements-title---link---stylesheet--and-meta-)
* [Question Mark Error Handling](https://dioxuslabs.com/blog/release-060/#question-mark-error-handling)
* [Synchronous prevent\_default](https://dioxuslabs.com/blog/release-060/#synchronous-prevent-default)
* [Tracking size with onresize](https://dioxuslabs.com/blog/release-060/#tracking-size-with-onresize)
* [Tracking visibility with onvisible](https://dioxuslabs.com/blog/release-060/#tracking-visibility-with-onvisible)
* [Hybrid WGPU Overlays](https://dioxuslabs.com/blog/release-060/#hybrid-wgpu-overlays)
* [Web, iOS, and Android bundle support](https://dioxuslabs.com/blog/release-060/#web-ios-and-android-bundle-support)
* [JSON Output for CI / CLI](https://dioxuslabs.com/blog/release-060/#json-output-for-ci--cli)
* [New Starter Templates](https://dioxuslabs.com/blog/release-060/#new-starter-templates)
* [Nightly Docs, Tutorials, and New Guides](https://dioxuslabs.com/blog/release-060/#nightly-docs-tutorials-and-new-guides)
* [Preview of In-Place Binary Patching](https://dioxuslabs.com/blog/release-060/#preview-of-in-place-binary-patching)
* [Smaller changes:](https://dioxuslabs.com/blog/release-060/#smaller-changes)
* [Upgrading from 0.5 to 0.6](https://dioxuslabs.com/blog/release-060/#upgrading-from-05-to-06)
* [Conclusion](https://dioxuslabs.com/blog/release-060/#conclusion)
* [Thanks to the community!](https://dioxuslabs.com/blog/release-060/#thanks-to-the-community)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
[Back to blog](https://dioxuslabs.com/blog/)
Dioxus 0.1
==========
Release Notes - Jonathan Kelley
### After months of work, we're very excited to release the first version of Dioxus! Dioxus is a new library for building interactive user interfaces with Rust.
> Jan 3, 2022
> [@jkelleyrtp](https://github.com/jkelleyrtp)
> , thanks [@alexkirsz](https://github.com/alexkirsz)
After many months of work, we're very excited to release the first version of Dioxus!
Dioxus is a new library for building interactive user interfaces (GUI) with Rust. It is built around a Virtual DOM, making it portable for the web, desktop, server, mobile, and more.
Dioxus has the following design goals:
* **Familiar**: Offer a React-like mental model and API surface
* **Robust**: Avoid runtime bugs by moving rules and error handling into the type system
* **Performant**: Scale to the largest apps and the largest teams
* **Productive**: Comprehensive inline documentation, fast recompiles, and deeply integrated tooling
* **Extensible**: Reusable hooks and components that work on every platform
Dioxus is designed to be familiar for developers already comfortable with React paradigms. Our goal is to ensure a smooth transition from TypeScript/React without having to learn any major new concepts.
To give you an idea of what Dioxus looks like, here's a simple counter app:
use dioxus::prelude::\*;
fn main() {
dioxus::desktop::launch(app)
}
fn app(cx: Scope) -> Element {
let mut count \= use\_state(&cx, || 0);
cx.render(rsx! { h1 { "Count: {count}" }
button { onclick: move |\_| count += 1, "+" }
button { onclick: move |\_| count \-= 1, "-" }
})
}
use dioxus::prelude::\*;
fn main() {
dioxus::desktop::launch(app)
}
fn app(cx: Scope) -> Element {
let mut count \= use\_state(&cx, || 0);
cx.render(rsx! { h1 { "Count: {count}" } button { onclick: move |\_| count += 1, "+" } button { onclick: move |\_| count \-= 1, "-" } })
}
This simple counter is a complete desktop application, running at native speeds on a native thread. Dioxus automatically shuttles all events from the WebView runtime into the application code. In our app, we can interact natively with system APIs, run multi-threaded code, and do anything a regular native Rust application might do. Running `cargo build --release` will compile a portable binary that looks and feels the same on Windows, macOS, and Linux. We can then use `cargo-bundle` to bundle our binary into a native `.app`/ `.exe`/ `.deb`.
Dioxus supports many of the same features React does including:
* Server-side-rendering, pre-rendering, and hydration
* Mobile, desktop, and web support
* Suspense, fibers, coroutines, and error handling
* Hooks, first-class state management, components
* Fragments, conditional rendering, and custom elements
However, some things are different in Dioxus:
* Automatic memoization (opt-out rather than opt-in)
* No effects - effectual code can only originate from actions or coroutines
* Suspense is implemented as hooks - _not_ deeply ingrained within Dioxus Core
* Async code is _explicit_ with a preference for _coroutines_ instead
As a demo, here's our teaser example running on all our current supported platforms:
This very site is built with Dioxus, and the source code is available [here](https://github.com/dioxuslabs/docsite)
.
To get started with Dioxus, check out any of the "Getting Started" guides for your platform of choice, or check out the GitHub Repository for more details.
* [Getting Started with Dioxus](https://dioxuslabs.com/docs/0.3/guide/en)
* [Getting Started with Web](https://dioxuslabs.com/reference/web)
* [Getting Started with Desktop](https://dioxuslabs.com/reference/desktop)
* [Getting Started with Mobile](https://dioxuslabs.com/reference/mobile)
* [Getting Started with SSR](https://dioxuslabs.com/reference/ssr)
* [File explorer desktop app](https://github.com/dioxuslabs/example-projects)
* [WiFi scanner desktop app](https://github.com/dioxuslabs/example-projects)
* [Dog CEO API Search](https://github.com/dioxuslabs/example-projects)
* [TodoMVC Mobile App](https://github.com/dioxuslabs/example-projects)
* [E-Commerce Liveview App](https://github.com/dioxuslabs/example-projects)
We believe that Rust's ability to write high-level and statically typed code should make it easier for frontend teams to take on even the most ambitious of projects. Rust projects can be refactored fearlessly: the powerful type system prevents an entire class of bugs at compile-time. No more `cannot read property of undefined` ever again! With Rust, all errors must be accounted for at compile time. You cannot ship an app that does not â in some way â handle its errors.
TypeScript is still fundamentally JavaScript. If you've written enough TypeScript, you might be bogged down with lots of configuration options, lack of proper support for "go-to-source," or incorrect ad-hoc typing. With Rust, strong types are built-in, saving tons of headache like `cannot read property of undefined`.
By using Rust, we gain:
* Strong types for every library
* Immutability by default
* A simple and intuitive module system
* Integrated documentation (go to source actually goes to source instead of the `.d.ts` file)
* Advanced pattern matching
* Clean, efficient, composable iterators
* Inline built-in unit/integration testing
* High quality error handling
* Flexible standard library and traits
* Powerful macro system
* Access to the [crates.io](https://crates.io/)
ecosystem
Dioxus itself leverages this platform to provide the following guarantees:
* Correct use of immutable data structures
* Guaranteed handling of errors and null-values in components
* Native performance on mobile
* Direct access to system IO
And much more. Dioxus makes Rust apps just as fast to write as React apps, but affords more robustness, giving your frontend team greater confidence in making big changes in shorter timespans.
Semantically, TypeScript-React and Rust-Dioxus are very similar. In TypeScript, we would declare a simple component as:
type CardProps = {
title: string; paragraph: string;
};
const Card: FunctionComponent = (props) => {
let \[count, set\_count\] = use\_state(0); return ( );
};
type CardProps = {
title: string; paragraph: string;
};
const Card: FunctionComponent = (props) => {
let \[count, set\_count\] = use\_state(0); return ( );
};
In Dioxus, we would define the same component in a similar fashion:
#\[derive(Props, PartialEq)\]
struct CardProps {
title: String,
paragraph: String
}
static Card: Component \= |cx| {
let mut count \= use\_state(&cx, || 0);
cx.render(rsx!(
aside {
h2 { "{cx.props.title}" }
p { "{cx.props.paragraph}" }
button { onclick: move |\_| count+=1, "Count: {count}" }
}
))
};
#\[derive(Props, PartialEq)\]
struct CardProps {
title: String,
paragraph: String
}
static Card: Component \= |cx| {
let mut count \= use\_state(&cx, || 0);
cx.render(rsx!(
aside {
h2 { "{cx.props.title}" }
p { "{cx.props.paragraph}" }
button { onclick: move |\_| count+=1, "Count: {count}" }
}
))
};
However, we recognize that not every project needs Rust - many are fine with JavaScript! We also acknowledge that Rust/Wasm/Dioxus does not fix "everything that is wrong with frontend development." There are always going to be new patterns, frameworks, and languages that solve these problems better than Rust and Dioxus.
As a general rule of thumb, Dioxus is for you if:
* your app will become very large
* you need to share code across many platforms
* you want a fast way to build for desktop
* you want to avoid electron or need direct access to hardware
* you're tired of JavaScript tooling
Today, to publish a Dioxus app, you don't need NPM/WebPack/Parcel/etc. Dioxus simply builds with cargo, and for web builds, Dioxus happily works with the popular [trunk](https://trunkrs.dev/)
project.
Here, we'll dive into some features of Dioxus and why it's so fun to use. The [guide](https://dioxuslabs.com/docs/0.3/guide/en/)
serves as a deeper and more comprehensive look at what Dioxus can do.
To start a new project, all you need is Cargo, which comes with Rust. For a simple desktop app, all we'll need is the `dioxus` crate with the appropriate `desktop` feature. We start by initializing a new binary crate:
$ cargo init dioxus\_example
$ cd dioxus\_example
$ cargo init dioxus\_example
$ cd dioxus\_example
We then add a dependancy on Dioxus to the `Cargo.toml` file, with the "desktop" feature enabled:
\[dependencies\]
dioxus \= { version \= "\*", features \= \["desktop"\] }
\[dependencies\]
dioxus \= { version \= "\*", features \= \["desktop"\] }
We can add our counter from above.
use dioxus::prelude::\*;
fn main() {
dioxus::desktop::launch(app)
}
fn app(cx: Scope) -> Element {
let mut count \= use\_state(&cx, || 0);
cx.render(rsx! { h1 { "Count: {count}" }
button { onclick: move |\_| count += 1, "+" }
button { onclick: move |\_| count \-= 1, "-" }
})
}
use dioxus::prelude::\*;
fn main() {
dioxus::desktop::launch(app)
}
fn app(cx: Scope) -> Element {
let mut count \= use\_state(&cx, || 0);
cx.render(rsx! { h1 { "Count: {count}" } button { onclick: move |\_| count += 1, "+" } button { onclick: move |\_| count \-= 1, "-" } })
}
And voilĂ ! We can `cargo run` our app
Dioxus ships with a templating macro called RSX, a spin on React's JSX. RSX is very similar to regular struct syntax for Rust so it integrates well with your IDE. If used with [Rust-Analyzer](https://github.com/rust-analyzer/rust-analyzer)
(not tested anywhere else) RSX supports code-folding, block selection, bracket pair colorizing, autocompletion, symbol renaming â pretty much anything you would expect from writing regular struct-style code.
rsx! {
div { "Hello world" }
button {
onclick: move |\_| log::info!("button pressed"),
"Press me"
}
}
rsx! {
div { "Hello world" }
button {
onclick: move |\_| log::info!("button pressed"),
"Press me"
}
}
If macros aren't your style, you can always drop down to the factory API:
LazyNodes::new(|f| {
f.fragment(\[\
f.element(div, \[f.text("hello world")\], \[\], None, None)\
f.element(\
button,\
\[f.text("Press Me")\],\
\[on::click(move |\_| log::info!("button pressed"))\],\
None,\
None\
)\
\])
})
LazyNodes::new(|f| {
f.fragment(\[\
f.element(div, \[f.text("hello world")\], \[\], None, None)\
f.element(\
button,\
\[f.text("Press Me")\],\
\[on::click(move |\_| log::info!("button pressed"))\],\
None,\
None\
)\
\])
})
The `rsx!` macro generates idiomatic Rust code that uses the factory API â no different than what you'd write by hand yourself.
To make it easier to work with RSX, we've built a small [VSCode extension](https://github.com/DioxusLabs/studio)
with useful utilities. This extension provides a command that converts a selected block of HTML into RSX so you can easily reuse existing web templates.
Many of the Rust UI frameworks are particularly difficult to work with. Even the ones branded as "ergonomic" are quite challenging to in comparison to TSX/JSX. With Dioxus, we've innovated on a number of Rust patterns to deliver a framework that is actually enjoyable to develop in.
For example, many Rust frameworks require you to clone your data in for _every_ closure and handler you use. This can get really clumsy for large apps.
div()
.children(\[\
button().onclick(cloned!(name, date, age, description \=> move |evt| { /\* \*/ })\
button().onclick(cloned!(name, date, age, description \=> move |evt| { /\* \*/ })\
button().onclick(cloned!(name, date, age, description \=> move |evt| { /\* \*/ })\
\])
div()
.children(\[\
button().onclick(cloned!(name, date, age, description \=> move |evt| { /\* \*/ })\
button().onclick(cloned!(name, date, age, description \=> move |evt| { /\* \*/ })\
button().onclick(cloned!(name, date, age, description \=> move |evt| { /\* \*/ })\
\])
Dioxus understands the lifetimes of data borrowed from `Scope`, so you can safely return any borrowed data without declaring explicit captures. Hook handles all implement `Copy` so they can be shared between listeners without any ceremony.
let name \= use\_state(&cx, || "asd");
rsx! {
div {
button { onclick: move |\_| name.set("abc") }
button { onclick: move |\_| name.set("def") }
button { onclick: move |\_| name.set("ghi") }
}
}
let name \= use\_state(&cx, || "asd");
rsx! {
div {
button { onclick: move |\_| name.set("abc") }
button { onclick: move |\_| name.set("def") }
button { onclick: move |\_| name.set("ghi") }
}
}
Because we know the lifetime of your handlers, we can also expose this to children. No other Rust frameworks let us share borrowed state through the tree, forcing use of Rc/Arc everywhere. With Dioxus, all the Rc/Arc magic is tucked away in hooks, and just beautiful borrowed interfaces are exposed to your code. You don't need to know how Rc/RefCell work to build a competent Dioxus app.
fn app(cx: Scope) -> Element {
let name \= use\_state(&cx, || "asd");
cx.render(rsx!{
Button { name: name }
})
}
#\[derive(Props)\]
struct ButtonProps<'a\> {
name: UseState<'a, &'static str\>
}
fn Button<'a\>(cx: Scope<'a, Childprops<'a\>>) -> Element {
cx.render(rsx!{
button {
onclick: move |\_| cx.props.name.set("bob")
}
})
}
fn app(cx: Scope) -> Element {
let name \= use\_state(&cx, || "asd");
cx.render(rsx!{
Button { name: name }
})
}
#\[derive(Props)\]
struct ButtonProps<'a\> {
name: UseState<'a, &'static str\>
}
fn Button<'a\>(cx: Scope<'a, Childprops<'a\>>) -> Element {
cx.render(rsx!{
button {
onclick: move |\_| cx.props.name.set("bob")
}
})
}
There's _way_ more to this story, but hopefully we've convinced you that Dioxus' DX somewhat approximates JSX/React.
Note: all IDE-related features have only been tested with [Rust-Analyzer](https://github.com/rust-analyzer/rust-analyzer)
.
Dioxus code operates pleasantly with your IDE. For starters, most elements are documented through the Rustdoc system. A quick summary of the MDN docs is always under your finger tips:
Dioxus also wraps platform-specific events with a custom synthetic event system. This means events enjoy proper autocomplete and documentation, unlike [Yew](https://yew.rs/)
which currently relies on [web-sys](https://crates.io/crates/web-sys)
with incomplete IDE support:
Even element attributes and event handlers have top-notch documentation!
The `rsx!` macro also benefits from code folding, batch renaming, and block selection, making most basic code navigation and completion tasks a breeze.
Furthermore, the `rsx!` macro itself is documented, so if you ever forget how to use a certain feature, the documentation remains close at hand:
We spent a ton of time on this and we hope you enjoy it!
We take the performance of Dioxus seriously. Instead of resolving to "good enough," Dioxus is designed to push the limits of what a declarative React-like framework can achieve. Dioxus is designed with multi-tenancy in mind: a single machine should be able to run thousands of simultaneous low-latency LiveView apps without skipping a beat. To accomplish this goal we've implemented a large number of optimizations:
* Usage of bump memory allocators and double-buffering
* Compile-time hashing of templates
* Automatic component memoization
* Fiber-like scheduler
* DOM Patch Batching
Dioxus is humbly built off the work done by [Dodrio](https://github.com/fitzgen/dodrio)
, a now-archived research project by fitzgen exploring the use of bump allocators in UI frameworks.
Dioxus is _substantially_ more performant than many of the other Rust DOM-based UI libraries (Yew/Percy) and is _significantly_ more performant than React - roughly competitive with InfernoJS. While not as performant as libraries like SolidJS/Sycamore, Dioxus imposes roughly a ~ 3% overhead over DOM patching, so it's _plenty_ fast.
Weâve mentioned before that Dioxus works practically anywhere that Rust does. When running natively as a desktop or mobile app, your Dioxus code will run on its own thread, not inside of a web runtime. This means you can access hardware, file system, and platform APIs directly without needing to go through a shim layer. In our examples, we feature a [file explorer app](https://github.com/DioxusLabs/example-projects/tree/master/file-explorer)
and [WiFi scanner app](https://github.com/DioxusLabs/example-projects/tree/master/wifi-scanner)
where platform access occurs inside an asynchronous multithreaded coroutine. This solves the problem faced by React Native and other cross-platform toolkits where JavaScript apps incur a massive performance penalty with substantial maintenance overhead associated with platform API shims.
A desktop app:
[](https://github.com/DioxusLabs/example-projects/blob/master/file-explorer)
A mobile app:
[](https://github.com/DioxusLabs/example-projects/blob/master/ios_demo)
However, be warned that mobile is currently considered very experimental and there will likely be quirks. Dioxus is leveraging the work done by the [Tauri](https://github.com/tauri-apps/tauri)
team to enable mobile support, and mobile support isn't technically complete in Tauri yet.
iOS should be supported out of the box, but Android support will take custom some boilerplate that hasn't been completely figured out. If you're interested in contributing to Dioxus, improving mobile support would be extremely helpful.
Yes, you can even build terminal user interfaces with Dioxus. Full support is still a work in progress, but the foundation is there.
[](https://github.com/dioxusLabs/rink)
There are a bunch of things we didn't talk about here. Check out the guide for more information, or peruse the examples and reference for more context.
* Jank-free rendering with fiber scheduler
* Support for borrowed props
* Conditional rendering
* CSS/Styling/Inline style support
* Support for inline Context Providing/Consuming
* First-class global state management
For a quick glance at party with React, check out the [Readme on Github](https://github.com/DioxusLabs/dioxus#parity-with-react)
.
The world of Rust on the frontend is barely explored. Given the performance, ergonomics, and portability of Rust/Dioxus, we expect there to be a ton of different applications where having a React-like toolkit running natively can enable things previously considered impossible.
In the coming weeks, our plan is to finish the remaining outstanding features where Dioxus is lacking in comparison to React:
* Transition effects for Suspense
* Micro-optimizations and better cross-platform/browser bug mitigations
* Heuristics to guide the diffing algorithm
* Better support for subtree memoization (signals, etc.)
* More thorough documentation, fleshing out sore spots
We also need some help in important crates currently missing:
* First class cross-platform router (currently in progress)
* An extension to DioxusStudio that enables lazy bundling of static assets
* Animation library (see [React Spring](https://react-spring.io/)
, [Framer Motion](https://www.framer.com/motion/)
)
* A [TUI renderer for Dioxus](https://github.com/dioxuslabs/rink)
(see [Ink](https://github.com/vadimdemedes/ink)
)
And finally, some bigger, forward-thinking projects that are too big for a one-person team:
* Completely native renderer for the Dioxus Virtual DOM (see [Flutter](https://flutter.dev/)
)
* Better support for LiveView
* Code-splitting
* 3D renderer (see [react-three-fiber](https://github.com/pmndrs/react-three-fiber)
)
Stay tuned for our next article, which will go over some of the optimization techniques that went into making Dioxus blazing fast.
The future is bright for Rust frontends! If you'd like to get involved, we have a [Discord server](https://discord.gg/XgGxMSkvUM)
, [a subreddit](http://reddit.com/r/dioxus)
, and [GitHub discussion pages](https://github.com/DioxusLabs/dioxus/discussions)
.
Let us know what you build!
Check out the original `/r/rust` thread here.
On this page
------------
* [Show me some examples of what can be built!](https://dioxuslabs.com/blog/introducing-dioxus/#show-me-some-examples-of-what-can-be-built)
* [Why should I use Rust and Dioxus for frontend?](https://dioxuslabs.com/blog/introducing-dioxus/#why-should-i-use-rust-and-dioxus-for-frontend)
* [Difference from TypeScript/React:](https://dioxuslabs.com/blog/introducing-dioxus/#difference-from-typescriptreact)
* [Show me more](https://dioxuslabs.com/blog/introducing-dioxus/#show-me-more)
* [Building a new project is simple](https://dioxuslabs.com/blog/introducing-dioxus/#building-a-new-project-is-simple)
* [Support for JSX-style templating](https://dioxuslabs.com/blog/introducing-dioxus/#support-for-jsx-style-templating)
* [Dioxus prioritizes developer experience](https://dioxuslabs.com/blog/introducing-dioxus/#dioxus-prioritizes-developer-experience)
* [Dioxus is perfected for the IDE](https://dioxuslabs.com/blog/introducing-dioxus/#dioxus-is-perfected-for-the-ide)
* [Dioxus is extremely fast](https://dioxuslabs.com/blog/introducing-dioxus/#dioxus-is-extremely-fast)
* [Works on Desktop and Mobile](https://dioxuslabs.com/blog/introducing-dioxus/#works-on-desktop-and-mobile)
* [Did someone say TUI support?](https://dioxuslabs.com/blog/introducing-dioxus/#did-someone-say-tui-support)
* [Things we didn't cover:](https://dioxuslabs.com/blog/introducing-dioxus/#things-we-didnt-cover)
* [What's on the roadmap?](https://dioxuslabs.com/blog/introducing-dioxus/#whats-on-the-roadmap)
* [Community](https://dioxuslabs.com/blog/introducing-dioxus/#community)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
Almost all apps need a remote server to store and update user data. Dioxus provides a number of fullstack utilities for building your app's server alongisde the client. With Dioxus Fullstack, you can build _both_ your app's frontend and backend entirely in Rust!
Dioxus Fullstack deeply integrates with the popular [Axum](https://docs.rs/axum/latest/axum/)
framework, making it easy to quickly add complex functionality to your app, including:
* **Server-Side-Rendering**: Render HTML on the server and hydrate it on the client
* **Server Functions**: Type-safe Axum HTTP endpoints directly callable from the client
* **Hot-Reload**: Rapid Rust hot-reload during development powered by [subsecond](https://crates.io/crates/subsecond)
* **Typed Routing**: Easily extract queries and paths from the URL
* **Multi-part Forms**: Capture multipart form data from the client into typed Rust structs
* **Binary Streams**: Easily add file upload/download backend capability
* **SSE and WebSockets**: Complex, stateful datatypes for server communication
* **Asset Management**: Automatically optimizes assets for deployment to CDNs
* **WASM Support**: Deploy to WASM-based providers like Cloudflare Workers
* **Bundle Splitting**: Split apart large WASM blobs on a per-route basis
* **Static Site Generation**: Generate HTML markup perfect for blogs and static sites
Currently, Dioxus Fullstack does not provide built-in utilities for things like Databases, Caches, Sessions, and Mailers. Our current focus is to finish polishing the fullstack integration before branching out into a more "complete" fullstack solution. You'll need to pull in 3rd-party crates like `Sqlx` and `tower-sessions` to use such features. To help, we provide a [few examples in the Dioxus GitHub repo](https://github.com/DioxusLabs/dioxus/tree/main/examples/07-fullstack)
to get started.
With Dioxus, our goal is to maximize your developer productivity. Dioxus Fullstack ships with full Rust hot-reload support built-in thanks to our hot-patch engine [subsecond](https://crates.io/crates/subsecond)
. Subsecond uses advanced assembly and linker techniques to allow modifying Rust functions at runtime. You can add new endpoints, pages, and logic to your app without manually rebuilding.
Subsecond currently has a few limitations. For the best experience, we recommend only modifying code in the "tip" of your app. Note that code that runs only once will not be hot-reloadable and will require a restart of the app.
Dioxus Fullstack provides an easy way to communicate with the server from any client. Server functions let you define a function that always runs on the server. When you call that function from the client, Dioxus will automatically serialize the arguments, send them to the server, run the function on the server, serialize the return value, and send it back to the client.
// The body of the function will always run on the server so we can do server-side operations like database queries
#\[get("/api/dog/{breed}")\]
async fn fetch\_dog(breed: String) -> Result {
DB.execute("SELECT url FROM dogs WHERE id = ?1", &breed)
}
// The body of the function will always run on the server so we can do server-side operations like database queries
#\[get("/api/dog/{breed}")\]
async fn fetch\_dog(breed: String) -> Result {
DB.execute("SELECT url FROM dogs WHERE id = ?1", &breed)
}
We can use the results of server functions during server-side-rendering along with hydration:
let url \= use\_loader(|| fetch\_dog("poodle".to\_string()))?;
rsx! {
img { src: "{url}", alt: "A cute dog" }
}
let url \= use\_loader(|| fetch\_dog("poodle".to\_string()))?;
rsx! {
img { src: "{url}", alt: "A cute dog" }
}
Server functions are described in more detail in the [server functions guide](https://dioxuslabs.com/learn/0.7/essentials/fullstack/server_functions)
. In addition to this guide, you can find more examples of fullstack apps in the [examples directory](https://github.com/DioxusLabs/dioxus/tree/main/examples)
.
Dioxus Fullstack comes with full support for Axum, and with it, special client handlers for things like WebSockets and HTTP Streams. We provide a number of utilities like `use_websocket` to reactively manage these resources on the client.
Our `Streaming` wrapper allows you to easily send arbitrary bytes, text, JSON, and chunked file contents to and from the server. Easily roll your own hybrid client-server types by implementing `IntoRequest` and `FromResponse`!
Dioxus Fullstack allows you to render your app on the server, speeding up load times for your users and improving your site's discoverability for search engines like Google. Server-side-rendering (SSR) allows you to render your app's initial HTML on the server, sending a fully-formed HTML document to the client. The client can then "hydrate" the HTML into a fully-interactive app that can continue running on the client without requiring a persistant server connection.
Because Dioxus Fullstack integrates with our build tool DX, your fullstack apps come pre-optimized for deploying onto infrastructure like content-distribution-networks (CDNs). CDNs reduce your bandwidth usage and speed up your app's time-to-first byte for maximum performance. Assets bundled with DX are hashed, letting the client infinitely cache their contents.
[PREVIOUSSuspense](https://dioxuslabs.com/learn/0.7/essentials/basics/suspense)
[NEXTProject Setup](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup)
On this page
------------
* [Hot-Reload](https://dioxuslabs.com/learn/0.7/essentials/fullstack/#hot-reload)
* [Server functions](https://dioxuslabs.com/learn/0.7/essentials/fullstack/#server-functions)
* [Websockets and Streams](https://dioxuslabs.com/learn/0.7/essentials/fullstack/#websockets-and-streams)
* [Server Side Rendering](https://dioxuslabs.com/learn/0.7/essentials/fullstack/#server-side-rendering)
* [Assets](https://dioxuslabs.com/learn/0.7/essentials/fullstack/#assets)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Advanced Topics](https://dioxuslabs.com/learn/0.7/essentials/advanced/)
This section covers a variety of advanced topics you may find useful as your dioxus app grows. It covers topic from organizing your app with custom hooks to breaking out of dioxus with effects.
* [Custom hooks](https://dioxuslabs.com/learn/0.7/essentials/advanced/custom_hooks)
In addition to the built-in hooks, Dioxus lets you create your own custom hooks to encapsulate logic you can use throughout your components.
* [Component Lifecycle](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle)
Every component in dioxus follows the same, mount, diff and drop lifecycle. This section covers how to hook into that lifecycle.
* [Breaking Out](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out)
Sometimes the apis provided by dioxus aren't enough. This section covers how to break out of dioxus and use your own apis to manipulate the DOM or call JS functions.
[PREVIOUSLayouts](https://dioxuslabs.com/learn/0.7/essentials/router/layouts)
[NEXTCustom Hooks](https://dioxuslabs.com/learn/0.7/essentials/advanced/custom_hooks)
On this page
------------
* [Table of Contents](https://dioxuslabs.com/learn/0.7/essentials/advanced/#table-of-contents)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
These guides build on topics covered in the [core concepts](https://dioxuslabs.com/learn/0.7/essentials/)
chapter to provide more detailed explanations and examples. While we recommend everyone read either the entire [tutorial](https://dioxuslabs.com/learn/0.7/tutorial/)
or [core concepts](https://dioxuslabs.com/learn/0.7/essentials/)
chapters as you learn dioxus, these guides are intended for users who want to dive deeper into specific topics as needed.
Dioxus provides a set of tools to make building cross platform applications easier. The [`dioxus-cli`](https://crates.io/crates/dioxus-cli)
is the core tool for building, running, and managing dioxus applications. The [`tools`](https://dioxuslabs.com/learn/0.7/guides/tools/)
guide provides more information on the various tools available in the dioxus ecosystem.
When you build an app with dioxus, most of your application code can be platform agnostic. When you do need to interact with platform specific features, dioxus provides a variety of platform backends to help you do so. The [platforms](https://dioxuslabs.com/learn/0.7/guides/platforms/)
guide provides more information on the various platforms supported by dioxus.
Once you finish building your application, the [publishing guide](https://dioxuslabs.com/learn/0.7/guides/deploy/)
provides an overview of how to package and distribute your application. It also includes information about what configuration options are available for bundling.
If you are ready to dive into building your own renderer for dioxus, the [custom renderer guide](https://dioxuslabs.com/learn/0.7/guides/depth/custom_renderer)
provides an overview of how to get started.
If you are updating from an older version of dioxus, the [migration guides](https://dioxuslabs.com/learn/0.7/migration/)
provide information about breaking changes and how to update your code to work with the latest version of dioxus.
[PREVIOUSBreaking Out](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out)
[NEXTTools](https://dioxuslabs.com/learn/0.7/guides/tools/)
On this page
------------
* [Tools](https://dioxuslabs.com/learn/0.7/guides/#tools)
* [Platforms](https://dioxuslabs.com/learn/0.7/guides/#platforms)
* [Publishing](https://dioxuslabs.com/learn/0.7/guides/#publishing)
* [Custom Renderer](https://dioxuslabs.com/learn/0.7/guides/#custom-renderer)
* [Migration](https://dioxuslabs.com/learn/0.7/guides/#migration)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Routing](https://dioxuslabs.com/learn/0.7/essentials/router/)
As your app grows, it can be helpful to organize your app into multiple pages or views you can switch between. In web application, each view has an associated url that can be saved and shared. The Dioxus router helps you manage the URL state of your application. It provides a type safe interface that checks all routes at compile time to prevent runtime errors.
To get started, you can add the `router` feature to your `dioxus` dependency in your `Cargo.toml`:
\[dependencies\]
dioxus \= { version \= "0.7", features \= \["router"\] }
\[dependencies\]
dioxus \= { version \= "0.7", features \= \["router"\] }
The core of the router is your `Routable` enum. You will use this enum throughout your application to navigate to different pages. Each variant of the enum is a single view page in your app handles:
1. Parsing your route from a URL
2. Displaying your route as a URL
3. Rendering your route as a component
To create a `Routable` enum, you will need to derive the `Routable` with a `#[route(..)]` attribute on each variant which describes the format of the route. You must have a component in scope that matches the name of each variant to render the route:
src/router\_introduction.rs
use dioxus::prelude::\*;
#\[derive(Clone, Debug, PartialEq, Routable)\]
enum Route {
#\[route("/")\]
Home,
#\[route("/about")\]
About,
#\[route("/user/:id")\]
User { id: u32 },
}
#\[component\]
fn Home() -> Element {
rsx! { "Welcome to the home page!" }
}
#\[component\]
fn About() -> Element {
rsx! { "This is the about page." }
}
#\[component\]
fn User(id: u32) -> Element {
rsx! { "User page for user with id: {id}" }
}
use dioxus::prelude::\*;
#\[derive(Clone, Debug, PartialEq, Routable)\]
enum Route {
#\[route("/")\]
Home,
#\[route("/about")\]
About,
#\[route("/user/:id")\]
User { id: u32 },
}
#\[component\]
fn Home() -> Element {
rsx! { "Welcome to the home page!" }
}
#\[component\]
fn About() -> Element {
rsx! { "This is the about page." }
}
#\[component\]
fn User(id: u32) -> Element {
rsx! { "User page for user with id: {id}" }
}
Now that you have defined your routes, you can use the `Router` component to render them. The `Router` component takes your `Routable` enum as a generic argument to define handle parsing, and rendering routes.
src/router\_introduction.rs
fn main() {
dioxus::launch(|| rsx! { Router:: {} });
}
fn main() {
dioxus::launch(|| rsx! { Router:: {} });
}
To navigate between routes, you can use the `Link` component provided by the router. The `Link` component takes a `to` prop which can be either a unchecked string route or a variant of your `Routable` enum:
src/router\_introduction.rs
// ...
#\[component\]
fn Home() -> Element {
rsx! { div { "Welcome to the home page!"
Link { to: Route::About, "Go to About Page" }
} }
}
// ...
#\[component\]
fn Home() -> Element {
rsx! { div { "Welcome to the home page!"
Link { to: Route::About, "Go to About Page" } } }
}
[PREVIOUSStatic Site Generation](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation)
[NEXTDefining Routes](https://dioxuslabs.com/learn/0.7/essentials/router/routes)
On this page
------------
* [Installing the router](https://dioxuslabs.com/learn/0.7/essentials/router/#installing-the-router)
* [Creating a Routable enum](https://dioxuslabs.com/learn/0.7/essentials/router/#creating-a-routable-enum)
* [Rendering the router](https://dioxuslabs.com/learn/0.7/essentials/router/#rendering-the-router)
* [Linking to your first route](https://dioxuslabs.com/learn/0.7/essentials/router/#linking-to-your-first-route)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Utilities](https://dioxuslabs.com/learn/0.7/guides/utilities/)
The utilities section provides a collection of useful libraries that can be used alongside dioxus.
* [Logging](https://dioxuslabs.com/learn/0.7/guides/utilities/logging)
Covers how to use dioxus-logger to configure logging for your project.
* [Internationalization](https://dioxuslabs.com/learn/0.7/guides/utilities/internationalization)
Explains how to use dioxus-i8n to support multiple languages in your application.
* [Tailwind](https://dioxuslabs.com/learn/0.7/guides/utilities/tailwind)
Provides setup instructions for using dioxus with Tailwind CSS.
[PREVIOUSAnti-patterns](https://dioxuslabs.com/learn/0.7/guides/tips/antipatterns)
[NEXTLogging](https://dioxuslabs.com/learn/0.7/guides/utilities/logging)
On this page
------------
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[In-Depth](https://dioxuslabs.com/learn/0.7/guides/depth/)
[PREVIOUSTailwind](https://dioxuslabs.com/learn/0.7/guides/utilities/tailwind)
[NEXTCustom Renderer](https://dioxuslabs.com/learn/0.7/guides/depth/custom_renderer)
On this page
------------
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Tools](https://dioxuslabs.com/learn/0.7/guides/tools/)
Dioxus has an ecosystem of tools to help you develop and deploy your applications. This guide will help you set up, configure and use these tools.
The CLI bundles together many different tools for dioxus development. Dioxus provides prebuilt binaries for Windows, macOS, and Linux you can download with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall)
:
cargo binstall dioxus-cli
cargo binstall dioxus-cli
If you don't have cargo-binstall installed or we don't have a prebuilt binary for your platform, you can install the CLI with manually with cargo install:
cargo install dioxus-cli
cargo install dioxus-cli
To verify your installation and get an overview of all the commands available, run:
dx --help
dx --help
You should see something like this:
Dioxus: build web, desktop, and mobile apps with a single codebase
Usage: dx \[OPTIONS\]
Commands:
new Create a new Dioxus project serve Build, watch, and serve the project bundle Bundle the Dioxus app into a shippable object build Build the Dioxus project and all of its assets run Run the project without any hotreloading init Init a new project for Dioxus in the current directory (by default). Will attempt to keep your project in a good state doctor Diagnose installed tools and system configuration print Print project information in a structured format, like cargo args, linker args, and other flags DX sets that might be useful in third-party tools translate Translate a source file into Dioxus code fmt Automatically format RSX check Check the project for any issues config Dioxus config file controls self-update Update the Dioxus CLI to the latest version tools Run a dioxus build tool. IE \`build-assets\`, \`hotpatch\`, etc components Manage components from the \`dioxus-component\` registry help Print this message or the help of the given subcommand(s)
Options:
--verbose Use verbose output \[default: false\]
--trace Use trace output \[default: false\]
--json-output Output logs in JSON format -h, --help Print help -V, --version Print version
Logging Options:
--log-to-file Write \*all\* logs to a file
Manifest Options:
--locked Assert that \`Cargo.lock\` will remain unchanged --offline Run without accessing the network --frozen Equivalent to specifying both --locked and --offline
Dioxus: build web, desktop, and mobile apps with a single codebase
Usage: dx \[OPTIONS\]
Commands:
new Create a new Dioxus project serve Build, watch, and serve the project bundle Bundle the Dioxus app into a shippable object build Build the Dioxus project and all of its assets run Run the project without any hotreloading init Init a new project for Dioxus in the current directory (by default). Will attempt to keep your project in a good state doctor Diagnose installed tools and system configuration print Print project information in a structured format, like cargo args, linker args, and other flags DX sets that might be useful in third-party tools translate Translate a source file into Dioxus code fmt Automatically format RSX check Check the project for any issues config Dioxus config file controls self-update Update the Dioxus CLI to the latest version tools Run a dioxus build tool. IE \`build-assets\`, \`hotpatch\`, etc components Manage components from the \`dioxus-component\` registry help Print this message or the help of the given subcommand(s)
Options:
--verbose Use verbose output \[default: false\]
--trace Use trace output \[default: false\]
--json-output Output logs in JSON format -h, --help Print help -V, --version Print version
Logging Options:
--log-to-file Write \*all\* logs to a file
Manifest Options:
--locked Assert that \`Cargo.lock\` will remain unchanged --offline Run without accessing the network --frozen Equivalent to specifying both --locked and --offline
Many chapters in this guide cover different commands in the CLI:
* [Create a project](https://dioxuslabs.com/learn/0.7/guides/tools/creating)
provides an overview of the `dx new` and `dx init` commands to scaffold your dioxus project
* [Translate HTML](https://dioxuslabs.com/learn/0.7/guides/tools/translate)
provides an overview of the `dx translate` command to convert HTML into rsx.
Other chapters explore different aspects of using the CLI and other tools:
* [Configure Project](https://dioxuslabs.com/learn/0.7/guides/tools/configure)
explores how you can configure your project with the `Dioxus.toml` file the CLI reads
[PREVIOUSOverview](https://dioxuslabs.com/learn/0.7/guides/)
[NEXTCreate a Project](https://dioxuslabs.com/learn/0.7/guides/tools/creating)
On this page
------------
* [Installing the CLI](https://dioxuslabs.com/learn/0.7/guides/tools/#installing-the-cli)
* [Manual installation](https://dioxuslabs.com/learn/0.7/guides/tools/#manual-installation)
* [Commands](https://dioxuslabs.com/learn/0.7/guides/tools/#commands)
* [Table of Contents](https://dioxuslabs.com/learn/0.7/guides/tools/#table-of-contents)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Testing and Debugging](https://dioxuslabs.com/learn/0.7/guides/testing/)
Testing and debugging are essential parts of the development process. This guide covers the basics of testing dioxus applications and debugging issues.
Testing can be broken down into several categories:
* **Unit Testing**: Testing individual components or functions in isolation.
* **End-to-End Testing**: Testing the entire application from start to finish.
Unit testing involves testing individual components or functions in isolation. Rust has built in support for testing using `cargo test`. You can annotate any function with the `#[test]` attribute to mark it as a test function. Here's an example of how to write a unit test for a simple function:
fn add(a: i32, b: i32) -> i32 {
a + b
}
#\[test\]
fn test\_add() {
assert\_eq!(add(2, 3), 5);
}
fn add(a: i32, b: i32) -> i32 {
a + b
}
#\[test\]
fn test\_add() {
assert\_eq!(add(2, 3), 5);
}
End-to-end testing involves testing the entire application from start to finish. For dioxus applications, playwright can be used to automate the browser and test different aspects of your application. The [Web Testing](https://dioxuslabs.com/learn/0.7/guides/testing/web)
guide provides more information on how to setup and use playwright with dioxus.
While it is important to understand how to debug issues when they come up, avoiding issues altogether is even better. The [anti-patterns](https://dioxuslabs.com/learn/0.7/guides/tips/antipatterns)
guide walks through a couple of common pitfalls and how to avoid them.
Once you have ironed out all of the bugs in your application and are ready to deploy, its worth taking some time to get your application ready for production. The [Optimizing](https://dioxuslabs.com/learn/0.7/guides/tips/optimizing)
guide covers optimizing your build settings for production.
[PREVIOUSBundle Config](https://dioxuslabs.com/learn/0.7/guides/deploy/config)
[NEXTWeb Testing](https://dioxuslabs.com/learn/0.7/guides/testing/web)
On this page
------------
* [Testing](https://dioxuslabs.com/learn/0.7/guides/testing/#testing)
* [Unit Testing](https://dioxuslabs.com/learn/0.7/guides/testing/#unit-testing)
* [End-to-End Testing](https://dioxuslabs.com/learn/0.7/guides/testing/#end-to-end-testing)
* [Avoiding Common Pitfalls](https://dioxuslabs.com/learn/0.7/guides/testing/#avoiding-common-pitfalls)
* [Optimizing Builds](https://dioxuslabs.com/learn/0.7/guides/testing/#optimizing-builds)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Platform Support](https://dioxuslabs.com/learn/0.7/guides/platforms/)
Most of your code in dioxus will work across all platforms. However, each platform has its own set of features and limitations. For example, the web platform supports calling JavaScript through wasm-bindgen, while the desktop platform supports customizing the appearance of the window around the application.
Before diving into platform-specific code, it's important to have a good understanding of features in rust. Features let you add code that will only be included in the build if a certain feature is enabled.
Dioxus uses a different feature for each platform. For example, the web platform enables the `dioxus/web` feature, while the desktop platform enables the `dioxus/desktop` feature.
In your `Cargo.toml` file, you should set up a feature for each platform you want to support. For example:
\[features\]
default \= \[\]
web \= \["dioxus/web"\] \# This feature is enabled during web builds
desktop \= \["dioxus/desktop"\] \# This feature is enabled during desktop builds
\[features\]
default \= \[\]
web \= \["dioxus/web"\] \# This feature is enabled during web builds
desktop \= \["dioxus/desktop"\] \# This feature is enabled during desktop builds
Once you have your features set up, you can wrap your code in `#[cfg(feature = "web")]` or `#[cfg(feature = "desktop")]` to conditionally include code for each platform.
#\[cfg(feature \= "web")\]
fn web\_specific\_code() {
// Code specific to the web platform
}
#\[cfg(feature \= "desktop")\]
fn desktop\_specific\_code() {
// Code specific to the desktop platform
}
#\[cfg(feature \= "web")\]
fn web\_specific\_code() {
// Code specific to the web platform
}
#\[cfg(feature \= "desktop")\]
fn desktop\_specific\_code() {
// Code specific to the desktop platform
}
In addition to platform specific code, you may need to set up dependencies that are only included on specific platforms. For example, if you're building a web application, you may want to include a dependency on the `wasm-bindgen` crate to call JavaScript functions from Rust.
You can add platform specific dependencies as optional in your `Cargo.toml` and enable them using the `features` table. For example:
\# Since this dependency is optional, it isn't included in the build automatically
wasm-bindgen \= { version \= "\*", optional \= true }
\[features\]
default \= \[\]
\# adding dep:wasm-bindgen enables the wasm-bindgen dependency only
\# in web builds
web \= \["dioxus/web", "dep:wasm-bindgen"\]
desktop \= \["dioxus/desktop"\]
\# Since this dependency is optional, it isn't included in the build automatically
wasm-bindgen \= { version \= "\*", optional \= true }
\[features\]
default \= \[\]
\# adding dep:wasm-bindgen enables the wasm-bindgen dependency only
\# in web builds
web \= \["dioxus/web", "dep:wasm-bindgen"\]
desktop \= \["dioxus/desktop"\]
Each chapter in this guide covers a different platform:
* [Web](https://dioxuslabs.com/learn/0.7/guides/platforms/web)
The web platform lets you compile to wasm and render to the DOM in the browser
* [Desktop](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop)
The desktop platform runs your code natively and renders using webview
* [Mobile](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile)
The mobile platform has the same rendering engine as desktop, but requires additional setup for mobile devices/emulators
[PREVIOUSTranslate HTML](https://dioxuslabs.com/learn/0.7/guides/tools/translate)
[NEXTWeb](https://dioxuslabs.com/learn/0.7/guides/platforms/web)
On this page
------------
* [Platform specific code](https://dioxuslabs.com/learn/0.7/guides/platforms/#platform-specific-code)
* [Platform-specific dependancies](https://dioxuslabs.com/learn/0.7/guides/platforms/#platform-specific-dependancies)
* [Table of Contents](https://dioxuslabs.com/learn/0.7/guides/platforms/#table-of-contents)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Custom Error Pages](https://dioxuslabs.com/learn/0.7/essentials/fullstack/errors)
Errors are unfortunately inevitable in software development. Even in Rust, apps might not behave as expected and user requests might be malformed.
In these cases, you might want to show an error page to the user while also returning an appropriate status code.
Recall in the [Server Functions](https://dioxuslabs.com/learn/0.7/essentials/fullstack/server_functions)
chapter, that all server functions must return a `Result`:
#\[post("/api/user/login")\]
pub async fn login() -> Result<()> {
// ...
}
#\[post("/api/user/login")\]
pub async fn login() -> Result<()> {
// ...
}
Because server functions are called from the client, they need some way of expressing _both_ a request failure and a server failure. If the user is offline, we want to reliably return an offline error and status in the UI.
Also recall that server functions can return several different error types:
* `ServerFnError`: A broad error type encompassing request failures and server failures
* `anyhow::Error`: A general-purpose error type that downcasts its inner value
* `CapturedError`: A cheaply-cloneable `anyhow::Error` wrapper
* `StatusCode`: A specific HTTP status code
* `HttpError`: A specific HTTP status code and a message
* Custom Errors: User errors that implement `Serialize + Deserialize + AsStatusCode`
Dioxus will attempt to downcast server function errors and captured errors into status codes such that the returned page receives an appropriate HTTP status.
If an error does not downcast to a known status-code-like error type, then the request will default to a `500 INTERNAL SERVER ERROR`.
#\[post("/api/user/login")\]
pub async fn login() -> Result<()> {
// This will return a 500 status code
return Err(anyhow::anyhow!("Bad request!").into());
// ...
}
#\[post("/api/user/login")\]
pub async fn login() -> Result<()> {
// This will return a 500 status code
return Err(anyhow::anyhow!("Bad request!").into());
// ...
}
The `OrHttpError` error type makes emitting status codes quite simple with its extension methods on `Result`, `Option`, and `bool`.
#\[post("/api/user/login")\]
pub async fn login() -> Result<()> {
authenticate\_user() // this method comes from \`OrHttpError\`
.or\_unauthorized("You must be logged in to view this resource")?;
// ..
}
#\[post("/api/user/login")\]
pub async fn login() -> Result<()> {
authenticate\_user() // this method comes from \`OrHttpError\`
.or\_unauthorized("You must be logged in to view this resource")?;
// ..
}
In the event of an error, Dioxus extracts the status code for the response by downcasting errors that bubble to root component.
For example, this example app does not provide a root error boundary, and thus all errors will bubble up to the root:
fn app() -> Element {
let post\_data \= use\_loader(move || get\_post())?;
rsx! { p { "{post\_data}" }
}
}
// This endpoint always throws an error
#\[get("/api/post/")\]
async fn get\_post() -> Result {
HttpError::not\_found("Post not found")
}
fn app() -> Element {
let post\_data \= use\_loader(move || get\_post())?;
rsx! { p { "{post\_data}" } }
}
// This endpoint always throws an error
#\[get("/api/post/")\]
async fn get\_post() -> Result {
HttpError::not\_found("Post not found")
}
If you `curl` the app, you'll notice that it returns a `404` status code.
If we want to catch the error and provide a nice fallback UI, we can use an `ErrorBoundary`. Note that when we catch the error, we must explicitly set the HTTP status code on the outgoing response with `FullstackContext::commit_error_status`:
fn app() -> Element {
rsx! { ErrorBoundary {
handle\_error: move |err| {
// To ensure the HTTP status is still set properly, we need to call \`commit\_error\_status\`
let http\_error \= FullstackContext::commit\_error\_status(err.error().unwrap());
// and then we can render some pretty fallback UI
rsx! { "An error occurred! {http\_error:?}" }
}, Post {}
} }
}
fn Post() -> Element {
let post\_data \= use\_loader(move || get\_post())?;
rsx! { p { "{post\_data" } }
}
fn app() -> Element {
rsx! { ErrorBoundary {
handle\_error: move |err| {
// To ensure the HTTP status is still set properly, we need to call \`commit\_error\_status\`
let http\_error \= FullstackContext::commit\_error\_status(err.error().unwrap());
// and then we can render some pretty fallback UI
rsx! { "An error occurred! {http\_error:?}" } }, Post {}
} }
}
fn Post() -> Element {
let post\_data \= use\_loader(move || get\_post())?;
rsx! { p { "{post\_data" } }
}
The `commit_error_status` function on `FullstackContext` extracts the HTTP status from a `CapturedError` and then modifies the outgoing response accordingly.
If you're using the Dioxus Router for your app's routing, then it might not be immediately clear how to integrate custom error pages into your app.
In these cases, we'd take a similar approach with an `ErrorBoundary`. We could either wrap our `Router {}` component in an error boundary, or add a layout to our app that renders the fallback UI.
// A router definition with \`ErrorLayout\` layout
#\[derive(Routable, PartialEq, Clone, Debug)\]
enum Route {
#\[layout(ErrorLayout)\] #\[route("/")\]
Home,
#\[route("/blog/:id")\]
Blog { id: u32 },
}
// And then our Outlet is wrapped in a fallback UI
#\[component\]
fn ErrorLayout() -> Element {
rsx! { ErrorBoundary {
handle\_error: move |err: ErrorContext| {
let http\_error \= FullstackContext::commit\_error\_status(err.error().unwrap());
match http\_error.status { StatusCode::NOT\_FOUND \=> rsx! { div { "404 - Page not found" } },
\_ \=> rsx! { div { "An unknown error occurred" } },
} }, Outlet:: {}
} }
}
// A router definition with \`ErrorLayout\` layout
#\[derive(Routable, PartialEq, Clone, Debug)\]
enum Route {
#\[layout(ErrorLayout)\] #\[route("/")\]
Home,
#\[route("/blog/:id")\]
Blog { id: u32 },
}
// And then our Outlet is wrapped in a fallback UI
#\[component\]
fn ErrorLayout() -> Element {
rsx! { ErrorBoundary {
handle\_error: move |err: ErrorContext| {
let http\_error \= FullstackContext::commit\_error\_status(err.error().unwrap());
match http\_error.status { StatusCode::NOT\_FOUND \=> rsx! { div { "404 - Page not found" } }, \_ \=> rsx! { div { "An unknown error occurred" } }, } }, Outlet:: {}
} }
}
Using layouts for error pages is extremely powerful. You can isolate fallback UI to specific parts of the page while also properly setting the returned status code.
For example, the GitHub UI retains most of its UI while isolate the 404 message to just the source code viewer:
It's a better user experience to render a web page that is visually consistent while also still delivering the appropriate status code.
[PREVIOUSServer Functions](https://dioxuslabs.com/learn/0.7/essentials/fullstack/server_functions)
[NEXTRouter and State](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum)
On this page
------------
* [Creating an Error](https://dioxuslabs.com/learn/0.7/essentials/fullstack/errors/#creating-an-error)
* [Error Status Codes Bubble](https://dioxuslabs.com/learn/0.7/essentials/fullstack/errors/#error-status-codes-bubble)
* [Error Layout with Router](https://dioxuslabs.com/learn/0.7/essentials/fullstack/errors/#error-layout-with-router)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Migration](https://dioxuslabs.com/learn/0.7/migration/)
Dioxus has evolved over its lifetime. We feel quite stable with the current API, but there might be changes in the future.
To help migrate between versions, we've assembled a set of migration guides:
* [v0.4 to v0.5](https://dioxuslabs.com/learn/0.7/migration/to_05/)
* [v0.5 to v0.6](https://dioxuslabs.com/learn/0.7/migration/to_06)
* [v0.6 to v0.7](https://dioxuslabs.com/learn/0.7/migration/to_07)
[PREVIOUSCustom Renderer](https://dioxuslabs.com/learn/0.7/guides/depth/custom_renderer)
[NEXTTo 0.7](https://dioxuslabs.com/learn/0.7/migration/to_07)
On this page
------------
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Publishing](https://dioxuslabs.com/learn/0.7/guides/deploy/)
After you have built your application, you will need to publish it somewhere. This reference will outline different methods of publishing your desktop or web application.
Edit your `Dioxus.toml` to point your `out_dir` to the `docs` folder and the `base_path` to the name of your repo:
\[application\]
\# ...
\[web.app\]
base\_path \= "your\_repo"
\[application\]
\# ...
\[web.app\]
base\_path \= "your\_repo"
Then build your app and publish it to Github:
* Make sure GitHub Pages is set up for your repo to publish any static files in the docs directory
* Build your app into the `docs` directory with:
dx bundle --out-dir docs
dx bundle --out-dir docs
* Move the static content from `docs/public` to `docs`
mv docs/public/\* docs
mv docs/public/\* docs
* Make a copy of your `docs/index.html` file and rename the copy to `docs/404.html` so that your app will work with client-side routing:
cp docs/index.html docs/404.html
cp docs/index.html docs/404.html
* Add and commit with git
* Push to GitHub
Dioxus desktop app uses your operating system's WebView library, so it's portable to be distributed for other platforms.
In this section, we'll cover how to bundle your app for macOS, Windows, and Linux.
Depending on your platform, you may need to add some additional code to your `main.rs` file to make sure your app is ready for bundling. On Windows, you'll need to add the `#![windows_subsystem = "windows"]` attribute to your `main.rs` file to hide the terminal window that pops up when you run your app. **If you're developing on Windows, only use this when bundling.** It will disable the terminal, so you will not get logs of any kind. You can gate it behind a feature, like so:
\# Cargo.toml
\[features\]
bundle \= \[\]
\# Cargo.toml
\[features\]
bundle \= \[\]
And then your `main.rs`:
#!\[cfg\_attr(feature \= "bundle", windows\_subsystem \= "windows")\]
#!\[cfg\_attr(feature \= "bundle", windows\_subsystem \= "windows")\]
If you want to bundle assets with your application, you can either use them with the `manganis` crate (covered more in the [assets](https://dioxuslabs.com/learn/0.7/essentials/ui/assets)
page), or you can include them in your `Dioxus.toml` file:
\[bundle\]
\# The list of files to include in the bundle. These can contain globs.
resources \= \["main.css", "header.svg", "\*\*/\*.png"\]
\[bundle\]
\# The list of files to include in the bundle. These can contain globs.
resources \= \["main.css", "header.svg", "\*\*/\*.png"\]
The first thing we'll do is install the [dioxus-cli](https://github.com/DioxusLabs/dioxus/tree/main/packages/cli)
. This extension to cargo will make it very easy to package our app for the various platforms.
To install, simply run
`cargo install dioxus-cli`
To bundle your application you can simply run `dx bundle --release` (also add `--features bundle` if you're using that, see the [this](https://dioxuslabs.com/learn/0.7/guides/deploy/#preparing-your-application-for-bundling)
for more) to produce a final app with all the optimizations and assets builtin.
Once you've ran the command, your app should be accessible in `dist/bundle/`.
For example, a macOS app would look like this:
Nice! And it's only 4.8 Mb â extremely lean!! Because Dioxus leverages your platform's native WebView, Dioxus apps are extremely memory efficient and won't waste your battery.
> Note: not all CSS works the same on all platforms. Make sure to view your app's CSS on each platform â or web browser (Firefox, Chrome, Safari) before publishing.
[PREVIOUSMobile](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile)
[NEXTBundle Config](https://dioxuslabs.com/learn/0.7/guides/deploy/config)
On this page
------------
* [Web: Publishing with GitHub Pages](https://dioxuslabs.com/learn/0.7/guides/deploy/#web-publishing-with-github-pages)
* [Desktop: Creating an installer](https://dioxuslabs.com/learn/0.7/guides/deploy/#desktop-creating-an-installer)
* [Preparing your application for bundling](https://dioxuslabs.com/learn/0.7/guides/deploy/#preparing-your-application-for-bundling)
* [Adding assets to your application](https://dioxuslabs.com/learn/0.7/guides/deploy/#adding-assets-to-your-application)
* [Install dioxus CLI](https://dioxuslabs.com/learn/0.7/guides/deploy/#install-dioxus-cli)
* [Building](https://dioxuslabs.com/learn/0.7/guides/deploy/#building)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Authentication](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication)
Most production-ready apps have some sort of authentication and authorization to restrict data and resources from being publicly accessible to all users.
Dioxus does _not_ provide a built-in way of managing authentication. However, since auth is such a critical component of building fullstack apps, this chapter will help guide you through the process of implementing it for your app.
> In the future, we'd like to integrate sessions and auth directly into Dioxus fullstack, but for now, you'll need to rely on 3rd-party libraries.
Authentication is the process of verifying a user's identity, usually through the use of cookies or access tokens.
Your app should not blindly accept actions from untrusted users, so it's important to verify that a user who claims to be "Bob" _actually is_ "Bob".
Authorization is the _next step_ after authentication. Once a user's identity is verified, you must then verify that they can actually take a given action.
You don't want one user to change another user's login credentials, so any action related to user data must be _authorized_ first.
Fundamentally, auth works by associating a users _connection_ with some _session_ in a database. As a user traverses our page and makes actions, we need some way of identifying their session on the server.
Usually, this is done via a middleware that automatically registers every connection with a row in your database. If the user is _unauthenticated_, you can either store their session as an anonymous user, or a ignore it completely.
A session is usually inserted with an axum-level middleware:
dioxus::server::router(app)
.layer(axum::middleware::from\_fn( |request: Request, next: Next| async move {
// Get the auth token and then insert the session into the request's extensions
//
// We need to look up the auth token in our database to retrieve the session
if let Some(token) \= request.headers().get("Authorization") {
if let Some(session) \= DATABASE.get\_session(token) {
request.extensions\_mut().insert(session); } }
// And then run the request
next.run(request).await
}, ))
dioxus::server::router(app)
.layer(axum::middleware::from\_fn( |request: Request, next: Next| async move {
// Get the auth token and then insert the session into the request's extensions
//
// We need to look up the auth token in our database to retrieve the session
if let Some(token) \= request.headers().get("Authorization") {
if let Some(session) \= DATABASE.get\_session(token) {
request.extensions\_mut().insert(session); } }
// And then run the request
next.run(request).await
}, ))
You can implement session lookup and session creation system manually, or use a 3rd-party library like [`axum_session_auth`](https://crates.io/crates/axum_session_auth)
to handle most of the complexity for you.
Generally, you'll add a 3rd-party library as a `.layer()` on your router, and it will add the `Session` extension to your requests automatically:
dioxus::serve(|| async move {
// Create an axum router that dioxus will attach the app to
Ok(dioxus::server::router(app)
// Add the \`AuthLayer\`
.layer( AuthLayer::new(Some(db.clone()))
.with\_config(AuthConfig::::default().with\_anonymous\_user\_id(Some(1))),
) // And add the \`SessionLayer\`
.layer(SessionLayer::new(
SessionStore::::new(
Some(db.into()),
SessionConfig::default().with\_table\_name("test\_table"),
) .await?,
)))
})
dioxus::serve(|| async move {
// Create an axum router that dioxus will attach the app to
Ok(dioxus::server::router(app)
// Add the \`AuthLayer\`
.layer( AuthLayer::new(Some(db.clone()))
.with\_config(AuthConfig::::default().with\_anonymous\_user\_id(Some(1))),
) // And add the \`SessionLayer\`
.layer(SessionLayer::new(
SessionStore::::new(
Some(db.into()),
SessionConfig::default().with\_table\_name("test\_table"),
) .await?,
)))
})
The `axum_session_auth` crate integrates with `sqlx` to automatically manage sessions using a row in your database.
You can use extractors to integrate auth with your Fullstack application.
You can create a custom extractor to extract the auth session from the request. From that auth session, you can check if the user has the required privileges before returning the private data.
Because the sessions are inserted into every request, you can extract them with server-only extractors:
/// We use the \`auth::Session\` extractor to get access to the current user session.
/// This lets us modify the user session, log in/out, and access the current user.
#\[post("/api/user/login", auth: auth::Session)\]
pub async fn login() -> Result<()> {
auth.login\_user(2);
Ok(())
}
/// Just like \`login\`, but this time we log out the user.
#\[post("/api/user/logout", auth: auth::Session)\]
pub async fn logout() -> Result<()> {
auth.logout\_user(); Ok(())
}
/// We use the \`auth::Session\` extractor to get access to the current user session.
/// This lets us modify the user session, log in/out, and access the current user.
#\[post("/api/user/login", auth: auth::Session)\]
pub async fn login() -> Result<()> {
auth.login\_user(2);
Ok(())
}
/// Just like \`login\`, but this time we log out the user.
#\[post("/api/user/logout", auth: auth::Session)\]
pub async fn logout() -> Result<()> {
auth.logout\_user(); Ok(())
}
A [full auth example](https://github.com/DioxusLabs/dioxus/blob/7102bc3b6a0ddea3a9e71423fc6d667df8d956f3/examples/07-fullstack/auth/src/main.rs)
with the complete implementation is available in the fullstack examples.
Implementing auth can be somewhat tedious, so there are a number of 3rd party services that simplify the implementation for you. With these services, the session and auth data tends to not live in _your database_, but rather theirs.
We don't recommend any particular 3rd party service. However, there are some solutions like Supabase and Firebase where sessions are managed in your database, but with prebuilt infrastructure for you to integrate with.
[PREVIOUSForms and Multipart](https://dioxuslabs.com/learn/0.7/essentials/fullstack/forms)
[NEXTNative Clients](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native)
On this page
------------
* [What is Authentication?](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication/#what-is-authentication)
* [What is Authorization?](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication/#what-is-authorization)
* [Auth is Built on Sessions](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication/#auth-is-built-on-sessions)
* [Libraries for Authentication](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication/#libraries-for-authentication)
* [Auth as an Extractor](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication/#auth-as-an-extractor)
* [Auth as a 3rd-party service](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication/#auth-as-a-3rd-party-service)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Tools](https://dioxuslabs.com/learn/0.7/guides/tools/)
[Create a Project](https://dioxuslabs.com/learn/0.7/guides/tools/creating)
Once you have the Dioxus CLI installed, you can use it to create your own project!
First, run the `dx new` command to create a new project.
> It clones this [template](https://github.com/DioxusLabs/dioxus-template)
> , which is used to create dioxus apps.
>
> You can create your project from a different template by passing the `template` argument:
>
> dx new --template gh:dioxuslabs/dioxus-template
>
> dx new --template gh:dioxuslabs/dioxus-template
Next, navigate into your new project using `cd project-name`, or simply opening it in an IDE.
> Make sure the WASM target is installed before running the projects. You can install the WASM target for rust using rustup:
>
> rustup target add wasm32-unknown-unknown
>
> rustup target add wasm32-unknown-unknown
Finally, serve your project with `dx serve`! The CLI will tell you the address it is serving on, along with additional info such as code warnings.
[PREVIOUSTools](https://dioxuslabs.com/learn/0.7/guides/tools/)
[NEXTConfigure Project](https://dioxuslabs.com/learn/0.7/guides/tools/configure)
On this page
------------
* [Initializing a project](https://dioxuslabs.com/learn/0.7/guides/tools/creating/#initializing-a-project)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Forms and Multipart](https://dioxuslabs.com/learn/0.7/essentials/fullstack/forms)
Dioxus natively supports HTML Forms and Multipart uploads.
* HTML forms are collections of input elements represented as a list of key-value pairs
* Multipart requests are requests that contain multiple bodies
Many forms you'll build will be rather simple. Uploading them will only require a single request body. In some cases, as with file-uploads, you'll need a multi-part form data.
Dioxus Fullstack supports form uploads through Axum's typed `Form` type. Simply wrap a struct that implements `Serialize + Deserialize` and pass it as an argument to a server function:
// Our form payload
#\[derive(Deserialize, Serialize)\]
pub struct LoginForm {
username: String,
password: String,
}
// Our form endpoint
#\[post("/api/login")\]
async fn login(form: Form) -> Result<()> {
// Verify the username and password.
// In a real application, you'd check these against a database.
if form.0.username \== "admin" && form.0.password \== "password" {
// ..
}
}
// Our form payload
#\[derive(Deserialize, Serialize)\]
pub struct LoginForm {
username: String,
password: String,
}
// Our form endpoint
#\[post("/api/login")\]
async fn login(form: Form) -> Result<()> {
// Verify the username and password.
// In a real application, you'd check these against a database.
if form.0.username \== "admin" && form.0.password \== "password" { // ..
}
}
The values from the form can be created manually by constructing the form body, or automatically by calling `.parsed_values()` on the `FormEvent` type created by `onsubmit`.
rsx! {
form { onsubmit: move |evt: FormEvent| async move {
// Prevent the browser from navigating away.
evt.prevent\_default();
// Extract the form values into our \`LoginForm\` struct. The \`.parsed\_values\` method
// is provided by Dioxus and works with any form element that has \`name\` attributes.
let values: LoginForm \= evt.parsed\_values().unwrap();
// Call the login endpoint
login(Form(values)).await;
}, input { r#type: "text", id: "username", name: "username" }
label { "Username" }
input { r#type: "password", id: "password", name: "password" }
label { "Password" }
button { "Login" }
}
}
rsx! {
form { onsubmit: move |evt: FormEvent| async move {
// Prevent the browser from navigating away.
evt.prevent\_default();
// Extract the form values into our \`LoginForm\` struct. The \`.parsed\_values\` method
// is provided by Dioxus and works with any form element that has \`name\` attributes.
let values: LoginForm \= evt.parsed\_values().unwrap();
// Call the login endpoint
login(Form(values)).await;
}, input { r#type: "text", id: "username", name: "username" } label { "Username" } input { r#type: "password", id: "password", name: "password" } label { "Password" } button { "Login" } }
}
Form elements must have a "name" attribute which will be used during the deserialization process to identify form fields.
Note that `GET` requests will encode the form values in the request URL. This might not work for complex data structures, so it's best practice to use `POST` endpoints for handling form data.
With some forms, you'll need to handle multiple request bodies in a single request. For example, if your form has file inputs, the browser will automatically create a multi-part request with the form values in one body and then file uploads in another.
Dioxus provides the `MultipartFormData` type which will automatically convert `FormEvent` objects into proper multi-part requests.
On the client, you can convert the `FormEvent` with `.into()`:
rsx! {
form { display: "flex", flex\_direction: "column", gap: "8px", onsubmit: move |evt| async move { evt.prevent\_default();
upload(evt.into()).await; }, label { r#for: "headshot", "Photos" } input { r#type: "file", name: "headshot", multiple: true, accept: ".png,.jpg,.jpeg" } label { r#for: "resume", "Resume" } input { r#type: "file", name: "resume", multiple: false, accept: ".pdf" } label { r#for: "name", "Name" } input { r#type: "text", name: "name", placeholder: "Name" } label { r#for: "age", "Age" } input { r#type: "number", name: "age", placeholder: "Age" } input { r#type: "submit", name: "submit", value: "Submit your resume" } }
}
rsx! {
form { display: "flex", flex\_direction: "column", gap: "8px", onsubmit: move |evt| async move { evt.prevent\_default();
upload(evt.into()).await; }, label { r#for: "headshot", "Photos" } input { r#type: "file", name: "headshot", multiple: true, accept: ".png,.jpg,.jpeg" } label { r#for: "resume", "Resume" } input { r#type: "file", name: "resume", multiple: false, accept: ".pdf" } label { r#for: "name", "Name" } input { r#type: "text", name: "name", placeholder: "Name" } label { r#for: "age", "Age" } input { r#type: "number", name: "age", placeholder: "Age" } input { r#type: "submit", name: "submit", value: "Submit your resume" } }
}
On the server, you can use an endpoint that takes `MultipartFormData` and then iterate through the fields using `next_field()`:
#\[post("/api/upload-multipart")\]
async fn upload(mut form: MultipartFormData) -> Result<()> {
while let Ok(Some(field)) \= form.next\_field().await {
let name \= field.name().unwrap\_or("").to\_string();
let file\_name \= field.file\_name().unwrap\_or("").to\_string();
let content\_type \= field.content\_type().unwrap\_or("").to\_string();
let bytes \= field.bytes().await;
// ...
}
Ok(())
}
#\[post("/api/upload-multipart")\]
async fn upload(mut form: MultipartFormData) -> Result<()> {
while let Ok(Some(field)) \= form.next\_field().await {
let name \= field.name().unwrap\_or("").to\_string();
let file\_name \= field.file\_name().unwrap\_or("").to\_string();
let content\_type \= field.content\_type().unwrap\_or("").to\_string();
let bytes \= field.bytes().await;
// ...
}
Ok(())
}
Currently Dioxus does not support typed `MultipartFormData` objects, but it _is_ something we'd like to add in the future.
[PREVIOUSStreams and SSE](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streams)
[NEXTAuthentication](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication)
On this page
------------
* [Forms](https://dioxuslabs.com/learn/0.7/essentials/fullstack/forms/#forms)
* [Multipart](https://dioxuslabs.com/learn/0.7/essentials/fullstack/forms/#multipart)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Middleware](https://dioxuslabs.com/learn/0.7/essentials/fullstack/middleware)
Middleware allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.
Dioxus Fullstack provides two main ways of adding middleware to your app:
* Imperatively using Axum's APIs on your Router in `dioxus::serve`
* Declaratively by annotating individual endpoints with the `#[middleware]` attribute
In web applications, middleware are functions that are called before and after the request is handled by your endpoint logic.
The underlying web framework that Dioxus Fullstack is built on - Axum - does not define its own bespoke middleware system. Instead, it leans on the broader ecosystem, integrating with the more fundamental [`tower`](https://github.com/tower-rs/tower)
and [`hyper`](https://github.com/hyperium/hyper)
crates.
Axum _does_ provide a simple way of writing middleware with `middleware::from_fn`:
axum::middleware::from\_fn(
|request: Request, next: Next| async move {
// Read and write the contents of the incoming request
println!("Headers: {:?}", request.headers());
// And then run the request, modifying and returning the response
next.run(request).await
},
)
axum::middleware::from\_fn(
|request: Request, next: Next| async move {
// Read and write the contents of the incoming request
println!("Headers: {:?}", request.headers());
// And then run the request, modifying and returning the response
next.run(request).await
},
)
Middleware give you both _read_ and _write_ access to both the _request_ and the _response_ of the handler. This is extremely powerful!
You can implements a wide range of functionality with middleware:
* Logging and telemetry
* Rate limiting
* Validation
* Compression
* CORS, CSRF
* Authentication and Authorization
* Caching
The broader Rust ecosystem has many different 3rd party crates for middleware.
The two main crates to look for middleware are:
* [Tower](https://docs.rs/tower/latest/tower/)
: The underlying library for networking
* [Tower-HTTP](https://github.com/tower-rs/tower-http)
: A dedicated HTTP-specific middleware library
Because Dioxus is built on Axum, you can use many Axum APIs directly. Dioxus Fullstack does not provide any bespoke wrappers around Axum middleware - you can simply attach them to your router in `dioxus::serve`:
dioxus::serve(|| async move {
use axum::{extract::Request, middleware::Next};
use dioxus::server::axum;
Ok(dioxus::server::router(app)
// we can apply a layer to the entire router using axum's \`.layer\` method
.layer(axum::middleware::from\_fn( |request: Request, next: Next| async move {
// Read the incoming request
println!("Request: {} {}", request.method(), request.uri().path());
// Run the handler, returning the response
let res \= next.run(request).await;
// Read/write the response
println!("Response: {}", res.status());
res }, )))
});
dioxus::serve(|| async move {
use axum::{extract::Request, middleware::Next};
use dioxus::server::axum;
Ok(dioxus::server::router(app)
// we can apply a layer to the entire router using axum's \`.layer\` method
.layer(axum::middleware::from\_fn( |request: Request, next: Next| async move {
// Read the incoming request
println!("Request: {} {}", request.method(), request.uri().path());
// Run the handler, returning the response
let res \= next.run(request).await;
// Read/write the response
println!("Response: {}", res.status());
res }, )))
});
The Tower-HTTP crate provides a number of useful middleware layers to add to your app. The `ServiceBuilder` object can be used to efficiently assemble a `Service` which handles a wide range of middleware actions:
// Use tower's \`ServiceBuilder\` API to build a stack of tower middleware
// wrapping our request handler.
let middleware \= ServiceBuilder::new()
// Mark the \`Authorization\` request header as sensitive so it doesn't show in logs
.layer(SetSensitiveRequestHeadersLayer::new(once(AUTHORIZATION)))
// High level logging of requests and responses
.layer(TraceLayer::new\_for\_http())
// Share an \`Arc\` with all requests
.layer(AddExtensionLayer::new(Arc::new(state)))
// Compress responses
.layer(CompressionLayer::new())
// Propagate \`X-Request-Id\`s from requests to responses
.layer(PropagateHeaderLayer::new(HeaderName::from\_static("x-request-id")))
// If the response has a known size set the \`Content-Length\` header
.layer(SetResponseHeaderLayer::overriding(CONTENT\_TYPE, content\_length\_from\_response))
// Authorize requests using a token
.layer(ValidateRequestHeaderLayer::bearer("passwordlol"))
// Accept only application/json, application/\* and \*/\* in a request's ACCEPT header
.layer(ValidateRequestHeaderLayer::accept("application/json"))
// Wrap a \`Service\` in our middleware stack
.service\_fn(handler);
// Use tower's \`ServiceBuilder\` API to build a stack of tower middleware
// wrapping our request handler.
let middleware \= ServiceBuilder::new()
// Mark the \`Authorization\` request header as sensitive so it doesn't show in logs
.layer(SetSensitiveRequestHeadersLayer::new(once(AUTHORIZATION)))
// High level logging of requests and responses
.layer(TraceLayer::new\_for\_http())
// Share an \`Arc\` with all requests
.layer(AddExtensionLayer::new(Arc::new(state)))
// Compress responses
.layer(CompressionLayer::new())
// Propagate \`X-Request-Id\`s from requests to responses
.layer(PropagateHeaderLayer::new(HeaderName::from\_static("x-request-id")))
// If the response has a known size set the \`Content-Length\` header
.layer(SetResponseHeaderLayer::overriding(CONTENT\_TYPE, content\_length\_from\_response))
// Authorize requests using a token
.layer(ValidateRequestHeaderLayer::bearer("passwordlol"))
// Accept only application/json, application/\* and \*/\* in a request's ACCEPT header
.layer(ValidateRequestHeaderLayer::accept("application/json"))
// Wrap a \`Service\` in our middleware stack
.service\_fn(handler);
You can then attach this service as a layer to your router:
dioxus::serve(|| async move {
use axum::{extract::Request, middleware::Next};
use dioxus::server::axum;
// Assemble a middleware object from the ServiceBuilder
let middleware \= ServiceBuilder::new()
.layer(/\* \*/)
.layer(/\* \*/)
.layer(/\* \*/);
Ok(dioxus::server::router(app).layer(middleware))
});
dioxus::serve(|| async move {
use axum::{extract::Request, middleware::Next};
use dioxus::server::axum;
// Assemble a middleware object from the ServiceBuilder
let middleware \= ServiceBuilder::new()
.layer(/\* \*/)
.layer(/\* \*/)
.layer(/\* \*/);
Ok(dioxus::server::router(app).layer(middleware))
});
Axum recommend initializing multiple middleware on a `ServiceBuilder` object for maximum performance, but you can also attach layers directly onto the router:
dioxus::serve(|| async move {
use axum::{extract::Request, middleware::Next};
use dioxus::server::axum;
Ok(
dioxus::server::router(app) .layer(/\* \*/)
.layer(/\* \*/)
.layer(/\* \*/)
)
});
dioxus::serve(|| async move {
use axum::{extract::Request, middleware::Next};
use dioxus::server::axum;
Ok(
dioxus::server::router(app) .layer(/\* \*/)
.layer(/\* \*/)
.layer(/\* \*/)
)
});
If you need to apply middleware to just a handful of specific routes, you can use the `#[middleware]` attribute. Unlike router-level middleware, route-level middleware will only be applied to a specific endpoint. Alternatively, you could register routes one-by-one on the axum router with dedicated calls `.layer()`.
For example, we might want to add a "timeout" middleware to a specific server function. This middleware will stop running the server function if it reaches a certain timeout:
src/server\_function\_middleware.rs
#\[cfg(feature \= "server")\]
use {std::time::Duration, tower\_http::timeout::TimeoutLayer};
// Add a timeout middleware to the server function that will return an error if the function takes longer than 1 second to execute
#\[post("/api/timeout")\]
#\[middleware(TimeoutLayer::new(Duration::from\_secs(1)))\]
pub async fn timeout() -> Result<(), ServerFnError> {
tokio::time::sleep(Duration::from\_secs(2)).await;
Ok(())
}
#\[cfg(feature \= "server")\]
use {std::time::Duration, tower\_http::timeout::TimeoutLayer};
// Add a timeout middleware to the server function that will return an error if the function takes longer than 1 second to execute
#\[post("/api/timeout")\]
#\[middleware(TimeoutLayer::new(Duration::from\_secs(1)))\]
pub async fn timeout() -> Result<(), ServerFnError> {
tokio::time::sleep(Duration::from\_secs(2)).await;
Ok(())
}
Under the hood, Dioxus Fullstack creates a `MethodRouter` object and then attaches these layers with calls to `.layer()` automatically.
In the chapter on server-side-rendering, we discussed at length about how Dioxus Fullstack is architected around client-side-rendering, with SSR being an additional enhancement. One enhancement is the ability to add a `Cache-Control` header to HTML responses, letting our CDN and Reverse Proxy decrease the load on our server. When the `Cache-Control` header is present, the proxy is able to cache responses.
> It's very important to note that middleware can "bust" the cache - even accidentally!
If you're using middleware for session management or authentication, it can be easy to accidentally cache pages that shouldn't be cached. For example, a news site might want to cache its homepage:
dioxus::server::router(app)
.layer(axum::middleware::from\_fn( |request: Request, next: Next| async move {
// If the route is \`/home\`, cache the page
let is\_home \= request.uri() \== "/home";
let res \= next.run(request).await;
if is\_home { res.headers\_mut().insert("Cache-Control", "max-age=10800")
}
res } ))
dioxus::server::router(app)
.layer(axum::middleware::from\_fn( |request: Request, next: Next| async move {
// If the route is \`/home\`, cache the page
let is\_home \= request.uri() \== "/home";
let res \= next.run(request).await;
if is\_home { res.headers\_mut().insert("Cache-Control", "max-age=10800")
}
res } ))
Eventually, we might add a feature that lets users customize their homepage. We might add a session layer to our router:
dioxus::server::router(app)
.layer(session\_layer) // a new session layer
.layer(caching\_layer)
dioxus::server::router(app)
.layer(session\_layer) // a new session layer
.layer(caching\_layer)
If we're not careful, we might accidentally cache a _logged-in user's_ homepage! Caching is typically based on the request's URL, but middleware also operate on headers. If we show dynamic content based on headers (like auth or sessions), we need to take care to only cache certain responses.
Many reverse proxies have the ability to configure caching based on request headers. We suggest diving into our deploy platform's reverse proxy setup, or implementing a smarter caching middleware yourself.
[PREVIOUSRouter and State](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum)
[NEXTWebsockets](https://dioxuslabs.com/learn/0.7/essentials/fullstack/websockets)
On this page
------------
* [What is Middleware?](https://dioxuslabs.com/learn/0.7/essentials/fullstack/middleware/#what-is-middleware)
* [Middleware on the Router](https://dioxuslabs.com/learn/0.7/essentials/fullstack/middleware/#middleware-on-the-router)
* [Middleware on individual Routes](https://dioxuslabs.com/learn/0.7/essentials/fullstack/middleware/#middleware-on-individual-routes)
* [Caching and Middleware](https://dioxuslabs.com/learn/0.7/essentials/fullstack/middleware/#caching-and-middleware)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Platform Support](https://dioxuslabs.com/learn/0.7/guides/platforms/)
[Desktop](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop)
This guide will cover concepts specific to the Dioxus desktop renderer.
Apps built with Dioxus desktop use the system WebView to render the page. This makes the final size of application much smaller than other WebView renderers (typically under 5MB).
Although desktop apps are rendered in a WebView, your Rust code runs natively. This means that browser APIs are _not_ available, so rendering WebGL, Canvas, etc is not as easy as the Web. However, native system APIs _are_ accessible, so streaming, WebSockets, the filesystem, etc are all easily accessible though system APIs.
Dioxus desktop is built on top of [wry](https://github.com/tauri-apps/wry)
, a Rust library for creating desktop applications with a WebView.
> In the future, we plan to move to a custom web renderer-based DOM renderer with WGPU integrations ([Blitz](https://github.com/DioxusLabs/blitz)
> ).
* [File Explorer](https://github.com/DioxusLabs/dioxus/tree/main/examples/file-explorer)
* [Tailwind App](https://github.com/DioxusLabs/dioxus/tree/main/examples/tailwind)
[](https://github.com/DioxusLabs/dioxus/tree/main/examples/tailwind)
Dioxus provides some ergonomic wrappers over the browser API, but in some cases you may need to access parts of the browser API Dioxus does not expose.
For these cases, Dioxus desktop exposes the use\_eval hook that allows you to run raw Javascript in the webview:
src/eval.rs
use dioxus::prelude::\*;
fn main() {
launch(app);
}
fn app() -> Element {
let future \= use\_resource(move || async move {
// You can create as many eval instances as you want
let mut eval \= document::eval(
r#"
// You can send messages from JavaScript to Rust with the dioxus.send function dioxus.send("Hi from JS!"); // You can receive messages from Rust to JavaScript with the dioxus.recv function let msg = await dioxus.recv(); console.log(msg); "#,
);
// You can send messages to JavaScript with the send method
eval.send("Hi from Rust!").unwrap();
// You can receive any message from JavaScript with the recv method
eval.recv::().await.unwrap()
});
match future.read\_unchecked().as\_ref() { Some(v) \=> rsx! {
p { "{v}" }
}, \_ \=> rsx! {
p { "hello" }
}, }
}
use dioxus::prelude::\*;
fn main() {
launch(app);
}
fn app() -> Element {
let future \= use\_resource(move || async move {
// You can create as many eval instances as you want
let mut eval \= document::eval(
r#"
// You can send messages from JavaScript to Rust with the dioxus.send function dioxus.send("Hi from JS!"); // You can receive messages from Rust to JavaScript with the dioxus.recv function let msg = await dioxus.recv(); console.log(msg); "#,
);
// You can send messages to JavaScript with the send method
eval.send("Hi from Rust!").unwrap();
// You can receive any message from JavaScript with the recv method
eval.recv::().await.unwrap()
});
match future.read\_unchecked().as\_ref() { Some(v) \=> rsx! {
p { "{v}" } }, \_ \=> rsx! {
p { "hello" } }, }
}
You can link to local assets in dioxus desktop instead of using a url:
src/custom\_assets.rs
use dioxus::prelude::\*;
fn main() {
launch(app);
}
fn app() -> Element {
rsx! { div { img { src: asset!("/assets/static/scanner.png") }
} }
}
use dioxus::prelude::\*;
fn main() {
launch(app);
}
fn app() -> Element {
rsx! { div { img { src: asset!("/assets/static/scanner.png") }
} }
}
In cases where you need more low level control over your window, you can use wry APIs exposed through the [Desktop Config](https://docs.rs/dioxus-desktop/latest/dioxus_desktop/struct.Config.html)
and the [use\_window hook](https://docs.rs/dioxus-desktop/latest/dioxus_desktop/fn.use_window.html)
[PREVIOUSWeb](https://dioxuslabs.com/learn/0.7/guides/platforms/web)
[NEXTMobile](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile)
On this page
------------
* [Examples](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop/#examples)
* [Running Javascript](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop/#running-javascript)
* [Custom Assets](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop/#custom-assets)
* [Integrating with Wry](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop/#integrating-with-wry)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Routing](https://dioxuslabs.com/learn/0.7/essentials/router/)
[Layouts](https://dioxuslabs.com/learn/0.7/essentials/router/layouts)
Layouts allow you to wrap all child routes in a component. This can be useful when creating something like a header that will be used in many different routes.
[`Outlet`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Outlet.html)
tells the router where to render content in layouts. In the following example, the Index will be rendered within the [`Outlet`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Outlet.html)
.
Here is a more complete example of a layout wrapping the body of a page.
src/outlet.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
#\[layout(Wrapper)\] #\[route("/")\]
Index {},
}
#\[component\]
fn Wrapper() -> Element {
rsx! { header { "header" }
// The index route will be rendered here
Outlet:: {}
footer { "footer" }
}
}
#\[component\]
fn Index() -> Element {
rsx! { h1 { "Index" } }
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
#\[layout(Wrapper)\] #\[route("/")\]
Index {},
}
#\[component\]
fn Wrapper() -> Element {
rsx! { header { "header" } // The index route will be rendered here
Outlet:: {}
footer { "footer" } }
}
#\[component\]
fn Index() -> Element {
rsx! { h1 { "Index" } }
}
The example above will output the following HTML (line breaks added for readability):
headerIndexfooterheaderIndexfooter
You can combine layouts with nested routes to create dynamic layouts with content that changes based on the current route.
Just like routes, layouts components must accept a prop for each dynamic segment in the route. For example, if you have a route with a dynamic segment like `/:name`, your layout component must accept a `name` prop:
src/outlet.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
#\[nest("/:name")\]
#\[layout(Wrapper)\] #\[route("/")\]
Index {
name: String,
},
}
#\[component\]
fn Wrapper(name: String) -> Element {
rsx! { header { "Welcome {name}!" }
// The index route will be rendered here
Outlet:: {}
footer { "footer" }
}
}
#\[component\]
fn Index(name: String) -> Element {
rsx! { h1 { "This is a homepage for {name}" } }
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
#\[nest("/:name")\]
#\[layout(Wrapper)\] #\[route("/")\]
Index {
name: String,
},
}
#\[component\]
fn Wrapper(name: String) -> Element {
rsx! { header { "Welcome {name}!" } // The index route will be rendered here
Outlet:: {}
footer { "footer" } }
}
#\[component\]
fn Index(name: String) -> Element {
rsx! { h1 { "This is a homepage for {name}" } }
}
Or to get the full route, you can use the `use_route` hook.
src/outlet.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
#\[layout(Wrapper)\] #\[route("/:name")\]
Index {
name: String,
},
}
#\[component\]
fn Wrapper() -> Element {
let full\_route \= use\_route::();
rsx! { header { "Welcome to {full\_route}!" }
// The index route will be rendered here
Outlet:: {}
footer { "footer" }
}
}
#\[component\]
fn Index(name: String) -> Element {
rsx! { h1 { "This is a homepage for {name}" } }
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
#\[layout(Wrapper)\] #\[route("/:name")\]
Index {
name: String,
},
}
#\[component\]
fn Wrapper() -> Element {
let full\_route \= use\_route::();
rsx! { header { "Welcome to {full\_route}!" } // The index route will be rendered here
Outlet:: {}
footer { "footer" } }
}
#\[component\]
fn Index(name: String) -> Element {
rsx! { h1 { "This is a homepage for {name}" } }
}
[PREVIOUSNavigation](https://dioxuslabs.com/learn/0.7/essentials/router/navigation)
[NEXTAdvanced Topics](https://dioxuslabs.com/learn/0.7/essentials/advanced/)
On this page
------------
* [Layouts with dynamic segments](https://dioxuslabs.com/learn/0.7/essentials/router/layouts/#layouts-with-dynamic-segments)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Static Site Generation](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation)
Static site generation (SSG) lets you pre-generate all static pages of your application at build time. Once you have the static HTML pages, you can deploy them to any static hosting provider like GitHub Pages.
SSG is extremely powerful since it lets you cache the rendering of your pages before deploying to production. This cuts down on bandwidth costs, lets you cache content on a CDN, and allows for deploying _without_ a server. Many deploy providers let you deploy SSG sites for free!
Dioxus SSG works by running your app locally, querying the app for a sitemap, and then indexing your site using `curl` requests manually. If your site is configured to use SSG, then it will cache HTML for each page on the filesystem.
This approach to SSG is quite different than a traditional static-site-generator like Hugo, Jekyll, or Zola. Dioxus SSG is designed to let you write your entire site in Rust, load data however you want, and then deploy a hybrid SSG app that loads SPA content.
Even if your app has a significant amount of static content, you might not actually need SSG. You should use SSG in a few cases:
* You have _lots_ of static content that benefits from pre-rendering before deploy
* You don't need a backend for your site
Sites like docs and portfolios benefit from SSG while apps like photo editors will not. In many cases, you can simply set `Cache-Control` headers while rendering pages and let your CDN or reverse-proxy handle caching for you!
SSG builds on top of the incremental rendering feature of Dioxus fullstack. We need to set up the `ServeConfig` to enable incremental rendering. The incremental config needs to render to the `public` directory where Dioxus places all other public files like the wasm binary and static assets. The `public` directory in the web folder will always be placed alongside the server binary.
src/static\_site\_generation.rs
fn main() {
dioxus::LaunchBuilder::new()
// Set the server config only if we are building the server target
.with\_cfg(server\_only! { ServeConfig::builder()
// Enable incremental rendering
.incremental( dioxus::server::IncrementalRendererConfig::new()
// Store static files in the public directory where other static assets like wasm are stored
.static\_dir( std::env::current\_exe() .unwrap() .parent() .unwrap() .join("public")
) // Don't clear the public folder on every build. The public folder has other files including the wasm
// binary and static assets required for the app to run
.clear\_cache(false)
) .enable\_out\_of\_order\_streaming() }) .launch(app);
}
fn main() {
dioxus::LaunchBuilder::new()
// Set the server config only if we are building the server target
.with\_cfg(server\_only! { ServeConfig::builder()
// Enable incremental rendering
.incremental( dioxus::server::IncrementalRendererConfig::new()
// Store static files in the public directory where other static assets like wasm are stored
.static\_dir( std::env::current\_exe() .unwrap() .parent() .unwrap() .join("public")
) // Don't clear the public folder on every build. The public folder has other files including the wasm
// binary and static assets required for the app to run
.clear\_cache(false)
) .enable\_out\_of\_order\_streaming() }) .launch(app);
}
Once you have incremental rendering enabled, you need to tell the CLI about the static routes in your app. The CLI looks for a server function at the endpoint `"static_routes"` that returns a list of all static urls. It will call this server function at build time and pre-render all of the routes in the list.
src/static\_site\_generation.rs
#\[derive(Routable, Clone, PartialEq)\]
pub enum Route {
// Any routes with no dynamic segments in your router will be included in the static routes list
#\[route("/")\]
Index {},
#\[route("/other")\]
Other {},
}
// The server function at the endpoint "static\_routes" will be called by the CLI to generate the list of static
// routes. You must explicitly set the endpoint to \`"static\_routes"\` in the server function attribute instead of
// the default randomly generated endpoint.
#\[server(endpoint \= "static\_routes", output \= server\_fn::codec::Json)\]
async fn static\_routes() -> Result, ServerFnError> {
// The \`Routable\` trait has a \`static\_routes\` method that returns all static routes in the enum
Ok(Route::static\_routes()
.iter() .map(ToString::to\_string)
.collect())
}
#\[derive(Routable, Clone, PartialEq)\]
pub enum Route {
// Any routes with no dynamic segments in your router will be included in the static routes list
#\[route("/")\]
Index {},
#\[route("/other")\]
Other {},
}
// The server function at the endpoint "static\_routes" will be called by the CLI to generate the list of static
// routes. You must explicitly set the endpoint to \`"static\_routes"\` in the server function attribute instead of
// the default randomly generated endpoint.
#\[server(endpoint \= "static\_routes", output \= server\_fn::codec::Json)\]
async fn static\_routes() -> Result, ServerFnError> {
// The \`Routable\` trait has a \`static\_routes\` method that returns all static routes in the enum
Ok(Route::static\_routes()
.iter() .map(ToString::to\_string)
.collect())
}
Finally, you can bundle your site with `dx bundle --web --ssg`. Once the CLI finishes bundling, you should see a `public` folder in the dx folder of your project:
The folder contains all of the static assets that you need to serve your site. You can copy the public folder into any static hosting provider like GitHub Pages.
[PREVIOUSHTML Streaming](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming)
[NEXTRouting](https://dioxuslabs.com/learn/0.7/essentials/router/)
On this page
------------
* [How Dioxus SSG works](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation/#how-dioxus-ssg-works)
* [You might not need SSG](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation/#you-might-not-need-ssg)
* [Setting up the ServeConfig](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation/#setting-up-the-serveconfig)
* [Configuring static routes](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation/#configuring-static-routes)
* [Publishing static sites](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation/#publishing-static-sites)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Native Clients](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native)
So far, we've focused on using fullstack alongside a web application. However, not all apps you'll build with Dioxus will be loaded in a web browser. Dioxus supports mobile apps and desktop apps as well.
On these platforms, fullstack works a bit differently. You can still use server functions, but things like server-side-rendering no-longer apply.
Developing a native fullstack app works just the same as developing a fullstack web app. Make sure your `Cargo.toml` has the appropriate features:
\[dependencies\]
dioxus \= { version \= "0.7", features \= \["fullstack"\] }
\[features\]
server \= \["dioxus/server"\]
desktop \= \["dioxus/desktop"\]
\[dependencies\]
dioxus \= { version \= "0.7", features \= \["fullstack"\] }
\[features\]
server \= \["dioxus/server"\]
desktop \= \["dioxus/desktop"\]
And then, to serve the app, use `dx serve --`:
dx serve --desktop
dx serve --desktop
When you build a native app that relies on server functions, you can freely call any server function just as you would with a web app.
This simple hello world app works the same on web, desktop, and mobile:
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| { let mut message \= use\_action(get\_message);
rsx! { h1 { "Server says: "}
pre { "{message:?}"}
button { onclick: move |\_| message.call("world".into(), 30), "Click me!" }
} });
}
#\[get("/api/{name}/?age")\]
async fn get\_message(name: String, age: i32) -> Result {
Ok(format!("Hello {}, you are {} years old!", name, age))
}
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| { let mut message \= use\_action(get\_message);
rsx! { h1 { "Server says: "}
pre { "{message:?}"}
button { onclick: move |\_| message.call("world".into(), 30), "Click me!" } } });
}
#\[get("/api/{name}/?age")\]
async fn get\_message(name: String, age: i32) -> Result {
Ok(format!("Hello {}, you are {} years old!", name, age))
}
Your native code can still make requests to your backend. However, when if you deployed your app to production, you might notice that the native app _does not know where to make requests_.
In the web, requests are always made to the current host origin. For example, requests to this endpoint are made to `/api/dogs`:
#\[get("/api/dogs")\]
async fn get\_message() -> Result<()> {
// ..
}
#\[get("/api/dogs")\]
async fn get\_message() -> Result<()> {
// ..
}
Desktop and mobiles are not served from a specific URL, and thus do not know which host to make a request to.
To set a specific server URL, you must call `set_server_url` before making any requests:
fn main() {
#\[cfg(not(feature \= "server"))\]
dioxus::fullstack::set\_server\_url("https://hot-dog.fly.dev");
dioxus::launch(app);
}
fn main() {
#\[cfg(not(feature \= "server"))\]
dioxus::fullstack::set\_server\_url("https://hot-dog.fly.dev");
dioxus::launch(app);
}
This ensures that requests are always properly joined with the correct host.
When using fullstack with native apps, a number of features and optimizations are disabled. Native apps are usually meant to be used offline, so their rendering needs to happen entirely on the client. Architecturally, native apps are similar to single-page-applications (SPA) where the bundle loads and _then_ HTTP requests are made to load content.
As such, a number of features are disabled:
* There is no hydration context, and thus no hydration data to hydrate the page
* The app is never rendered on the server, skipping `#[cfg(feature = "server")]` code
* There is no `FullstackContext` when rendering components
* HTML Streaming and SSG have no effect
Functionally, this won't change how you build your apps, but you should be aware that some code might never be executed.
Dioxus supports two ways of annotating server functions:
* Explicitly with `#[get]`, `#[post]`, `#[delete]`, etc.
* Anonymously with `#[server]`
When you use the `#[server]` macro, the endpoint path is free to change as you update the endpoint's signature and body. If you re-redeploy your backend, URLs that worked previously are not guaranteed to exist in the future.
// â this endpoint generates \`/api/do\_it12nldkj2378jnakls\`
#\[server\]
async fn do\_it() -> Result<()> {
//
}
// â this endpoint generates \`/api/do\_it12nldkj2378jnakls\`
#\[server\]
async fn do\_it() -> Result<()> {
//
}
Because the endpoint receives a hash, its name is unique and might change as you update its code.
When using server functions with native clients, we strongly recommend using the `#[get]` / `#[post]` annotations since they guarantee a stable endpoint.
// â This endpoint is stable
#\[post("/api/do\_it")\]
async fn do\_it() -> Result<()> {
//
}
// â This endpoint is stable
#\[post("/api/do\_it")\]
async fn do\_it() -> Result<()> {
//
}
Because native clients are distributed as downloadable software, they might not always up to date as the latest version of your code. This can be particularly challenging when you want to update the signature of an endpoint.
// version 1
#\[post("/api/do\_it")\]
async fn do\_it() -> Result<()> { /\* \*/ }
// version 2
// â we are breaking old clients!
#\[post("/api/do\_it")\]
async fn do\_it(name: String) -> Result<()> { /\* \*/ }
// version 1
#\[post("/api/do\_it")\]
async fn do\_it() -> Result<()> { /\* \*/ }
// version 2
// â we are breaking old clients!
#\[post("/api/do\_it")\]
async fn do\_it(name: String) -> Result<()> { /\* \*/ }
We hope this problem is obvious to you - if you re-redploy your backend with breaking changes, previous clients will break!
To upgrade APIs, we recommend one of two options:
* Use `Option` to add new fields
* Use `/api/v1`, `/api/v2/` versioning
For most API upgrades, you can simply add new fields by making new values optional with `Option`:
// version 2
// â Option means \`name\` is not required
#\[post("/api/do\_it")\]
async fn do\_it(name: Option) -> Result<()> { /\* \*/ }
// version 2
// â Option means \`name\` is not required
#\[post("/api/do\_it")\]
async fn do\_it(name: Option) -> Result<()> { /\* \*/ }
For API changes that require much larger changes, we recommend using a versioning scheme to create different versions of the API accessible by the client:
// This is at /api/v1/
#\[post("/api/v1/do\_it")\]
async fn do\_it() -> Result<()> { /\* \*/ }
// This is at api/v2
#\[post("/api/v2/do\_it")\]
async fn do\_it(name: String) -> Result<()> { /\* \*/ }
// This is at /api/v1/
#\[post("/api/v1/do\_it")\]
async fn do\_it() -> Result<()> { /\* \*/ }
// This is at api/v2
#\[post("/api/v2/do\_it")\]
async fn do\_it(name: String) -> Result<()> { /\* \*/ }
Creating different API versions is common practice and helps prevent breaking old clients as you update your app.
You can deploy native fullstack apps just the same as you would deploy a regular web app. Server apps always generate a `server` binary and a `/public/` folder. Native apps will generate an app bundle ( `.app`, `.ipa`, `.apk`, etc).
You can distribute the native app via an app store or by making the file downloadable to your users.
To distribute the server, simply upload it to a hosting provider of your choice. As long as you set the `server_url` in the native app, you should be able to access your backend from the native client.
[PREVIOUSAuthentication](https://dioxuslabs.com/learn/0.7/essentials/fullstack/authentication)
[NEXTHTML Streaming](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming)
On this page
------------
* [Developing a Native Fullstack App](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native/#developing-a-native-fullstack-app)
* [Server Functions for Native App](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native/#server-functions-for-native-app)
* [Disabled Fullstack Features](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native/#disabled-fullstack-features)
* [Prefer Known Endpoints](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native/#prefer-known-endpoints)
* [Versioning](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native/#versioning)
* [Deploying](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native/#deploying)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Advanced Topics](https://dioxuslabs.com/learn/0.7/essentials/advanced/)
[Component Lifecycle](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle)
`use_hook` lets you create new state for your component. The closure you pass to `use_hook` will be called once the first time the component is rendered. Every time the component is re-rendered, the value that was created the first run will be re-used.
src/component\_lifecycle.rs
fn UseHook() -> Element {
// The closure that is passed to use\_hook will be called once the first time the component is rendered
let random\_number \= use\_hook(|| {
let new\_random\_number \= random\_number();
log!("{new\_random\_number}");
new\_random\_number });
rsx! { div { "Random {random\_number}" }
}
}
fn UseHook() -> Element {
// The closure that is passed to use\_hook will be called once the first time the component is rendered
let random\_number \= use\_hook(|| {
let new\_random\_number \= random\_number();
log!("{new\_random\_number}");
new\_random\_number });
rsx! { div { "Random {random\_number}" } }
}
đ
Random 13.97
Logs
13.97
You can use tracked values to re-render your component whenever a value changes.
src/component\_lifecycle.rs
fn Rerenders() -> Element {
let mut count \= use\_signal(|| 0);
log!("Rerendering parent component with {}", \*count.peek());
rsx! { button { onclick: move |\_| count += 1, "Increment" }
// Since we read count here, the component will rerender when count changes
Count { current\_count: count() }
}
}
// If the count prop changes, the component will rerender
#\[component\]
fn Count(current\_count: i32) -> Element {
log!("Rerendering child component with {current\_count}");
rsx! { div { "The count is {current\_count}" }
}
}
fn Rerenders() -> Element {
let mut count \= use\_signal(|| 0);
log!("Rerendering parent component with {}", \*count.peek());
rsx! { button { onclick: move |\_| count += 1, "Increment" } // Since we read count here, the component will rerender when count changes
Count { current\_count: count() }
}
}
// If the count prop changes, the component will rerender
#\[component\]
fn Count(current\_count: i32) -> Element {
log!("Rerendering child component with {current\_count}");
rsx! { div { "The count is {current\_count}" } }
}
Increment
The count is 0
Logs
Rerendering child component with 0
Rerendering parent component with 0
You should avoid changing state in the body of a component. If you read and write to state in the body of a component, you can cause an infinite loop as the component tries to rerender because of the change which triggers another state change.
src/component\_lifecycle.rs
fn Bad() -> Element {
let mut count \= use\_signal(|| 0);
// â Don't mutate state in the body of the component.
// It can easily cause an infinite loop!
count += 1;
rsx! { "{count}" }
}
fn Bad() -> Element {
let mut count \= use\_signal(|| 0);
// â Don't mutate state in the body of the component.
// It can easily cause an infinite loop!
count += 1;
rsx! { "{count}" }
}
Instead, derive state with `use_memo`, `use_resource`, or mutate state in a effect.
You can use effects to run code whenever a component is rendered.
src/component\_lifecycle.rs
fn Effect() -> Element {
// Effects run after the component is rendered
// You can use them to read or modify the rendered component
use\_effect(|| { log!("Effect ran");
document::eval(&format!(
"document.getElementById('effect-output').innerText = 'Effect ran'"
)); });
rsx! { div { id: "effect-output", "This will be changed by the effect" }
}
}
fn Effect() -> Element {
// Effects run after the component is rendered
// You can use them to read or modify the rendered component
use\_effect(|| { log!("Effect ran");
document::eval(&format!(
"document.getElementById('effect-output').innerText = 'Effect ran'"
)); });
rsx! { div { id: "effect-output", "This will be changed by the effect" } }
}
This will be changed by the effect
Logs
Before a component is dropped, it will drop all of its hooks. You can use this drop behavior to clean up any resources that your component is using. If you just need the drop effect, you can use the [`use_drop`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_drop.html)
hook.
src/component\_lifecycle.rs
fn TogglesChild() -> Element {
let mut show \= use\_signal(|| true);
rsx! { button { onclick: move |\_| show.toggle(), "Toggle" }
if show() {
Child {}
} }
}
fn Child() -> Element {
// You can use the use\_drop hook to clean up any resources
dioxus::core::use\_drop(|| { log!("Child dropped");
});
rsx! { div { "Child" }
}
}
fn TogglesChild() -> Element {
let mut show \= use\_signal(|| true);
rsx! { button { onclick: move |\_| show.toggle(), "Toggle" } if show() {
Child {}
} }
}
fn Child() -> Element {
// You can use the use\_drop hook to clean up any resources
dioxus::core::use\_drop(|| { log!("Child dropped");
});
rsx! { div { "Child" } }
}
Toggle
Child
Logs
[PREVIOUSCustom Hooks](https://dioxuslabs.com/learn/0.7/essentials/advanced/custom_hooks)
[NEXTBreaking Out](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out)
On this page
------------
* [Initializing State with use\_hook](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle/#initializing-state-with-use-hook)
* [Rerendering](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle/#rerendering)
* [â ïž Don't mutate state in the body of a component](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle/#-dont-mutate-state-in-the-body-of-a-component)
* [Using Effects](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle/#using-effects)
* [Cleaning Up Components with Drop](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle/#cleaning-up-components-with-drop)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Websockets](https://dioxuslabs.com/learn/0.7/essentials/fullstack/websockets)
Dioxus Fullstack provides built-in types for creating and managing websockets that work alongside server functions. Dioxus websockets are built on top of the underlying Axum websocket API, but with a few improvements tailored for fullstack apps:
* Shared server/client types
* Reactive wrappers for use in UI code
* Typed inputs, outputs, and customizable encoding
Websockets are an extremely powerful communication protocol that allows bidirectional message passing to and from the server. Websockets are more efficient than HTTP requests for large amounts of messages, provide better real-time support, and allow for _ordered_ data transmission.
Note that websockets are _stateful_, meaning that a websocket connection ties a client and server together for a given session. If you plan to use websockets in a "serverless" environment with time limits of request handling, then you need some way to "store" the websocket session across multiple requests.
To create a new server function that returns a websocket, simply use `WebsocketOptions` as your body type and `Websocket` as your response type.
#\[get("/api/uppercase\_ws")\]
async fn uppercase\_ws(options: WebSocketOptions) -> Result {
Ok(options.on\_upgrade(move |mut socket| async move {
// send back a greeting message
\_ \= socket .send("Hello!".to\_string())
.await;
// Loop and echo back uppercase messages
while let Ok(msg) \= socket.recv().await {
\_ \= socket.send(msg.to\_ascii\_uppercase()).await;
} }))
}
#\[get("/api/uppercase\_ws")\]
async fn uppercase\_ws(options: WebSocketOptions) -> Result {
Ok(options.on\_upgrade(move |mut socket| async move {
// send back a greeting message
\_ \= socket .send("Hello!".to\_string())
.await;
// Loop and echo back uppercase messages
while let Ok(msg) \= socket.recv().await {
\_ \= socket.send(msg.to\_ascii\_uppercase()).await;
} }))
}
The `Websocket` type is generic over three parameters - the input type, output type, and encoding:
pub struct Websocket { // ...
}
pub struct Websocket { // ...
}
The input and output types are the types used when you call `.send()` and `.recv()` on the `socket` object provided after `on_upgrade`. By strongly typing the websocket, we guarantee that your client and server always use the right message format across the client and server.
The `on_upgrade` method is a wrapper over the underlying Axum `on_upgrade` API that returns an axum response, indicating to the client that the websocket upgrade process is successful. If the client agrees, then the server will run the `on_upgrade` callback, spawning the future. Note that this future is spawned on a tokio [LocalSet](https://docs.rs/tokio/latest/tokio/task/struct.LocalSet.html)
. This means the future does not need to be `Send`.
We can use our own message types for the input and output messages. Calls to `.send()` and `.recv()` will attempt to deserialize messages into the right type, returning an error if the deserialization fails.
// Events flowing \*from\* the client to the server
#\[derive(Serialize, Deserialize, Debug)\]
enum ClientEvent {
TextInput(String),
}
// Events flowing \*to\* the client from the server
#\[derive(Serialize, Deserialize, Debug)\]
enum ServerEvent {
Uppercase(String),
}
#\[get("/api/uppercase\_ws")\]
async fn uppercase\_ws(options: WebSocketOptions) -> Result> {
// ...
}
// Events flowing \*from\* the client to the server
#\[derive(Serialize, Deserialize, Debug)\]
enum ClientEvent {
TextInput(String),
}
// Events flowing \*to\* the client from the server
#\[derive(Serialize, Deserialize, Debug)\]
enum ServerEvent {
Uppercase(String),
}
#\[get("/api/uppercase\_ws")\]
async fn uppercase\_ws(options: WebSocketOptions) -> Result> {
// ...
}
We can also customize the encoding of the websocket with the third generic on `Websocket`. By default, messages are encoded using JSON with `JsonEncoding`, but you can opt for an alternative format like the binary Cbor format with `CborEncoding`:
#\[get("/api/uppercase\_ws")\]
async fn uppercase\_ws(options: WebSocketOptions) -> Result> {
// ...
}
#\[get("/api/uppercase\_ws")\]
async fn uppercase\_ws(options: WebSocketOptions) -> Result> {
// ...
}
Generally, if you're working with Rust-only clients, then Cbor or MsgPack are better options, but 3rd-party clients might be better suited with the standard JSON encoding.
If you need to send extra details to the server before establishing the websocket connection, you can use path and query parameters as well as header extraction like usual.
#\[get("/api/uppercase\_ws?name&age")\]
async fn uppercase\_ws(
name: String,
age: i32,
options: WebSocketOptions,
) -> Result> {
// ...
}
#\[get("/api/uppercase\_ws?name&age")\]
async fn uppercase\_ws(
name: String,
age: i32,
options: WebSocketOptions,
) -> Result> {
// ...
}
On the client, to connect to a websocket, we'll simply call the server function and await the result. You might do this inside a `use_future` hook to connect to the websocket endpoint when the component is mounted:
// Calling \`.recv()\` automatically waits for the connection to be established and deserializes
// messages as they arrive.
use\_future(move || async move {
// Connect to the websocket
let socket \= uppercase\_ws(WebSocketOptions::new()).await;
// Wait for the next message with \`.recv()\`
while let Ok(msg) \= socket.recv().await {
messages.push(msg); }
});
// Calling \`.recv()\` automatically waits for the connection to be established and deserializes
// messages as they arrive.
use\_future(move || async move {
// Connect to the websocket
let socket \= uppercase\_ws(WebSocketOptions::new()).await;
// Wait for the next message with \`.recv()\`
while let Ok(msg) \= socket.recv().await {
messages.push(msg); }
});
The `Websocket` object has a number of utility methods you can use to assess the state of the connection, send messages, and receive messages. We expose a number of lower-level APIs like `send_raw` that let you send raw websocket frames in case the typed API is too strict.
You might notice in the `use_future` example above, the websocket is only accessible to its containing scope. In a practical app, you'll want to send messages into the websocket and react to any changes in connection status.
The `use_websocket` hook wraps the `websocket` object with signal-based reactivity. We can use `.status()` to read the websocket connection state, and `.send()` to send messages to the server.
To connect to the websocket, we might use `use_websocket`:
// The \`use\_websocket\` wraps the \`WebSocket\` connection and provides a reactive handle to easily
// send and receive messages and track the connection state.
//
// We can customize the websocket connection with the \`WebSocketOptions\` struct, allowing us to
// set things like custom headers, protocols, reconnection strategies, etc.
let mut socket \= use\_websocket(|| uppercase\_ws("John Doe".into(), 30, WebSocketOptions::new()));
// The \`use\_websocket\` wraps the \`WebSocket\` connection and provides a reactive handle to easily
// send and receive messages and track the connection state.
//
// We can customize the websocket connection with the \`WebSocketOptions\` struct, allowing us to
// set things like custom headers, protocols, reconnection strategies, etc.
let mut socket \= use\_websocket(|| uppercase\_ws("John Doe".into(), 30, WebSocketOptions::new()));
To listen for messages, we can use `.recv()` in a future:
// Calling \`.recv()\` automatically waits for the connection to be established and deserializes
// messages as they arrive.
use\_future(move || async move {
while let Ok(msg) \= socket.recv().await {
messages.push(msg); }
});
// Calling \`.recv()\` automatically waits for the connection to be established and deserializes
// messages as they arrive.
use\_future(move || async move {
while let Ok(msg) \= socket.recv().await {
messages.push(msg); }
});
And then to send messages, we can use `.send()` on the handle:
rsx! {
input { placeholder: "Type a message",
oninput: move |e| async move {
\_ \= socket.send(ClientEvent::TextInput(e.value())).await;
}, }
}
rsx! {
input { placeholder: "Type a message",
oninput: move |e| async move {
\_ \= socket.send(ClientEvent::TextInput(e.value())).await;
}, }
}
If the connection fails, you can restart it by manually calling `.set()` on the handle with a new websocket object.
[PREVIOUSMiddleware](https://dioxuslabs.com/learn/0.7/essentials/fullstack/middleware)
[NEXTStreams and SSE](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streams)
On this page
------------
* [Websocket and WebsocketOptions](https://dioxuslabs.com/learn/0.7/essentials/fullstack/websockets/#websocket-and-websocketoptions)
* [Connecting to a Websocket](https://dioxuslabs.com/learn/0.7/essentials/fullstack/websockets/#connecting-to-a-websocket)
* [The use\_websocket hook](https://dioxuslabs.com/learn/0.7/essentials/fullstack/websockets/#the-use-websocket-hook)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Utilities](https://dioxuslabs.com/learn/0.7/guides/utilities/)
[Internationalization](https://dioxuslabs.com/learn/0.7/guides/utilities/internationalization)
If your application supports multiple languages, the [dioxus-i18n](https://github.com/dioxus-community/dioxus-i18n)
crate contains helpers to make working with translations in your application easier.
You can find an example [here](https://github.com/dioxus-community/dioxus-i18n/blob/main/examples/dioxus-desktop.rs)
.
[PREVIOUSLogging](https://dioxuslabs.com/learn/0.7/guides/utilities/logging)
[NEXTTailwind](https://dioxuslabs.com/learn/0.7/guides/utilities/tailwind)
On this page
------------
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Platform Support](https://dioxuslabs.com/learn/0.7/guides/platforms/)
[Mobile](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile)
Build a mobile app with Dioxus!
The Rust ecosystem for mobile continues to mature, with Dioxus offering strong support for mobile applications. Mobile is a first-class target for Dioxus apps, with a robust WebView implementation that supports CSS animations and transparency effects.
Mobile apps are rendered with either the platform's WebView or experimentally with WGPU. While native Android animations and widgets aren't currently supported, CSS-based animations and styling provide a powerful alternative.
Mobile support is well-suited for most application types, from business tools to consumer apps, making it an excellent choice for teams looking to build cross-platform applications with a single codebase.
Android devices run a different executable architecture than desktop and web. We need to install these toolchains to build Dioxus apps for Android.
First, install the Rust Android targets:
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86\_64-linux-android
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86\_64-linux-android
To develop on Android, you will need to [install Android Studio](https://developer.android.com/studio)
.
Once you have installed Android Studio, you will need to install the Android SDK and NDK:
1. Create a blank Android project
2. Select `Tools > SDK manager`
3. Navigate to the `SDK tools` window:
Then select:
* The SDK
* The SDK Command line tools
* The NDK (side by side)
* CMAKE
1. Select `apply` and follow the prompts
> More details that could be useful for debugging any errors you encounter are available [in the official android docs](https://developer.android.com/studio/intro/update#sdk-manager)
Next set the Java, Android, NDK, and PATH variables:
Mac:
export JAVA\_HOME\="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
export ANDROID\_HOME\="$HOME/Library/Android/sdk"
export NDK\_HOME\="$ANDROID\_HOME/ndk/25.2.9519653"
export PATH\="$PATH:$ANDROID\_HOME/emulator:$ANDROID\_HOME/platform-tools"
export JAVA\_HOME\="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
export ANDROID\_HOME\="$HOME/Library/Android/sdk"
export NDK\_HOME\="$ANDROID\_HOME/ndk/25.2.9519653"
export PATH\="$PATH:$ANDROID\_HOME/emulator:$ANDROID\_HOME/platform-tools"
Windows:
\[System.Environment\]::SetEnvironmentVariable("JAVA\_HOME", "C:\\Program Files\\Android\\Android Studio\\jbr", "User")
\[System.Environment\]::SetEnvironmentVariable("ANDROID\_HOME", "$env:LocalAppData\\Android\\Sdk", "User")
\[System.Environment\]::SetEnvironmentVariable("NDK\_HOME", "$env:LocalAppData\\Android\\Sdk\\ndk\\25.2.9519653", "User")
\[System.Environment\]::SetEnvironmentVariable("JAVA\_HOME", "C:\\Program Files\\Android\\Android Studio\\jbr", "User")
\[System.Environment\]::SetEnvironmentVariable("ANDROID\_HOME", "$env:LocalAppData\\Android\\Sdk", "User")
\[System.Environment\]::SetEnvironmentVariable("NDK\_HOME", "$env:LocalAppData\\Android\\Sdk\\ndk\\25.2.9519653", "User")
> The NDK version in the paths should match the version you installed in the last step
We manually set the PATH variable to include the Android emulator since some distributions of Android Studio include the emulator in the wrong location.
To develop on IOS, you will need to [install XCode](https://apps.apple.com/us/app/xcode/id497799835)
. Also make sure to install the iOS targets
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
> If you are using M1, you will have to run `cargo build --target x86_64-apple-ios` instead of `cargo apple build` if you want to run in simulator.
You will also need to install the iOS SDK and the Xcode command line tools.
Starting with Dioxus 0.6, `dx` ships with built-in support for mobile.
Simply create a new Dioxus project:
dx new my-app
dx new my-app
Make sure to launch the relevant mobile simulator. For Android, you can use the Android Studio emulator, or the Android Emulator in the terminal. Make sure to adjust the device name depending on which emulator you installed.
emulator -avd Pixel\_6\_API\_34 -netdelay none -netspeed full
emulator -avd Pixel\_6\_API\_34 -netdelay none -netspeed full
For iOS, you can use the iOS simulator. You can launch it with:
open /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app
xcrun simctl boot "iPhone 15 Pro Max"
open /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app
xcrun simctl boot "iPhone 15 Pro Max"
And then run the app with:
cd my-app
dx serve
cd my-app
dx serve
This will start the app in development mode.
[PREVIOUSDesktop](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop)
[NEXTPublishing](https://dioxuslabs.com/learn/0.7/guides/deploy/)
On this page
------------
* [Support](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile/#support)
* [Getting Set up](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile/#getting-set-up)
* [Android](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile/#android)
* [IOS](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile/#ios)
* [Running your app](https://dioxuslabs.com/learn/0.7/guides/platforms/mobile/#running-your-app)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Platform Support](https://dioxuslabs.com/learn/0.7/guides/platforms/)
[Web](https://dioxuslabs.com/learn/0.7/guides/platforms/web)
To run on the Web, your app must be compiled to WebAssembly and depend on the `dioxus` and `dioxus-web` crates.
A build of Dioxus for the web will be roughly equivalent to the size of a React build (70kb vs 65kb) but it will load significantly faster because [WebAssembly can be compiled as it is streamed](https://hacks.mozilla.org/2018/01/making-webassembly-even-faster-firefoxs-new-streaming-and-tiering-compiler/)
.
Examples:
* [TodoMVC](https://github.com/DioxusLabs/dioxus/blob/main/examples/todomvc.rs)
* [Tailwind App](https://github.com/DioxusLabs/dioxus/tree/main/examples/tailwind)
[](https://github.com/DioxusLabs/dioxus/blob/main/examples/todomvc.rs)
> Note: Because of the limitations of Wasm, [not every crate will work](https://rustwasm.github.io/docs/book/reference/which-crates-work-with-wasm.html)
> with your web apps, so you'll need to make sure that your crates work without native system calls (timers, IO, etc).
The Web is the best-supported target platform for Dioxus.
* Because your app will be compiled to WASM you have access to browser APIs through [wasm-bindgen](https://rustwasm.github.io/docs/wasm-bindgen/introduction.html)
.
* Dioxus provides hydration to resume apps that are rendered on the server. See the [fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
reference for more information.
Dioxus provides some ergonomic wrappers over the browser API, but in some cases you may need to access parts of the browser API Dioxus does not expose.
For these cases, Dioxus web exposes the use\_eval hook that allows you to run raw Javascript in the webview:
src/eval.rs
use dioxus::prelude::\*;
fn main() {
launch(app);
}
fn app() -> Element {
let future \= use\_resource(move || async move {
// You can create as many eval instances as you want
let mut eval \= document::eval(
r#"
// You can send messages from JavaScript to Rust with the dioxus.send function dioxus.send("Hi from JS!"); // You can receive messages from Rust to JavaScript with the dioxus.recv function let msg = await dioxus.recv(); console.log(msg); "#,
);
// You can send messages to JavaScript with the send method
eval.send("Hi from Rust!").unwrap();
// You can receive any message from JavaScript with the recv method
eval.recv::().await.unwrap()
});
match future.read\_unchecked().as\_ref() { Some(v) \=> rsx! {
p { "{v}" }
}, \_ \=> rsx! {
p { "hello" }
}, }
}
use dioxus::prelude::\*;
fn main() {
launch(app);
}
fn app() -> Element {
let future \= use\_resource(move || async move {
// You can create as many eval instances as you want
let mut eval \= document::eval(
r#"
// You can send messages from JavaScript to Rust with the dioxus.send function dioxus.send("Hi from JS!"); // You can receive messages from Rust to JavaScript with the dioxus.recv function let msg = await dioxus.recv(); console.log(msg); "#,
);
// You can send messages to JavaScript with the send method
eval.send("Hi from Rust!").unwrap();
// You can receive any message from JavaScript with the recv method
eval.recv::().await.unwrap()
});
match future.read\_unchecked().as\_ref() { Some(v) \=> rsx! {
p { "{v}" } }, \_ \=> rsx! {
p { "hello" } }, }
}
If you are targeting web, but don't plan on targeting any other Dioxus renderer you can also use the generated wrappers in the [web-sys](https://rustwasm.github.io/wasm-bindgen/web-sys/index.html)
and [gloo](https://gloo-rs.web.app/)
crates.
Dioxus supports providing custom index.html templates. The index.html must include a `div` with the id `main` to be used. Hot Reload is still supported. An example is provided in the [PWA-Example](https://github.com/DioxusLabs/dioxus/blob/main/examples/10-integrations/pwa/index.html)
.
[PREVIOUSPlatform Support](https://dioxuslabs.com/learn/0.7/guides/platforms/)
[NEXTDesktop](https://dioxuslabs.com/learn/0.7/guides/platforms/desktop)
On this page
------------
* [Support](https://dioxuslabs.com/learn/0.7/guides/platforms/web/#support)
* [Running Javascript](https://dioxuslabs.com/learn/0.7/guides/platforms/web/#running-javascript)
* [Customizing Index Template](https://dioxuslabs.com/learn/0.7/guides/platforms/web/#customizing-index-template)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Router and State](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum)
Dioxus fullstack is built on the popular backend crate Axum. The default `dioxus::launch` function will initialize a default Axum server for your fullstack project. If you need more control, you can easily customize the router with `dioxus::serve`.
The `dioxus::serve` function is the primary entrypoint for Dioxus apps that run on the server, as is standard in fullstack applications. For fullstack apps, you'll typically use both `dioxus::launch` and `dioxus::serve`, enabling each entrypoint based on the `"server"` feature.
fn main() {
// Run \`serve()\` on the server only
#\[cfg(feature \= "server")\]
dioxus::serve(|| async move {
// Create a new router for our app using the \`router\` function
let mut router \= dioxus::server::router(app);
// .. customize the router, adding layers and new routes
// And then return the router
Ok(router)
});
// When not on the server, just run \`launch()\` like normal
#\[cfg(not(feature \= "server"))\]
dioxus::launch(app);
}
fn main() {
// Run \`serve()\` on the server only
#\[cfg(feature \= "server")\]
dioxus::serve(|| async move {
// Create a new router for our app using the \`router\` function
let mut router \= dioxus::server::router(app);
// .. customize the router, adding layers and new routes
// And then return the router
Ok(router)
});
// When not on the server, just run \`launch()\` like normal
#\[cfg(not(feature \= "server"))\]
dioxus::launch(app);
}
Note how we use Rust's built-in `#[cfg]` macro to conditionally launch the app based on the `server` feature. When `server` feature is enabled, we enable `dioxus::serve`, and when it is disabled, we enable `dioxus::launch`.
The `dioxus::server::router` function creates a new axum router that sets up a few important pieces:
* Static Assets: automatically serve the `public` directory, index.html and assets
* SSR: automatically run the app, render it to HTML, and serialize data for hydration
* Server Functions: automatically initialize the API endpoints
Dioxus uses extension methods on the Axum router (given by `DioxusRouterExt`) that is equivalent to enabling each of these items manually:
axum::Router::new()
.register\_server\_functions()
.serve\_static\_assets()
.fallback(
get(render\_handler).with\_state(RenderHandleState::new(cfg, app)),
)
axum::Router::new()
.register\_server\_functions()
.serve\_static\_assets()
.fallback(
get(render\_handler).with\_state(RenderHandleState::new(cfg, app)),
)
When you use `dioxus::server::router` or `dioxus::launch` to start your fullstack server, Dioxus Fullstack registers all server functions for you automatically. This means you can quickly build your backend without needing to explicitly wire up endpoints to a central router.
If you need more control with a custom axum setup, you can manually iterate through the list of global server functions and register single endpoints, or create new routers with a subset of routes with `ServerFunction::collect()`:
// We can iterate through all server functions:
for func in ServerFunction::collect() {
// Read their data
tracing::info!(
"Registering server function: {} {}",
func.method(),
func.path()
);
// And add them to our router
router \= func.register\_server\_fn\_on\_router(router);
}
// We can iterate through all server functions:
for func in ServerFunction::collect() {
// Read their data
tracing::info!(
"Registering server function: {} {}",
func.method(),
func.path()
);
// And add them to our router
router \= func.register\_server\_fn\_on\_router(router);
}
One common use-case of a custom axum router is to add new routes to the router that are _not_ defined with server functions. We might want to include special endpoints that respond dynamically or that return non-HTML data types.
This example adds three new routes to our app:
dioxus::serve(|| async move {
use dioxus::server::axum::routing::{get, post};
let router \= dioxus::server::router(app)
.route("/submit", post(|| async { "Form submitted!" }))
.route("/about", get(|| async { "About us" }))
.route("/contact", get(|| async { "Contact us" }));
Ok(router)
});
dioxus::serve(|| async move {
use dioxus::server::axum::routing::{get, post};
let router \= dioxus::server::router(app)
.route("/submit", post(|| async { "Form submitted!" })) .route("/about", get(|| async { "About us" })) .route("/contact", get(|| async { "Contact us" }));
Ok(router)
});
Note that the server-side-rendering handler is registered as a _fallback_ handler. Any routes we manually register will take priority over the Dioxus app. Since these handlers are axum handlers, they can take the typical modifiers, like `.with_state()`, `.layer()`, etc.
let router \= dioxus::server::router(app)
.route( "/submit",
post( |state: State, ping: Extension, cookie: TypedHeader| async {
// ... endpoint logic
}, ), ) .with\_state(FormSubmitter::new())
.layer(Extension(Broadcast::new()));
let router \= dioxus::server::router(app)
.route( "/submit",
post( |state: State, ping: Extension, cookie: TypedHeader| async {
// ... endpoint logic
}, ), ) .with\_state(FormSubmitter::new())
.layer(Extension(Broadcast::new()));
The [Axum documentation](https://docs.rs/axum/latest/axum/index.html)
has more information on defining routes and handlers outside of server functions.
Axum allows you to to attach middleware to many parts of your router:
* To entire routers with [Router::layer](https://docs.rs/axum/latest/axum/struct.Router.html#method.layer)
and [Router::route\_layer](https://docs.rs/axum/latest/axum/struct.Router.html#method.route_layer)
.
* To method routers with [MethodRouter::layer](https://docs.rs/axum/latest/axum/routing/method_routing/struct.MethodRouter.html#method.layer)
and [MethodRouter::route\_layer](https://docs.rs/axum/latest/axum/routing/method_routing/struct.MethodRouter.html#method.route_layer)
.
* To individual handlers with [Handler::layer](https://docs.rs/axum/latest/axum/handler/trait.Handler.html#method.layer)
.
As you build out your app, you might want to expose state to your endpoints and to your requests. Axum provides two ways of adding state to endpoints: `Extension` and `State`. Extensions enable you to attach extra data to requests as they are handled by your router.
You can use extensions _either_ as a form of global state _or_ as a way of attaching state to requests. To share a given piece of data with all endpoints, you can attach the extension as a layer to the router in `dioxus::serve`:
dioxus::serve(|| async move {
use dioxus::server::axum::Extension;
use tokio::sync::broadcast;
let router \= dioxus::server::router(app)
.layer(Extension(broadcast::channel::(16).0));
Ok(router)
});
dioxus::serve(|| async move {
use dioxus::server::axum::Extension;
use tokio::sync::broadcast;
let router \= dioxus::server::router(app)
.layer(Extension(broadcast::channel::(16).0));
Ok(router)
});
Now, in our handlers, we can extract the extension from the request:
#\[post("/api/broadcast", ext: Extension>)\]
async fn broadcast\_message() -> Result<()> {
ext.send("New broadcast message".to\_string())?;
Ok(())
}
#\[post("/api/broadcast", ext: Extension>)\]
async fn broadcast\_message() -> Result<()> {
ext.send("New broadcast message".to\_string())?;
Ok(())
}
If we want to attach state to a single request - as in the case with a session middleware - we can attach a new middleware to the router that dynamically inserts a new extension into the request.
use axum::{extract::Request, middleware::Next, middleware};
let router \= dioxus::server::router(app)
.layer(middleware::from\_fn(|req: Request, next: Next| async move {
// Attach some extra state to the request
req.extensions\_mut().insert(Session::new());
// And then return the response with \`next.run()
Ok::<\_, Infallible\>(next.run(req).await)
}))
use axum::{extract::Request, middleware::Next, middleware};
let router \= dioxus::server::router(app)
.layer(middleware::from\_fn(|req: Request, next: Next| async move {
// Attach some extra state to the request
req.extensions\_mut().insert(Session::new());
// And then return the response with \`next.run()
Ok::<\_, Infallible\>(next.run(req).await)
}))
As a simpler alternative to axum extensions and `State`, you can also use the built-in `Lazy` type to access server resources without needing to set up a dedicated `dioxus::serve` entrypoint. The `Lazy` type is very similar to the standard library's `LazyLock` type, making it possible to initialize asynchronous data like database connections.
Simply create a new `Lazy` instance as a `static` variable:
static DATABASE: Lazy \= Lazy::new(|| async move {
dioxus::Ok(
SqlitePoolOptions::new()
.max\_connections(5)
.connect\_with("sqlite::memory:".parse().unwrap())
.await?,
)
});
static DATABASE: Lazy \= Lazy::new(|| async move {
dioxus::Ok(
SqlitePoolOptions::new()
.max\_connections(5)
.connect\_with("sqlite::memory:".parse().unwrap())
.await?,
)
});
Then when you access the `DATABASE` object in your code, Dioxus will ensure it's properly initialized, blocking the current thread until the initializer finishes. This lets you use asynchronous resources _synchronously_ which makes them extremely ergonomic.
/// When using the \`Lazy\` type, it implements \`Deref\`, so you can use it like a normal reference.
#\[get("/api/users")\]
async fn get\_users() -> Result> {
let users \= DATABASE
.fetch\_all(sqlx::query("SELECT name FROM users"))
.await?
.iter() .map(|row| row.get::("name"))
.collect::>();
Ok(users)
}
/// When using the \`Lazy\` type, it implements \`Deref\`, so you can use it like a normal reference.
#\[get("/api/users")\]
async fn get\_users() -> Result> {
let users \= DATABASE
.fetch\_all(sqlx::query("SELECT name FROM users"))
.await?
.iter() .map(|row| row.get::("name"))
.collect::>();
Ok(users)
}
Typically, Rust discourages the use of global variables for managing state, but for apps like web-servers, it's generally okay to have a single shared object for the entire app.
Note that you can also use the built-in standard `LazyLock` type for simple synchronous data:
static MESSAGES: LazyLock>> \= LazyLock::new(|| Mutex::new(Vec::new()));
#\[post("/api/messages")\]
async fn add\_message() -> Result<()> {
MESSAGES.lock().await.push("New message".to\_string());
Ok(())
}
static MESSAGES: LazyLock>> \= LazyLock::new(|| Mutex::new(Vec::new()));
#\[post("/api/messages")\]
async fn add\_message() -> Result<()> {
MESSAGES.lock().await.push("New message".to\_string());
Ok(())
}
[PREVIOUSCustom Error Pages](https://dioxuslabs.com/learn/0.7/essentials/fullstack/errors)
[NEXTMiddleware](https://dioxuslabs.com/learn/0.7/essentials/fullstack/middleware)
On this page
------------
* [Registering Server Functions](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum/#registering-server-functions)
* [Adding New Routes](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum/#adding-new-routes)
* [Adding Layers](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum/#adding-layers)
* [Adding State with Extensions](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum/#adding-state-with-extensions)
* [Using Lazy as Global State](https://dioxuslabs.com/learn/0.7/essentials/fullstack/axum/#using-lazyt-as-global-state)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Streams and SSE](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streams)
Dioxus Fullstack provides an easy way to send and receive streaming data from a server. This can be useful to implement functionality like streaming LLM responses, file downloads, and server-sent-events (SSE).
Unlike websockets which allow two-way communication, streams are unidirectional. In browsers, it's usually impossible to have a streaming input _and_ a streaming output, so you should stick to using streams for things like text/byte responses or file sending.
Dioxus Fullstack provides the `TextStream` type to easily send chunks of text between the client and the server. We can use this type as the input or output of a server function:
// The output is a \`TextStream\`
#\[get("/api/test\_stream?start")\]
async fn text\_stream(start: Option) -> Result {
let mut count \= start.unwrap\_or(0);
// We can create a new text stream with \`spawn\`
Ok(TextStream::spawn(move |tx| async move {
// Send a message with \`unbounded\_send\`
while tx.unbounded\_send(format!("Hello, world! {}", count)).is\_ok() {
count += 1;
// and then wait a bit
tokio::time::sleep(tokio::time::Duration::from\_millis(500)).await;
} }))
}
// The output is a \`TextStream\`
#\[get("/api/test\_stream?start")\]
async fn text\_stream(start: Option) -> Result {
let mut count \= start.unwrap\_or(0);
// We can create a new text stream with \`spawn\`
Ok(TextStream::spawn(move |tx| async move {
// Send a message with \`unbounded\_send\`
while tx.unbounded\_send(format!("Hello, world! {}", count)).is\_ok() {
count += 1;
// and then wait a bit
tokio::time::sleep(tokio::time::Duration::from\_millis(500)).await;
} }))
}
You can create a new stream with `TextStream::spawn` which gives you an `UnboundedSender` object, or from `TextStream::new()` which takes an existing type that implements the `Stream` trait:
// the \`rx\` here implements \`Stream\` which can be used in \`new()\`
let (tx, rx) \= futures::channel::mpsc::unbounded();
tokio::spawn(async move {
let mut count \= start.unwrap\_or(0);
loop {
let message \= format!("Hello, world! {}", count);
if tx.unbounded\_send(message).is\_err() { break;
}
count += 1;
tokio::time::sleep(tokio::time::Duration::from\_millis(500)).await;
}
});
Ok(Streaming::new(rx))
// the \`rx\` here implements \`Stream\` which can be used in \`new()\`
let (tx, rx) \= futures::channel::mpsc::unbounded();
tokio::spawn(async move {
let mut count \= start.unwrap\_or(0);
loop {
let message \= format!("Hello, world! {}", count);
if tx.unbounded\_send(message).is\_err() { break;
}
count += 1;
tokio::time::sleep(tokio::time::Duration::from\_millis(500)).await;
}
});
Ok(Streaming::new(rx))
The `TextStream` type is a superset of the `ByteStream` type. To send raw bytes between the client and the server, simply use `ByteStream` in the same way as `TextStream`, but with the `Bytes` type as input:
#\[post("/api/upload\_as\_bytestream")\]
async fn upload\_as\_bytestream(mut stream: ByteStream) -> Result<()> {
while let Some(chunk) \= stream.next().await {
// ... handle chunk
}
Ok(())
}
#\[post("/api/upload\_as\_bytestream")\]
async fn upload\_as\_bytestream(mut stream: ByteStream) -> Result<()> {
while let Some(chunk) \= stream.next().await {
// ... handle chunk
}
Ok(())
}
Note that in this example, we are _consuming_ the byte stream using `.next()`. Streams in Dioxus implement the standard [`Stream`](https://docs.rs/futures/latest/futures/prelude/trait.Stream.html)
trait, which has a number of [useful extensions](https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html)
.
Both the `TextStream` and `ByteStream` types are implemented as specific variations of the generic `Streaming` type. Under the hood, both stream types are simply streams of `Vec`. The `ByteStream` type wraps the incoming bytes in the `Bytes` type while `TextStream` ensures they're valid utf-8 text.
You can use any encoding provided it implements the `Encoding` trait.
pub trait Encoding {
fn content\_type() -> &'static str;
fn stream\_content\_type() -> &'static str;
fn to\_bytes(data: impl Serialize) -> Option;
fn from\_bytes(bytes: Bytes) -> Option;
}
pub trait Encoding {
fn content\_type() -> &'static str;
fn stream\_content\_type() -> &'static str;
fn to\_bytes(data: impl Serialize) -> Option;
fn from\_bytes(bytes: Bytes) -> Option;
}
Dioxus provides a number of built-in encodings:
* JsonEncoding: String-encoded JSON text
* CborEncoding: Binary-encoded data in the [CBOR](https://cbor.io/)
format
* PostcardEncoding: A binary encoding built on [Postcard](https://docs.rs/postcard/latest/postcard/)
meant for use in no\_std apps
* MsgPackEncoding: A compact binary encoding in a ["JSON but small" format](https://msgpack.org/index.html)
As each element in the stream arrives, it will be appropriately chunked and then deserialized using the encoding's `from_bytes` and `to_bytes` implementations.
This means we can stream arbitrary data - even custom structures!
#\[derive(Serialize, Deserialize, Debug)\]
struct Dog {
name: String,
age: u8,
}
/// A custom \`Streaming\` endpoint that streams JSON-encoded \`Dog\` structs to the client.
///
/// Dioxus provides the \`JsonEncoding\` type which can be used to encode and decode JSON data.
#\[get("/api/json\_stream")\]
async fn json\_stream() -> Result> {
Ok(Streaming::spawn(|tx| async move {
for count in 0..10 {
let dog \= Dog {
name: format!("Dog {}", count),
age: (count % 10) as u8,
};
if tx.unbounded\_send(dog).is\_err() { break;
}
tokio::time::sleep(tokio::time::Duration::from\_millis(500)).await;
} }))
}
#\[derive(Serialize, Deserialize, Debug)\]
struct Dog {
name: String,
age: u8,
}
/// A custom \`Streaming\` endpoint that streams JSON-encoded \`Dog\` structs to the client.
///
/// Dioxus provides the \`JsonEncoding\` type which can be used to encode and decode JSON data.
#\[get("/api/json\_stream")\]
async fn json\_stream() -> Result> {
Ok(Streaming::spawn(|tx| async move {
for count in 0..10 {
let dog \= Dog {
name: format!("Dog {}", count),
age: (count % 10) as u8,
};
if tx.unbounded\_send(dog).is\_err() { break;
}
tokio::time::sleep(tokio::time::Duration::from\_millis(500)).await;
} }))
}
The final stream type, `FileStream`, is a special stream type _not_ built on `Streaming`. File streams use platform-native optimizations to efficiently stream files without buffering the entire file into memory.
We can create the `FileStream` object in a variety of ways. For example, we can use `from_path` to efficiently stream arbitrary files from the server's file system:
/// This endpoint uses \`file!()\` to return the current file's \`PathBuf\`
#\[get("/api/download\_as\_filestream")\]
async fn download\_as\_filestream() -> Result {
Ok(FileStream::from\_path(file!()).await?)
}
/// This endpoint uses \`file!()\` to return the current file's \`PathBuf\`
#\[get("/api/download\_as\_filestream")\]
async fn download\_as\_filestream() -> Result {
Ok(FileStream::from\_path(file!()).await?)
}
The `FileStream` type can be created from the `FileData` type from dioxus-html. This makes it easy to add streaming file uploads to your app from the HTML `` and `` elements:
// Our client component calls the endpoint with \`file.into()\`
fn app() -> Element {
rsx! { h3 { "Upload as FileUpload" }
div { ondragover: move |evt| evt.prevent\_default(), ondrop: move |evt| async move {
evt.prevent\_default(); for file in files { \_ \= upload\_file\_as\_filestream(file.into()).await;
} }, "Drop files here"
} }
}
// Our server endpoint accepts \`FileStream\`
#\[post("/api/upload\_as\_file\_stream")\]
async fn upload\_file\_as\_filestream(mut upload: FileStream) -> Result<()> {
// ...
}
// Our client component calls the endpoint with \`file.into()\`
fn app() -> Element {
rsx! { h3 { "Upload as FileUpload" } div { ondragover: move |evt| evt.prevent\_default(), ondrop: move |evt| async move {
evt.prevent\_default(); for file in files { \_ \= upload\_file\_as\_filestream(file.into()).await;
} }, "Drop files here"
} }
}
// Our server endpoint accepts \`FileStream\`
#\[post("/api/upload\_as\_file\_stream")\]
async fn upload\_file\_as\_filestream(mut upload: FileStream) -> Result<()> {
// ...
}
The `FileStream` type also sets extra headers like `Content-Disposition` and `X-Content-Size` which give the server endpoint more information to efficiently handle the upload.
[PREVIOUSWebsockets](https://dioxuslabs.com/learn/0.7/essentials/fullstack/websockets)
[NEXTForms and Multipart](https://dioxuslabs.com/learn/0.7/essentials/fullstack/forms)
On this page
------------
* [Streaming Text](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streams/#streaming-text)
* [Streaming Bytes](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streams/#streaming-bytes)
* [The Generic Streaming type](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streams/#the-generic-streamingt-e-type)
* [File Streams](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streams/#file-streams)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Routing](https://dioxuslabs.com/learn/0.7/essentials/router/)
[Defining Routes](https://dioxuslabs.com/learn/0.7/essentials/router/routes)
When creating a `Routable` enum, we can define routes for our application using the `route("path")` attribute.
Each route is made up of segments. Most segments are separated by `/` characters in the path.
There are five fundamental types of segments:
1. [Static segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#static-segments)
are fixed strings that must be present in the path.
2. [Dynamic segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#dynamic-segments)
are types that can be parsed from a segment.
3. [Catch-all segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#catch-all-segments)
are types that can be parsed from multiple segments.
4. [Query segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#query-segments)
are types that can be parsed from the query string.
5. [Hash fragments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#hash-segments)
are types that can be parsed from the hash fragment.
Routes are matched:
* First, from most specific to least specific (Static then Dynamic then Catch All) (Query and hash are always matched)
* Then, if multiple routes match the same path, the order in which they are defined in the enum is followed.
Fixed routes match a specific path. For example, the route `#[route("/about")]` will match the path `/about`.
src/static\_segments.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// Routes always start with a slash
#\[route("/")\]
Home {},
// You can have multiple segments in a route
#\[route("/hello/world")\]
HelloWorld {},
}
#\[component\]
fn Home() -> Element {
todo!()
}
#\[component\]
fn HelloWorld() -> Element {
todo!()
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// Routes always start with a slash
#\[route("/")\]
Home {},
// You can have multiple segments in a route
#\[route("/hello/world")\]
HelloWorld {},
}
#\[component\]
fn Home() -> Element {
todo!()
}
#\[component\]
fn HelloWorld() -> Element {
todo!()
}
Dynamic segments are in the form of `:name` where `name` is the name of the field in the route variant. If the segment is parsed successfully then the route matches, otherwise the matching continues.
The segment can be of any type that implements `FromStr`.
src/dynamic\_segments.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with : are dynamic segments
#\[route("/post/:name")\]
BlogPost {
// You must include dynamic segments in child variants
name: String,
},
#\[route("/document/:id")\]
Document {
// You can use any type that implements FromStr
// If the segment can't be parsed, the route will not match
id: usize,
},
}
// Components must contain the same dynamic segments as their corresponding variant
#\[component\]
fn BlogPost(name: String) -> Element {
todo!()
}
#\[component\]
fn Document(id: usize) -> Element {
todo!()
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with : are dynamic segments
#\[route("/post/:name")\]
BlogPost {
// You must include dynamic segments in child variants
name: String,
},
#\[route("/document/:id")\]
Document {
// You can use any type that implements FromStr
// If the segment can't be parsed, the route will not match
id: usize,
},
}
// Components must contain the same dynamic segments as their corresponding variant
#\[component\]
fn BlogPost(name: String) -> Element {
todo!()
}
#\[component\]
fn Document(id: usize) -> Element {
todo!()
}
Catch All segments are in the form of `:..name` where `name` is the name of the field in the route variant. If the segments are parsed successfully then the route matches, otherwise the matching continues.
The segment can be of any type that implements `FromSegments`. ( `Vec` implements this by default)
Catch All segments must be the _last route segment_ in the path (query segments are not counted) and cannot be included in nests.
src/catch\_all\_segments.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with :.. are catch all segments
#\[route("/blog/:..segments")\]
BlogPost {
// You must include catch all segment in child variants
segments: Vec,
},
}
// Components must contain the same catch all segments as their corresponding variant
#\[component\]
fn BlogPost(segments: Vec) -> Element {
todo!()
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with :.. are catch all segments
#\[route("/blog/:..segments")\]
BlogPost {
// You must include catch all segment in child variants
segments: Vec,
},
}
// Components must contain the same catch all segments as their corresponding variant
#\[component\]
fn BlogPost(segments: Vec) -> Element {
todo!()
}
Query segments are in the form of `?:name&:othername` where `name` and `othername` are the names of fields in the route variant.
Unlike [Dynamic Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#dynamic-segments)
and [Catch All Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#catch-all-segments)
, parsing a Query segment must not fail.
The segment can be of any type that implements `FromQueryArgument`.
Query segments must be the _after all route segments_ and cannot be included in nests.
src/query\_segments.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with ?: are query segments
#\[route("/blog?:name&:surname")\]
BlogPost {
// You must include query segments in child variants
name: String,
surname: String,
},
}
#\[component\]
fn BlogPost(name: String, surname: String) -> Element {
rsx! { div { "This is your blogpost with a query segment:" }
div { "Name: {name}" }
div { "Surname: {surname}" }
}
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with ?: are query segments
#\[route("/blog?:name&:surname")\]
BlogPost {
// You must include query segments in child variants
name: String,
surname: String,
},
}
#\[component\]
fn BlogPost(name: String, surname: String) -> Element {
rsx! { div { "This is your blogpost with a query segment:" } div { "Name: {name}" } div { "Surname: {surname}" } }
}
Hash segments are in the form of `#:field` where `field` is a field in the route variant.
Just like [Query Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes#query-segments)
, parsing a Hash segment must not fail.
The segment can be of any type that implements `FromHashFragment`.
Hash fragments must be the _after all route segments and any query segments_ and cannot be included in nests.
src/hash\_fragments.rs
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with #: are hash segments
#\[route("/blog#:name")\]
BlogPost {
// You must include hash segments in child variants
name: String,
},
}
#\[component\]
fn BlogPost(name: String) -> Element {
rsx! { div { "This is your blogpost with a query segment:" }
div { "Name: {name}" }
}
}
#\[derive(Routable, Clone)\]
#\[rustfmt::skip\]
enum Route {
// segments that start with #: are hash segments
#\[route("/blog#:name")\]
BlogPost {
// You must include hash segments in child variants
name: String,
},
}
#\[component\]
fn BlogPost(name: String) -> Element {
rsx! { div { "This is your blogpost with a query segment:" } div { "Name: {name}" } }
}
When developing bigger applications we often want to nest routes within each other. As an example, we might want to organize a settings menu using this pattern:
â Settings
â General Settings (displayed when opening the settings) â Change Password â Privacy Settings
â Settings
â General Settings (displayed when opening the settings) â Change Password â Privacy Settings
We might want to map this structure to these paths and components:
/settings -> Settings { GeneralSettings }
/settings/password -> Settings { PWSettings }
/settings/privacy -> Settings { PrivacySettings }
/settings -> Settings { GeneralSettings }
/settings/password -> Settings { PWSettings }
/settings/privacy -> Settings { PrivacySettings }
Nested routes allow us to do this without repeating /settings in every route.
To nest routes, we use the `#[nest("path")]` and `#[end_nest]` attributes.
The path in nest must not:
1. Contain a [Catch All Segment](https://dioxuslabs.com/learn/0.7/essentials/router/routes#catch-all-segments)
2. Contain a [Query Segment](https://dioxuslabs.com/learn/0.7/essentials/router/routes#query-segments)
If you define a dynamic segment in a nest, it will be available to all child routes and layouts.
To finish a nest, we use the `#[end_nest]` attribute or the end of the enum.
src/nest.rs
#\[derive(Routable, Clone)\]
// Skipping formatting allows you to indent nests
#\[rustfmt::skip\]
enum Route {
// Start the /blog nest
#\[nest("/blog")\]
// You can nest as many times as you want
#\[nest("/:id")\]
#\[route("/post")\]
PostId {
// You must include parent dynamic segments in child variants
id: usize,
}, // End nests manually with #\[end\_nest\]
#\[end\_nest\] #\[route("/:id")\]
// The absolute route of BlogPost is /blog/:name
BlogPost {
id: usize,
}, // Or nests are ended automatically at the end of the enum
}
#\[component\]
fn BlogPost(id: usize) -> Element {
todo!()
}
#\[component\]
fn PostId(id: usize) -> Element {
todo!()
}
#\[derive(Routable, Clone)\]
// Skipping formatting allows you to indent nests
#\[rustfmt::skip\]
enum Route {
// Start the /blog nest
#\[nest("/blog")\]
// You can nest as many times as you want
#\[nest("/:id")\]
#\[route("/post")\]
PostId {
// You must include parent dynamic segments in child variants
id: usize,
}, // End nests manually with #\[end\_nest\]
#\[end\_nest\] #\[route("/:id")\]
// The absolute route of BlogPost is /blog/:name
BlogPost {
id: usize,
}, // Or nests are ended automatically at the end of the enum
}
#\[component\]
fn BlogPost(id: usize) -> Element {
todo!()
}
#\[component\]
fn PostId(id: usize) -> Element {
todo!()
}
[PREVIOUSRouting](https://dioxuslabs.com/learn/0.7/essentials/router/)
[NEXTNavigation](https://dioxuslabs.com/learn/0.7/essentials/router/navigation)
On this page
------------
* [Route Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#route-segments)
* [Static segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#static-segments)
* [Dynamic Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#dynamic-segments)
* [Catch All Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#catch-all-segments)
* [Query Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#query-segments)
* [Hash Segments](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#hash-segments)
* [Nested Routes](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#nested-routes)
* [Nesting](https://dioxuslabs.com/learn/0.7/essentials/router/routes/#nesting)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/beyond/)
This guide expands upon the basic of dioxus to dive into the internals of the framework. It covers:
* [Contributing to Dioxus](https://dioxuslabs.com/learn/0.7/beyond/contributing)
* [The Project Structure of Dioxus](https://dioxuslabs.com/learn/0.7/beyond/project_structure)
In addition to these chapters, it may also be helpful to read articles in the [Dioxus Blog](https://dioxuslabs.com/blog)
that discuss interesting optimziations like [template diffing](https://dioxuslabs.com/blog/templates-diffing)
dioxus uses internally
[PREVIOUSProps](https://dioxuslabs.com/learn/0.7/migration/to_05/props)
[NEXTContributing](https://dioxuslabs.com/learn/0.7/beyond/contributing)
On this page
------------
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Advanced Topics](https://dioxuslabs.com/learn/0.7/essentials/advanced/)
[Breaking Out](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out)
Dioxus makes it easy to build reactive user interfaces. However, there are some cases where you may need to break out of the reactive paradigm to interact with the DOM directly.
Dioxus exposes a limited number of [web apis](https://developer.mozilla.org/en-US/docs/Web/API)
with a nicer interface. If you need access to more APIs, you can use the `eval` function to run JavaScript in the browser.
For example, you can use the eval function to read the domain of the current page:
src/breaking\_out.rs
pub fn Eval() -> Element {
let mut domain \= use\_signal(String::new);
rsx! { button { // When you click the button, some javascript will run in the browser
// to read the domain and set the signal
onclick: move |\_| async move {
domain.set(document::eval("return document.domain").await.unwrap().to\_string());
}, "Read Domain"
} "Current domain: {domain}"
}
}
pub fn Eval() -> Element {
let mut domain \= use\_signal(String::new);
rsx! { button { // When you click the button, some javascript will run in the browser
// to read the domain and set the signal
onclick: move |\_| async move {
domain.set(document::eval("return document.domain").await.unwrap().to\_string());
}, "Read Domain"
} "Current domain: {domain}"
}
}
Read DomainCurrent domain:
If you are only targeting web, you can also use the [`web-sys`](https://crates.io/crates/web-sys)
crate for typed access to the web APIs. Here is what reading the domain looks like with web-sys:
src/breaking\_out.rs
use ::web\_sys::window;
use wasm\_bindgen::JsCast;
pub fn WebSys() -> Element {
let mut domain \= use\_signal(String::new);
rsx! { button { // When you click the button, we use web-sys to read the domain and a signal
onclick: move |\_| {
domain .set( window() .unwrap() .document() .unwrap() .dyn\_into::<::web\_sys::HtmlDocument>() .unwrap() .domain(), ); }, "Read Domain"
} "Current domain: {domain}"
}
}
use ::web\_sys::window;
use wasm\_bindgen::JsCast;
pub fn WebSys() -> Element {
let mut domain \= use\_signal(String::new);
rsx! { button { // When you click the button, we use web-sys to read the domain and a signal
onclick: move |\_| {
domain .set( window() .unwrap() .document() .unwrap() .dyn\_into::<::web\_sys::HtmlDocument>() .unwrap() .domain(), ); }, "Read Domain"
} "Current domain: {domain}"
}
}
Read DomainCurrent domain:
If you do need to interact with the DOM directly, you should do so in a `use_effect` hook. This hook will run after the component is rendered and all of the Dioxus UI has been rendered. You can read or modify the DOM in this hook.
For example, you can use the `use_effect` hook to write to a canvas element after it is created:
src/breaking\_out.rs
pub fn Canvas() -> Element {
let mut count \= use\_signal(|| 0);
use\_effect(move || {
// Effects are reactive like memos, and resources. If you read a value inside the effect, the effect will rerun when that value changes
let count \= count.read();
// You can use the count value to update the DOM manually
document::eval(&format!(
r#"var c = document.getElementById("dioxus-canvas");
var ctx = c.getContext("2d");
ctx.clearRect(0, 0, c.width, c.height);
ctx.font = "30px Arial";
ctx.fillText("{count}", 10, 50);"#
)); });
rsx! { button { // When you click the button, count will be incremented and the effect will rerun
onclick: move |\_| count += 1,
"Increment"
} canvas { id: "dioxus-canvas" }
}
}
pub fn Canvas() -> Element {
let mut count \= use\_signal(|| 0);
use\_effect(move || {
// Effects are reactive like memos, and resources. If you read a value inside the effect, the effect will rerun when that value changes
let count \= count.read();
// You can use the count value to update the DOM manually
document::eval(&format!(
r#"var c = document.getElementById("dioxus-canvas");
var ctx = c.getContext("2d");
ctx.clearRect(0, 0, c.width, c.height);
ctx.font = "30px Arial";
ctx.fillText("{count}", 10, 50);"#
)); });
rsx! { button { // When you click the button, count will be incremented and the effect will rerun
onclick: move |\_| count += 1,
"Increment"
} canvas { id: "dioxus-canvas" } }
}
Increment
If you need a handle to an element that is rendered by dioxus, you can use the `onmounted` event. This event will fire after the element is first mounted to the DOM. It returns a live reference to the element with some methods to interact with it.
You can use the onmounted event to do things like focus or scroll to an element after it is rendered:
src/breaking\_out.rs
pub fn OnMounted() -> Element {
let mut input\_element \= use\_signal(|| None);
rsx! { div { height: "100px",
button { class: "focus:outline-2 focus:outline-blue-600 focus:outline-dashed",
// The onmounted event will run the first time the button element is mounted
onmounted: move |element| input\_element.set(Some(element.data())),
"First button"
}
button { // When you click the button, if the button element has been mounted, we focus to that element
onclick: move |\_| async move {
if let Some(header) \= input\_element() {
let \_ \= header.set\_focus(true).await;
} }, "Focus first button"
} } }
}
pub fn OnMounted() -> Element {
let mut input\_element \= use\_signal(|| None);
rsx! { div { height: "100px",
button { class: "focus:outline-2 focus:outline-blue-600 focus:outline-dashed",
// The onmounted event will run the first time the button element is mounted
onmounted: move |element| input\_element.set(Some(element.data())),
"First button"
}
button { // When you click the button, if the button element has been mounted, we focus to that element
onclick: move |\_| async move {
if let Some(header) \= input\_element() {
let \_ \= header.set\_focus(true).await;
} }, "Focus first button"
} } }
}
First buttonFocus first button
Dioxus provides platform agnostic wrappers over each event type. These wrappers are often nicer to interact with than the raw event types, but they can be more limited. If you are targeting web, you can downcast the event with the `as_web_event` method to get the underlying web-sys event:
src/breaking\_out.rs
pub fn Downcast() -> Element {
let mut event\_text \= use\_signal(|| 0);
rsx! { div { onmousemove: move |event| {
#\[cfg(feature \= "web")\]
{ use dioxus::web::WebEventExt;
event\_text.set(event.as\_web\_event().movement\_x()); } }, "movement\_x was {event\_text}"
} }
}
pub fn Downcast() -> Element {
let mut event\_text \= use\_signal(|| 0);
rsx! { div { onmousemove: move |event| {
#\[cfg(feature \= "web")\]
{ use dioxus::web::WebEventExt;
event\_text.set(event.as\_web\_event().movement\_x()); } }, "movement\_x was {event\_text}"
} }
}
movement\_x was 0
[PREVIOUSComponent Lifecycle](https://dioxuslabs.com/learn/0.7/essentials/advanced/lifecycle)
[NEXTOverview](https://dioxuslabs.com/learn/0.7/guides/)
On this page
------------
* [Interacting with JavaScript with eval and web-sys](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out/#interacting-with-javascript-with-eval-and-web-sys)
* [Synchronizing DOM updates with use\_effect](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out/#synchronizing-dom-updates-with-use-effect)
* [Getting access to elements with onmounted](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out/#getting-access-to-elements-with-onmounted)
* [Down casting web sys events](https://dioxuslabs.com/learn/0.7/essentials/advanced/breaking_out/#down-casting-web-sys-events)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[HTML Streaming](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming)
For some sites, it is extremely important to optimize "time-to-first-byte". Users want to see results as soon as possible, even if not _all_ results are ready immediately.
Dioxus supports this usecase with a technology called _"HTML Streaming"_. HTML streaming allows you to quickly send an initial skeleton of the page to the user and then fill in various components as their data loads.
The default rendering mode in dioxus fullstack waits for all [suspense boundaries](https://dioxuslabs.com/learn/0.7/essentials/basics/suspense#suspense-with-fullstack)
to resolve before sending the entire page as HTML to the client. If you have a page with multiple chunks of async data, the server will wait for all of them to complete before rendering the page.
When streaming is enabled, the server can send chunks of HTML to the client as soon as each suspense boundary resolves. You can start interacting with a page as soon as the first part of the HTML is sent, instead of waiting for the entire page to be ready. This can lead to a much faster initial load time.
Bellow is the same [hackernews example](https://github.com/DioxusLabs/dioxus/tree/main/examples/01-app-demos/hackernews)
rendered with and without streaming enabled. While both pages take the same amount of time to load all the data, the page with streaming enabled on the left shows you the data as soon as it becomes available.
đ
When streaming is enabled, all of the contents of the page are still rendered into the html document, so search engines can still crawl and index the full content of the page. However, the content will not be visible to users unless they have JavaScript enabled. If you want to support users without JavaScript, you will need to disable streaming and use the default rendering mode.
HTML streaming is best suited for apps like e-commerce sites where much of the data is quick to render (the product image, description, etc) but some data takes much longer to resolve. In these cases, you don't want to make the user wait too long for the page to load, so you send down what you have as soon as possible.
Streaming adds some slight overhead and complexity to your app, so it's disabled by default.
You can enable streaming in the ServeConfig builder with the `enable_out_of_order_streaming` method. If you are launching your application through the `dioxus::LaunchBuilder`, you can use the `with_cfg` method to pass in a configuration that enables streaming:
src/streaming.rs
pub fn main() {
dioxus::LaunchBuilder::new()
.with\_cfg(server\_only! { dioxus::server::ServeConfig::builder().enable\_out\_of\_order\_streaming()
}) .launch(app);
}
pub fn main() {
dioxus::LaunchBuilder::new()
.with\_cfg(server\_only! { dioxus::server::ServeConfig::builder().enable\_out\_of\_order\_streaming()
}) .launch(app);
}
or if you are using a custom axum server, you can pass the config into `serve_dioxus_application` directly:
src/streaming.rs
#\[cfg(feature \= "server")\]
#\[tokio::main\]
async fn main() {
let addr \= dioxus::cli\_config::fullstack\_address\_or\_localhost();
let router \= axum::Router::new()
// Server side render the application, serve static assets, and register server functions
.serve\_dioxus\_application( dioxus::server::ServeConfig::builder().enable\_out\_of\_order\_streaming(),
app, ) .into\_make\_service(); let listener \= tokio::net::TcpListener::bind(addr).await.unwrap();
axum::serve(listener, router).await.unwrap();
}
#\[cfg(feature \= "server")\]
#\[tokio::main\]
async fn main() {
let addr \= dioxus::cli\_config::fullstack\_address\_or\_localhost();
let router \= axum::Router::new()
// Server side render the application, serve static assets, and register server functions
.serve\_dioxus\_application( dioxus::server::ServeConfig::builder().enable\_out\_of\_order\_streaming(),
app, ) .into\_make\_service(); let listener \= tokio::net::TcpListener::bind(addr).await.unwrap();
axum::serve(listener, router).await.unwrap();
}
Head elements can only be rendered in the initial HTML chunk that contains the `` tag. You should include all of your `document::Link`, `document::Meta`, and `document::Title` elements in the first part of your page if possible. If you have any head elements that are not included in the first chunk, they will be rendered by the client after hydration instead, which will not be visible to any search engines or users without JavaScript enabled.
The initial chunk of HTML is send after [commit\_initial\_chunk](https://docs.rs/dioxus-fullstack/0.7.0-alpha.1/dioxus_fullstack/prelude/fn.commit_initial_chunk.html)
is called for the first time. If you are using the router, this will happen automatically when all suspense boundaries above the router are resolved. If you are not using the router, you can call `commit_initial_chunk` manually after all of your blocking head elements have been rendered.
src/streaming.rs
/// An enum of all of the possible routes in the app.
#\[derive(Routable, Clone)\]
enum Route {
// The home page is at the / route
#\[route("/")\]
Home,
}
fn Home() -> Element {
let title \= use\_server\_future(get\_title)?;
let description \= use\_server\_future(get\_description)?;
rsx! { // This will be rendered on the server because it is inside the same (root)
// suspense boundary as the \`Router\` component.
document::Title { {title} }
SuspenseBoundary {
fallback: |\_| {
rsx! { "Loading..." }
}, AsyncHead {}
} }
}
fn AsyncHead() -> Element {
let description \= use\_server\_future(get\_description)?;
// The resource should always be resolved at this point because the \`?\` above bubbles
// up the async case if it is pending
let current\_description \= description.read\_unchecked(); let current\_description \= current\_description.as\_ref().unwrap();
rsx! { // This will be rendered on the client because it is in a
// suspense boundary below the \`Router\` component.
document::Meta { name: "description", content: "{current\_description}" }
}
}
/// An enum of all of the possible routes in the app.
#\[derive(Routable, Clone)\]
enum Route {
// The home page is at the / route
#\[route("/")\]
Home,
}
fn Home() -> Element {
let title \= use\_server\_future(get\_title)?;
let description \= use\_server\_future(get\_description)?;
rsx! { // This will be rendered on the server because it is inside the same (root)
// suspense boundary as the \`Router\` component.
document::Title { {title} }
SuspenseBoundary {
fallback: |\_| {
rsx! { "Loading..." } }, AsyncHead {}
} }
}
fn AsyncHead() -> Element {
let description \= use\_server\_future(get\_description)?;
// The resource should always be resolved at this point because the \`?\` above bubbles
// up the async case if it is pending
let current\_description \= description.read\_unchecked(); let current\_description \= current\_description.as\_ref().unwrap();
rsx! { // This will be rendered on the client because it is in a
// suspense boundary below the \`Router\` component.
document::Meta { name: "description", content: "{current\_description}" } }
}
When rendering an app with streaming enabled, Dioxus will wait for the app to commit its initial skeleton before sending a response to the user's request. This is done with the `commit_initial_chunk()` method.
Once the initial chunk is committed, you can no longer change the headers of the response nor change the HTTP status.
For example, you might have a server function that throws a 404 status code:
#\[get("/api/post/{id}")\]
async fn get\_post(id: u32) -> Result {
match id { 1 \=> Ok("first post".to\_string()),
\_ \=> HttpError::not\_found("Post not found")?,
}
}
#\[get("/api/post/{id}")\]
async fn get\_post(id: u32) -> Result {
match id { 1 \=> Ok("first post".to\_string()),
\_ \=> HttpError::not\_found("Post not found")?,
}
}
With streaming disabled, if this status code is bubbled to the root component as an error, the user will get a `404 NOT FOUND` status in the response.
#\[component\]
fn Post(id: ReadSignal) -> Element {
// If \`get\_post\` returns a 404, then the user will also get a 404
let post\_data \= use\_loader(move || get\_post(id()))?;
rsx! { h1 { "Post {id}" }
p { "{post\_data}" }
}
}
#\[component\]
fn Post(id: ReadSignal) -> Element {
// If \`get\_post\` returns a 404, then the user will also get a 404
let post\_data \= use\_loader(move || get\_post(id()))?;
rsx! { h1 { "Post {id}" } p { "{post\_data}" } }
}
However, when streaming is _enabled_, the status code from this server function will only be propagated to the user _before_ the call to `commit_initial_chunk()`.
Normally, you won't call `commit_initial_chunk()` yourself since the `Router` component calls it for you once the root suspense boundary is resolved.
This means that, when suspense is enabled, server functions won't set the HTTP status code if they are called from within a dedicated suspense boundary:
fn Home() -> Element {
rsx! { SuspenseBoundary {
fallback: |\_| rsx! { "loading..." },
// Errors here won't propagate to the response headers
Post { id: 123 }
} }
}
fn Home() -> Element {
rsx! { SuspenseBoundary {
fallback: |\_| rsx! { "loading..." },
// Errors here won't propagate to the response headers
Post { id: 123 }
} }
}
[PREVIOUSNative Clients](https://dioxuslabs.com/learn/0.7/essentials/fullstack/native)
[NEXTStatic Site Generation](https://dioxuslabs.com/learn/0.7/essentials/fullstack/static_site_generation)
On this page
------------
* [What is Streaming?](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming/#what-is-streaming)
* [SEO and No JS](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming/#seo-and-no-js)
* [Do You Need Streaming?](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming/#do-you-need-streaming)
* [Enabling Streaming](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming/#enabling-streaming)
* [Head elements with streaming](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming/#head-elements-with-streaming)
* [Response Headers with Streaming](https://dioxuslabs.com/learn/0.7/essentials/fullstack/streaming/#response-headers-with-streaming)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Routing](https://dioxuslabs.com/learn/0.7/essentials/router/)
[Navigation](https://dioxuslabs.com/learn/0.7/essentials/router/navigation)
When we split our app into pages, we need to provide our users with a way to navigate between them. On regular web pages, we'd use an anchor element for that, like this:
Link to an other page
Link to an other page
However, we cannot do that when using the router for three reasons:
1. Anchor tags make the browser load a new page from the server. This takes a lot of time, and it is much faster to let the router handle the navigation client-side.
2. Navigation using anchor tags only works when the app is running inside a browser. This means we cannot use them inside apps using Dioxus Desktop.
3. Anchor tags cannot check if the target page exists. This means we cannot prevent accidentally linking to non-existent pages.
To solve these problems, the router provides us with a [`Link`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html)
component we can use like this:
src/links.rs
#\[component\]
fn NavBar() -> Element {
rsx! { nav { Link { to: Route::Home {}, "Home" }
} Outlet:: {}
}
}
#\[component\]
fn NavBar() -> Element {
rsx! { nav { Link { to: Route::Home {}, "Home" } } Outlet:: {}
}
}
The `target` in the example above is similar to the `href` of a regular anchor element. However, it tells the router more about what kind of navigation it should perform. It accepts something that can be converted into a[`NavigationTarget`](https://docs.rs/dioxus-router/latest/dioxus_router/navigation/enum.NavigationTarget.html)
:
* The example uses a Internal route. This is the most common type of navigation. It tells the router to navigate to a page within our app by passing a variant of a \[`Routable`\] enum. This type of navigation can never fail if the link component is used inside a router component.
* \[`External`\] allows us to navigate to URLs outside of our app. This is useful for links to external websites. NavigationTarget::External accepts an URL to navigate to. This type of navigation can fail if the URL is invalid.
> The [`Link`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html)
> accepts several props that modify its behavior. See the API docs for more details.
Sometimes we want our application to navigate to another page without having the user click on a link. This is called programmatic navigation.
We can get a navigator with the [`navigator`](https://docs.rs/dioxus-router/latest/dioxus_router/prelude/struct.Navigator.html)
function which returns a [`Navigator`](https://docs.rs/dioxus-router/latest/dioxus_router/prelude/struct.Navigator.html)
.
We can use the [`Navigator`](https://docs.rs/dioxus-router/latest/dioxus_router/prelude/struct.Navigator.html)
to trigger four different kinds of navigation:
* `push` will navigate to the target. It works like a regular anchor tag.
* `replace` works like `push`, except that it replaces the current history entry instead of adding a new one. This means the prior page cannot be restored with the browser's back button.
* `Go back` works like the browser's back button.
* `Go forward` works like the browser's forward button.
src/navigator.rs
#\[component\]
fn Home() -> Element {
let nav \= navigator();
// push
nav.push(Route::PageNotFound { route: vec!\[\] });
// replace
nav.replace(Route::Home {});
// go back
nav.go\_back();
// go forward
nav.go\_forward();
rsx! { h1 { "Welcome to the Dioxus Blog!" } }
}
#\[component\]
fn Home() -> Element {
let nav \= navigator();
// push
nav.push(Route::PageNotFound { route: vec!\[\] });
// replace
nav.replace(Route::Home {});
// go back
nav.go\_back();
// go forward
nav.go\_forward();
rsx! { h1 { "Welcome to the Dioxus Blog!" } }
}
You might have noticed that, like [`Link`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html)
, the [`Navigator`](https://docs.rs/dioxus-router/latest/dioxus_router/prelude/struct.Navigator.html)
s `push` and`replace` functions take a [`NavigationTarget`](https://docs.rs/dioxus-router/latest/dioxus_router/navigation/enum.NavigationTarget.html)
. This means we can use either`Internal`, or `External` targets.
Unlike a [`Link`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html)
, the [`Navigator`](https://docs.rs/dioxus-router/latest/dioxus_router/prelude/struct.Navigator.html)
cannot rely on the browser (or webview) to handle navigation to external targets via a generated anchor element.
This means, that under certain conditions, navigation to external targets can fail.
\[ `HistoryProvider`\] s are used by the router to keep track of the navigation history and update any external state (e.g. the browser's URL).
The router provides two \[ `HistoryProvider`\] s, but you can also create your own. The two default implementations are:
* The \[`MemoryHistory`\] is a custom implementation that works in memory.
* The \[`LiveviewHistory`\] is a custom implementation that works with the liveview renderer.
* The \[`WebHistory`\] integrates with the browser's URL.
By default, the router uses the \[ `MemoryHistory`\] . It might be changed to use \[ `WebHistory`\] when the `web` feature is active, but that is not guaranteed.
You can override the default history:
src/history\_provider.rs
#\[component\]
fn App() -> Element {
rsx! { Router:: { config: || RouterConfig::default() }
}
}
#\[component\]
fn App() -> Element {
rsx! { Router:: { config: || RouterConfig::default() }
}
}
In some cases, we might want to run custom code when the current route changes. For this reason, the [`RouterConfig`](https://docs.rs/dioxus-router/latest/dioxus_router/prelude/struct.RouterConfig.html)
exposes an `on_update` field.
The `on_update` is called whenever the current routing information changes. It is called after the router updated its internal state, but before dependent components and hooks are updated.
If the callback returns a [`NavigationTarget`](https://docs.rs/dioxus-router/latest/dioxus_router/navigation/enum.NavigationTarget.html)
, the router will replace the current location with the specified target. It will not call the `on_update` again.
If at any point the router encounters a navigation failure, it will go to the appropriate state without calling the `on_update`. It doesn't matter if the invalid target initiated the navigation, was found as a redirect target, or was returned by the `on_update` itself.
src/routing\_update.rs
#\[derive(Routable, Clone, PartialEq)\]
enum Route {
#\[route("/")\]
Index {},
#\[route("/home")\]
Home {},
}
#\[component\]
fn Home() -> Element {
rsx! { p { "Home" }
}
}
#\[component\]
fn Index() -> Element {
rsx! { p { "Index" }
}
}
fn app() -> Element {
rsx! { Router:: {
config: || {
RouterConfig::default()
.on\_update(|state| {
(state.current() \== Route::Index {})
.then\_some(NavigationTarget::Internal(Route::Home {}))
}) }, } }
}
#\[derive(Routable, Clone, PartialEq)\]
enum Route {
#\[route("/")\]
Index {},
#\[route("/home")\]
Home {},
}
#\[component\]
fn Home() -> Element {
rsx! { p { "Home" } }
}
#\[component\]
fn Index() -> Element {
rsx! { p { "Index" } }
}
fn app() -> Element {
rsx! { Router:: {
config: || {
RouterConfig::default()
.on\_update(|state| {
(state.current() \== Route::Index {})
.then\_some(NavigationTarget::Internal(Route::Home {}))
}) }, } }
}
Some platforms, like web browsers, provide users with an easy way to navigate through an app's history. They have UI elements or integrate with the OS.
However, native platforms usually don't provide such amenities, which means that apps wanting users to have access to them, need to implement them. For this reason, the router comes with two components, which emulate a browser's back and forward buttons:
* [`GoBackButton`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.GoBackButton.html)
* [`GoForwardButton`](https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.GoForwardButton.html)
src/history\_buttons.rs
fn HistoryNavigation() -> Element {
rsx! { GoBackButton { "Back to the Past" }
GoForwardButton { "Back to the Future" }
}
}
fn HistoryNavigation() -> Element {
rsx! { GoBackButton { "Back to the Past" } GoForwardButton { "Back to the Future" } }
}
As you might know, browsers usually disable the back and forward buttons if there is no history to navigate to. The router's history buttons try to do that too, but depending on the \[ history provider \] that might not be possible.
Importantly, neither `WebHistory` supports that feature. This is due to limitations of the browser History API.
However, in both cases, the router will just ignore button presses, if there is no history to navigate to.
Also, when using `WebHistory`, the history buttons might navigate a user to a history entry outside your app.
[PREVIOUSDefining Routes](https://dioxuslabs.com/learn/0.7/essentials/router/routes)
[NEXTLayouts](https://dioxuslabs.com/learn/0.7/essentials/router/layouts)
On this page
------------
* [Programmatic Navigation](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#programmatic-navigation)
* [Using a Navigator](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#using-a-navigator)
* [External Navigation Targets](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#external-navigation-targets)
* [History Providers](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#history-providers)
* [Routing Update Callback](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#routing-update-callback)
* [How does the callback behave?](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#how-does-the-callback-behave)
* [Code Example](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#code-example)
* [History Buttons](https://dioxuslabs.com/learn/0.7/essentials/router/navigation/#history-buttons)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Tools](https://dioxuslabs.com/learn/0.7/guides/tools/)
[Translate HTML](https://dioxuslabs.com/learn/0.7/guides/tools/translate)
Dioxus uses a custom format called RSX to represent the HTML because it is more concise and looks more like Rust code. However, it can be a pain to convert existing HTML to RSX. That's why Dioxus comes with a tool called `dx translate` that can automatically convert HTML to RSX!
Dx translate can make converting large chunks of HTML to RSX much easier! Lets try translating some of the HTML from the Dioxus homepage:
dx translate --raw "
"
We get the following RSX you can easily copy and paste into your code:
div { class: "relative w-full mx-4 sm:mx-auto text-gray-600",
div { class: "text-\[3em\] md:text-\[5em\] font-semibold dark:text-white text-ghdarkmetal font-sans py-12 flex flex-col",
span { "Fullstack, crossplatform," }
span { "lightning fast, fully typed." }
} h3 { class: "text-\[2em\] dark:text-white font-extralight text-ghdarkmetal pt-4 max-w-screen-md mx-auto",
"Dioxus is a Rust library for building apps that run on desktop, web, mobile, and more."
} div { class: "pt-12 text-white text-\[1.2em\] font-sans font-bold flex flex-row justify-center space-x-4",
a { href: "/learn/0.7/getting\_started",
data\_dioxus\_id: "216",
dioxus\_prevent\_default: "onclick",
class: "bg-red-600 py-2 px-8 hover:-translate-y-2 transition-transform duration-300",
"Quickstart"
} a { dioxus\_prevent\_default: "onclick",
href: "/learn/0.7/reference",
data\_dioxus\_id: "214",
class: "bg-blue-500 py-2 px-8 hover:-translate-y-2 transition-transform duration-300",
"Read the docs"
} } div { class: "max-w-screen-2xl mx-auto pt-36",
h1 { class: "text-md", "Trusted by top companies" }
div { class: "pt-4 flex flex-row flex-wrap justify-center",
div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/futurewei\_bw.png" }
} div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/airbuslogo.svg" }
} div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/ESA\_logo.svg" }
} div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/yclogo.svg" }
} div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/satellite.webp" }
} } }
}
div { class: "relative w-full mx-4 sm:mx-auto text-gray-600",
div { class: "text-\[3em\] md:text-\[5em\] font-semibold dark:text-white text-ghdarkmetal font-sans py-12 flex flex-col",
span { "Fullstack, crossplatform," } span { "lightning fast, fully typed." } } h3 { class: "text-\[2em\] dark:text-white font-extralight text-ghdarkmetal pt-4 max-w-screen-md mx-auto",
"Dioxus is a Rust library for building apps that run on desktop, web, mobile, and more."
} div { class: "pt-12 text-white text-\[1.2em\] font-sans font-bold flex flex-row justify-center space-x-4",
a { href: "/learn/0.7/getting\_started",
data\_dioxus\_id: "216",
dioxus\_prevent\_default: "onclick",
class: "bg-red-600 py-2 px-8 hover:-translate-y-2 transition-transform duration-300",
"Quickstart"
} a { dioxus\_prevent\_default: "onclick",
href: "/learn/0.7/reference",
data\_dioxus\_id: "214",
class: "bg-blue-500 py-2 px-8 hover:-translate-y-2 transition-transform duration-300",
"Read the docs"
} } div { class: "max-w-screen-2xl mx-auto pt-36",
h1 { class: "text-md", "Trusted by top companies" } div { class: "pt-4 flex flex-row flex-wrap justify-center",
div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/futurewei\_bw.png" } } div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/airbuslogo.svg" } } div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/ESA\_logo.svg" } } div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/yclogo.svg" } } div { class: "h-12 w-40 p-2 m-4 flex justify-center items-center",
img { src: "/assets/static/satellite.webp" } } } }
}
The `dx translate` command has several flags you can use to control your html input and rsx output.
You can use the `--file` flag to translate an HTML file to RSX:
dx translate --file index.html
dx translate --file index.html
Or you can use the `--raw` flag to translate a string of HTML to RSX:
dx translate --raw "
Hello world
"
dx translate --raw "
Hello world
"
Both of those commands will output the following RSX:
div { "Hello world" }
div { "Hello world" }
The `dx translate` command will output the RSX to stdout. You can use the `--output` flag to write the RSX to a file instead.
dx translate --raw "
Hello world
" --output index.rs
dx translate --raw "
Hello world
" --output index.rs
You can automatically create a component with the `--component` flag.
dx translate --raw "
Hello world
" --component
dx translate --raw "
Hello world
" --component
This will output the following component:
fn component() -> Element {
rsx! { div { "Hello world" }
}
}
fn component() -> Element {
rsx! { div { "Hello world" } }
}
To learn more about the different flags `dx translate` supports, run `dx translate --help`.
[PREVIOUSConfigure Project](https://dioxuslabs.com/learn/0.7/guides/tools/configure)
[NEXTPlatform Support](https://dioxuslabs.com/learn/0.7/guides/platforms/)
On this page
------------
* [Usage](https://dioxuslabs.com/learn/0.7/guides/tools/translate/#usage)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/guides/)
[Utilities](https://dioxuslabs.com/learn/0.7/guides/utilities/)
[Logging](https://dioxuslabs.com/learn/0.7/guides/utilities/logging)
Dioxus has a wide range of supported platforms, each with their own logging requirements. We'll discuss the different options available for your projects.
Dioxus provides a first-party logger as part of `launch`. This sets up a tracing subscriber that cleanly integrates with the Dioxus CLI and platforms like Web and Mobile. In development mode, the `Debug` tracing level is set, and in release only the `Info` level is set.
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| { // Will only log in "dev" mode
tracing::debug!("Rendering app!");
// Will log in dev and release
tracing::info!("Rendering app!");
rsx! {} })
}
use dioxus::prelude::\*;
fn main() {
dioxus::launch(|| { // Will only log in "dev" mode
tracing::debug!("Rendering app!");
// Will log in dev and release
tracing::info!("Rendering app!");
rsx! {} })
}
To override the default or initialize the logger before `launch`, you can use the `init` function yourself:
To use Dioxus Logger, call the `init()` function:
use tracing::Level;
fn main() {
// Init logger
dioxus::logger::init(Level::INFO).expect("failed to init logger");
// Dioxus launch code
dioxus::launch(|| rsx! {})
}
use tracing::Level;
fn main() {
// Init logger
dioxus::logger::init(Level::INFO).expect("failed to init logger");
// Dioxus launch code
dioxus::launch(|| rsx! {})
}
The [Tracing](https://crates.io/crates/tracing)
crate is the logging interface that the dioxus-logger uses. It is not required to use the Tracing crate, but you will not receive logs from the Dioxus library.
The Tracing crate provides a variety of simple `println`\-like macros with varying levels of severity. The available macros are as follows with the highest severity on the bottom:
fn main() {
tracing::trace!("trace");
tracing::debug!("debug");
tracing::info!("info");
tracing::warn!("warn");
tracing::error!("error");
}
fn main() {
tracing::trace!("trace");
tracing::debug!("debug");
tracing::info!("info");
tracing::warn!("warn");
tracing::error!("error");
}
All the loggers provided on this page are, besides configuration and initialization, interfaced using these macros. Often you will also utilize the Tracing crate's `Level` enum. This enum usually represents the maximum log severity you want your application to emit and can be loaded from a variety of sources such as configuration file, environment variable, and more.
For more information, visit the Tracing crate's [docs](https://docs.rs/tracing/latest/tracing/)
.
On web, Dioxus Logger will use [tracing-wasm](https://crates.io/crates/tracing-wasm)
. On Desktop and server-based targets, Dioxus Logger will use [tracing-subscriber](https://crates.io/crates/tracing-subscriber)
's `FmtSubscriber`.
Android logs are sent to logcat. To use logcat through the Android debugger, run:
adb -d logcat
adb -d logcat
Your Android device will need developer options/usb debugging enabled.
For more information, visit android\_logger's [docs](https://docs.rs/android_logger/latest/android_logger/)
.
iOS logs are sent to oslog.
For more information, visit [oslog](https://crates.io/crates/oslog)
.
Dioxus Logger is the preferred logger to use with Dioxus if it suites your needs. There are more features to come. If there are any feature suggestions or issues with Dioxus Logger, feel free to reach out on the [Dioxus Discord Server](https://discord.gg/XgGxMSkvUM)
!
For more information, visit Dioxus Logger's [docs](https://docs.rs/dioxus-logger/latest/dioxus_logger/)
.
[PREVIOUSUtilities](https://dioxuslabs.com/learn/0.7/guides/utilities/)
[NEXTInternationalization](https://dioxuslabs.com/learn/0.7/guides/utilities/internationalization)
On this page
------------
* [Dioxus Logger](https://dioxuslabs.com/learn/0.7/guides/utilities/logging/#dioxus-logger)
* [The Tracing Crate](https://dioxuslabs.com/learn/0.7/guides/utilities/logging/#the-tracing-crate)
* [Platform Intricacies](https://dioxuslabs.com/learn/0.7/guides/utilities/logging/#platform-intricacies)
* [Viewing Logs](https://dioxuslabs.com/learn/0.7/guides/utilities/logging/#viewing-logs)
* [Final Notes](https://dioxuslabs.com/learn/0.7/guides/utilities/logging/#final-notes)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Project Setup](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup)
Fullstack Dioxus apps are structured a bit differently than client-only apps. This distinction has implications on how we organize our apps, requiring more care when adding dependencies and including code.
In this chapter, we'll explore how to use feature flags and cargo targets to structure our apps for fullstack development.
> Dioxus provides a number of templates with `dx new` to automatically bootstrap new fullstack projects.
>
> If you want to get started quickly, we suggest using one of the built-in templates and then heading on to next chapter.
A "fullstack" application is actually composed of at least two distinct binaries:
* The client binary that runs the web, desktop, or mobile application
* The server binary that renders the initial HTML and runs server functions
Because our client app and server app target different platforms, we need to include different code and different dependencies. You can conceptualize the "server" as just another platform for your app, just like you might target both iOS and Android. The server will have different dependencies than the client app, and thus you need to properly configure your app's `Cargo.toml` and build flags.
Our build tool, DX, is capable of building both the client and server of your app simultaneously. If the `--hotpatch` flag is enabled, DX will also automatically hot-reload both the client and server code in tandem.
When developing your app, you'll generally use `dx serve`. This command accepts the usual arguments you might pass to `cargo run`:
\# We can customize the build's features, profile, or release mode
dx serve --features "spicy" --release
\# We can specify examples, packages, and binaries
dx serve --example dogs
\# We can customize the build's features, profile, or release mode
dx serve --features "spicy" --release
\# We can specify examples, packages, and binaries
dx serve --example dogs
Under the hood, DX automatically detects if the target app has a server variant by checking its `Cargo.toml` for a Cargo feature called "server". In this Cargo feature, you would enable the `server` feature on Dioxus:
\[features\]
server \= \["dioxus/server"\]
\[features\]
server \= \["dioxus/server"\]
DX will also look for specific client features ( `"web"` / `"desktop"` / `"mobile"`) and enable the relevant feature depending on the target platform. DX uses the concept of "platform" to distinguish types of builds from one another.
To set a build's platform, you can use `--web`, `--desktop`, `--ios`, etc. When you specify a platform, DX also enables a corresponding feature in your Cargo.toml:
\# enabled with \`--web\`
web \= \["dioxus/web"\]
\# enabled with \`--desktop\`
desktop \= \["dioxus/desktop"\]
\# enabled with \`--mobile\`
mobile \= \["dioxus/mobile"\]
\# enabled with \`--web\`
web \= \["dioxus/web"\]
\# enabled with \`--desktop\`
desktop \= \["dioxus/desktop"\]
\# enabled with \`--mobile\`
mobile \= \["dioxus/mobile"\]
Running the command might look like:
\# sets target=wasm32-unknown-unknown, features="web", profile="wasm-dev"
dx serve --web
\# sets target=host, features="desktop", profile="desktop-dev"
dx serve --desktop
\# sets target=aarch64-apple-ios-sim, features="mobile", profile="ios-dev"
dx serve --ios
\# sets target=wasm32-unknown-unknown, features="web", profile="wasm-dev"
dx serve --web
\# sets target=host, features="desktop", profile="desktop-dev"
dx serve --desktop
\# sets target=aarch64-apple-ios-sim, features="mobile", profile="ios-dev"
dx serve --ios
If your `dioxus` dependency enables the `fullstack` feature, DX recognizes this app is a fullstack app and then creates two builds, each with a separate platform:
\[dependencies\]
dioxus \= { version \= "0.7", features \= \["fullstack"\] }
\[features\]
web \= \["dioxus/web"\]
server \= \["dioxus/server"\]
\[dependencies\]
dioxus \= { version \= "0.7", features \= \["fullstack"\] }
\[features\]
web \= \["dioxus/web"\]
server \= \["dioxus/server"\]
Internally, DX splits your input command into two separate `cargo build` commands, each with a different platform.
Feature flags like these for the client and server are automatically generated by the CLI when you run `dx new` with fullstack enabled. If you are creating a project from scratch, you will need to add the feature flags manually.
> If you are not familiar with features in rust, you can read more about feature flags in the [cargo reference](https://doc.rust-lang.org/cargo/reference/features.html)
> .
A fullstack app is comprised of two separate binaries, so DX provides a way to customize each. Usually, the default `dx serve` command is sufficient, but for complex app setups that need per-target customization, you can use the `@client` and `@server` modifiers to pass target-specific cargo args to each:
dx serve \\
@client --ios --features "optimizations" \\
@server --bin server
dx serve \\
@client --ios --features "optimizations" \\ @server --bin server
This syntax makes it possible to have two separate entrypoints for our app. This can be extremely useful if you have an existing backend and would like to launch that alongside your Dioxus frontend.
By default, DX isolates your server and client builds by levaraging Cargo Profiles. Cargo profiles let us specify certain build modifiers like opt-level, debug symbols, LTO, and other optimizations.
DX will use these profiles
* `web-dev` / `web-release`: targeting the web with `--web`
* `server-dev` / `server-release`: targeting the server (implicitly, or with `--server`)
* `desktop-dev` / `desktop-release`: targeting desktop apps with `--desktop`
* `ios-dev` / `ios-release`: targeting iOS apps with `--ios`
* `android-dev` / `android-release`: targeting Android apps with `--android`
These profiles correspond 1:1 with the "platforms" DX supports. Note that a `platform` is just a way of DX to isolate two builds from each other. You can completely customize the build, including:
* `--renderer`: swap between the various 1st-party renderers (ie `--renderer native`)
* `--bundle`: the bundle format of the build (`.app`, `.apk`, `.ipa`, etc.)
* all cargo options (`--features`, `--target`, `--profile`, `--bin`, etc.)
Many dependencies like [`tokio`](https://docs.rs/tokio/latest/tokio/index.html)
cannot be compiled to WebAssembly, and thus should only be built for the server. If these dependencies are enabled when building a WASM bundle, you will receive cryptic compilation errors. As such, we need to take care not to accidentally add server-only dependencies to our client app.
For example, if we want to interact with the filesystem in a server function, we might want to add `tokio`. The `tokio` crate provides utilities for working with async IO with abstractions like [`tokio::fs::File`](https://docs.rs/tokio/latest/tokio/fs/struct.File.html)
. Unfortunately, if try to add `tokio` with its `full` feature set, we will receive a compilation error:
\[dependencies\]
\# ...
\# â If tokio is added as a required dependency, it will be included in both the server
\# and the web bundle. The web bundle will fail to build because tokio is not
\# compatible with wasm
tokio \= { version \= "1", features \= \["full"\] }
\[dependencies\]
\# ...
\# â If tokio is added as a required dependency, it will be included in both the server
\# and the web bundle. The web bundle will fail to build because tokio is not
\# compatible with wasm
tokio \= { version \= "1", features \= \["full"\] }
error\[E0432\]: unresolved import \`crate::sys::IoSourceState\`
--\> /Users/user/.cargo/registry/src/index.crates.io-6f17d22bba15001f/mio-1.0.2/src |source.rs:14:5
14 | use crate::sys::IoSourceState;
| ^^^^^^^^^^^^^^^^^^^^^^^^^ no \`IoSourceState\` in \`sys\`
...
error\[E0432\]: unresolved import \`crate::sys::IoSourceState\`
--\> /Users/user/.cargo/registry/src/index.crates.io-6f17d22bba15001f/mio-1.0.2/src |source.rs:14:5
14 | use crate::sys::IoSourceState;
| ^^^^^^^^^^^^^^^^^^^^^^^^^ no \`IoSourceState\` in \`sys\`
...
Since we added `tokio` as a dependency for both the server and the client binary, cargo tries to compile it for each target. This fails because `tokio` is not compatible with the `wasm32-unknown-unknown` target.
To fix the issue, we can **make the dependency optional and only enable it in the server feature**:
\[dependencies\]
\# ...
\# â Since the tokio dependency is optional, it is not included in client bundle.
tokio \= { version \= "1", features \= \["full"\], optional \= true }
\[features\]
\# ...
\# â Since the tokio dependency is enabled in the server feature, it is included in
\# the server binary.
server \= \["dioxus/server", "dep:tokio"\]
\[dependencies\]
\# ...
\# â Since the tokio dependency is optional, it is not included in client bundle.
tokio \= { version \= "1", features \= \["full"\], optional \= true }
\[features\]
\# ...
\# â Since the tokio dependency is enabled in the server feature, it is included in
\# the server binary.
server \= \["dioxus/server", "dep:tokio"\]
Now when we build with `dx serve`, the project compiles successfully!
Many dependencies like [`wasm-bindgen`](https://docs.rs/wasm-bindgen/latest/wasm_bindgen/index.html)
and [`web-sys`](https://docs.rs/web-sys/latest/web_sys/index.html)
are only compatible with the client. Unlike server-only dependencies, these dependencies can compile on native targets, but they will panic when used outside of the browser.
You can reduce build times for your server and native binaries by including web dependencies only in the browser client binary.
Instead of adding web only dependencies to every binary in your project like this:
\[dependencies\]
\# ...
\# â If web-sys is added as a required dependency, it will be included in the server,
\# native, and the web bundle which makes build times longer.
web-sys \= { version \= "0.3.60", features \= \["console"\] }
\[dependencies\]
\# ...
\# â If web-sys is added as a required dependency, it will be included in the server,
\# native, and the web bundle which makes build times longer.
web-sys \= { version \= "0.3.60", features \= \["console"\] }
You can make the dependency optional and only enable it in the `web` feature in your `Cargo.toml`:
\[dependencies\]
\# ...
\# â Since the web-sys dependency is optional, it is not included in the server and
\# native bundles.
web-sys \= { version \= "0.3.60", features \= \["console"\], optional \= true }
\[features\]
\# ...
\# â Since the web-sys dependency is enabled in the web feature, it is included in
\# the web bundle.
web \= \["dioxus/web", "dep:web-sys"\]
\[dependencies\]
\# ...
\# â Since the web-sys dependency is optional, it is not included in the server and
\# native bundles.
web-sys \= { version \= "0.3.60", features \= \["console"\], optional \= true }
\[features\]
\# ...
\# â Since the web-sys dependency is enabled in the web feature, it is included in
\# the web bundle.
web \= \["dioxus/web", "dep:web-sys"\]
Once you have set up binary specific dependencies, you need to adjust any of your imports to only import the dependencies when building for the binary that includes those dependencies.
For example, if `tokio` is only enabled in the server feature, you will need to import it like this:
src/server\_tokio\_import.rs
// Since the tokio dependency is only enabled in the server feature,
// we need to only import it when the server feature is enabled.
#\[cfg(feature \= "server")\]
use {tokio::fs::File, tokio::io::AsyncReadExt};
// Since the tokio dependency is only enabled in the server feature,
// we need to only import it when the server feature is enabled.
#\[cfg(feature \= "server")\]
use {tokio::fs::File, tokio::io::AsyncReadExt};
You also need to only compile any usage of the dependency when the feature is enabled:
src/server\_tokio\_import.rs
// Since the tokio dependency is only enabled in the server feature,
// we need to only compile any usage of the dependency when the server feature is enabled.
#\[cfg(feature \= "server")\]
async fn read\_file() -> Result {
let mut file \= File::open("path/to/file").await?;
let mut contents \= String::new();
file.read\_to\_string(&mut contents).await?;
Ok(contents)
}
// The bodies of server functions automatically only compile when the server feature is enabled.
#\[server\]
async fn get\_file\_contents() -> Result {
let mut file \= File::open("path/to/file").await?;
let mut contents \= String::new();
file.read\_to\_string(&mut contents).await?;
Ok(contents)
}
// Since the tokio dependency is only enabled in the server feature,
// we need to only compile any usage of the dependency when the server feature is enabled.
#\[cfg(feature \= "server")\]
async fn read\_file() -> Result {
let mut file \= File::open("path/to/file").await?;
let mut contents \= String::new();
file.read\_to\_string(&mut contents).await?;
Ok(contents)
}
// The bodies of server functions automatically only compile when the server feature is enabled.
#\[server\]
async fn get\_file\_contents() -> Result {
let mut file \= File::open("path/to/file").await?;
let mut contents \= String::new();
file.read\_to\_string(&mut contents).await?;
Ok(contents)
}
It may be more convenient to group server or client specific code into a module that is only compiled when the feature is enabled:
src/server\_tokio\_import.rs
// Instead of configuring each item that is only used in the server, you can group
// them into a module that is only compiled when the server feature is enabled.
#\[cfg(feature \= "server")\]
mod tokio\_utilities {
use std::path::PathBuf;
use tokio::fs::File;
use tokio::io::AsyncReadExt;
pub async fn read\_file(path: PathBuf) -> Result {
let mut file \= File::open(path).await?;
let mut contents \= String::new();
file.read\_to\_string(&mut contents).await?;
Ok(contents)
}
}
// Then you can define your server functions using shared utilities you defined for
// server only code.
#\[server\]
async fn get\_file\_contents() -> Result {
let file \= tokio\_utilities::read\_file(PathBuf::from("path/to/file")).await?;
Ok(file)
}
#\[server\]
async fn get\_other\_file\_contents() -> Result {
let file \= tokio\_utilities::read\_file(PathBuf::from("path/to/other/file")).await?;
Ok(file)
}
// Instead of configuring each item that is only used in the server, you can group
// them into a module that is only compiled when the server feature is enabled.
#\[cfg(feature \= "server")\]
mod tokio\_utilities {
use std::path::PathBuf;
use tokio::fs::File;
use tokio::io::AsyncReadExt;
pub async fn read\_file(path: PathBuf) -> Result {
let mut file \= File::open(path).await?;
let mut contents \= String::new();
file.read\_to\_string(&mut contents).await?;
Ok(contents)
}
}
// Then you can define your server functions using shared utilities you defined for
// server only code.
#\[server\]
async fn get\_file\_contents() -> Result {
let file \= tokio\_utilities::read\_file(PathBuf::from("path/to/file")).await?;
Ok(file)
}
#\[server\]
async fn get\_other\_file\_contents() -> Result {
let file \= tokio\_utilities::read\_file(PathBuf::from("path/to/other/file")).await?;
Ok(file)
}
> The [rust reference](https://doc.rust-lang.org/reference/conditional-compilation.html)
> has more information about conditional compilation in rust.
If you so choose, you can split your frontend and backend into separate crates. This can be useful for larger projects where you have separate complex entrypoints for web, desktop, and mobile.
Workspace setups bring extra complexity, but they can make it much easier to share data types and functions across several different projects. For instance, you might have a single API crate used by several different apps.
In these cases, we might organize our workspace like so:
âââ Cargo.toml
âââ packages/
âââ cat-app/ â ... âââ dog-app/ â ... âââ pet-api/ ...
âââ Cargo.toml
âââ packages/
âââ cat-app/ â ... âââ dog-app/ â ... âââ pet-api/ ...
If you're using Dioxus Fullstack, you can import your `pet-api`'s server functions to call from your UI. In the client app, you can then import the `pet-api` crate:
\[dependencies\]
pet-api \= { workspace \= true }
\[dependencies\]
pet-api \= { workspace \= true }
To launch the server, you can choose one of two options:
1. Start the pet-api server from the client project
2. Launch the pet-api crate's main binary
If your server is simple enough, then option 1 can be a decent option since it automatically integrates with `dx serve`.
However, if you choose to have a dedicated server binary, then you'll need to use the `@client` and `@server` modifiers to use a different binary:
dx serve @client --bin dog-app @server --bin pet-api
dx serve @client --bin dog-app @server --bin pet-api
The built-in "Workspace" Dioxus Template can serve as a good starting point for workspace setups.
[PREVIOUSFullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[NEXTServer Side Rendering](https://dioxuslabs.com/learn/0.7/essentials/fullstack/ssr)
On this page
------------
* [The Server/Client split](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup/#the-serverclient-split)
* [How DX builds your app](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup/#how-dx-builds-your-app)
* [Customizing the Builds](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup/#customizing-the-builds)
* [Adding Server Only Dependencies](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup/#adding-server-only-dependencies)
* [Adding Client Only Dependencies](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup/#adding-client-only-dependencies)
* [Managing Binary Specific Imports](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup/#managing-binary-specific-imports)
* [Separate Frontend and Backend Crates](https://dioxuslabs.com/learn/0.7/essentials/fullstack/project_setup/#separate-frontend-and-backend-crates)
[Edit this page](https://github.com/DioxusLabs/docsite)
--------------------------------------------------------
---
# Dioxus | Fullstack crossplatform app framework for Rust
* [Tutorial\
--------](https://dioxuslabs.com/learn/0.6/guide/)
* [Web\
---](https://dioxuslabs.com/learn/0.6/guides/web/)
* [Desktop\
-------](https://dioxuslabs.com/learn/0.6/guides/desktop/)
* [Mobile\
------](https://dioxuslabs.com/learn/0.6/guides/mobile/)
* [Fullstack\
---------](https://dioxuslabs.com/learn/0.6/guides/fullstack/)
* [Typesafe Routing\
----------------](https://dioxuslabs.com/learn/0.6/router/reference/)
Using Stable Version
0.7.0
[Version 0.70.7.0](https://dioxuslabs.com/learn/0.7/)
[Version 0.60.6.3](https://dioxuslabs.com/learn/0.6/)
[Version 0.50.5.7](https://dioxuslabs.com/learn/0.5/)
[Version 0.40.4.3](https://dioxuslabs.com/learn/0.4/)
[Version 0.30.3.2](https://dioxuslabs.com/learn/0.3/)
[Dioxus 0.7.0](https://dioxuslabs.com/learn/0.7/)
[Welcome](https://dioxuslabs.com/learn/0.7/)
[Overview](https://dioxuslabs.com/learn/0.7/essentials/)
[Fullstack](https://dioxuslabs.com/learn/0.7/essentials/fullstack/)
[Server Side Rendering](https://dioxuslabs.com/learn/0.7/essentials/fullstack/ssr)
Dioxus Fullstack supports a powerful feature called "server side rendering" (SSR). SSR enables your apps to load data on the server _before_ sending HTML to the client.
Server-side-rendering improve's your site's page load times and makes it easier for web crawlers like Google to index. Sites that are easier to index rank higher in web searches, improving your conversion rate and ultimately, your bottom line.
You might be intimidated by the various terms, tradeoffs, and details. Don't worry - these additional concepts are simply optimizations to make your site perform better in various ways. You can still build a beautiful, useful, accessible site without enhancements like server-side-rendering.
The terms SSR and CSR refer to two different approaches to rendering pages:
* **CSR**: _Client-side-rendering_, data is loaded by a "skeleton" page with `fetch()`
* **SSR**: _Server-side-rendering_, data is loaded on the server and serialized into HTML
SSR gives us the ability to send a more "complete" HTML document to the user when the visit the site, making the site immediately usable and improving its ranking in search results.
The architecture of web applications have shifted substantially over the years. Client-side-rendering is a somewhat "modern" architecture where the server responds to user requests with a "skeleton" HTML.
The skeleton HTML might be barebones - something like:
![](\\"static/futurewei\_bw.png\\"\)
![](\\"static/airbuslogo.svg\\"\)
![](\\"static/ESA\_logo.svg\\"\){kind=logo}
![](\\"static/yclogo.svg\\"\)
![](\\"static/satellite.webp\\"\)