freya/_docs/hot_reload.rs
1//! # Hot Reload
2//!
3//! Freya supports hot reloading: while your app is running, changes to your
4//! code can be patched into the live process so you see updates without a
5//! full rebuild and restart.
6//!
7//! It is powered by [`subsecond`](https://crates.io/crates/subsecond) and is
8//! driven by the `dx` CLI.
9//!
10//! ## Installing the Dioxus CLI
11//!
12//! Hot reload is driven by the `dx` binary that ships with the Dioxus CLI.
13//! Install it with:
14//!
15//! ```sh
16//! cargo install dioxus-cli
17//! ```
18//!
19//! ## Enabling Hot Reload
20//!
21//! Hot reload is gated behind the `hotreload` feature flag.
22//! The recommended approach is to declare a feature in **your own crate** that
23//! forwards to Freya's, so hot reload is never included in default or release
24//! builds:
25//!
26//! ```toml
27//! # In your Cargo.toml
28//! [features]
29//! hotreload = ["freya/hotreload"]
30//! ```
31//!
32//! ## Running Your App with Hot Reload
33//!
34//! Use `dx serve` with the `--hot-patch` flag and your `hotreload` feature
35//! enabled:
36//!
37//! ```sh
38//! dx serve --hot-patch --features hotreload
39//! ```
40//!
41//! `dx` will build and launch your app, then watch your sources. When you save
42//! a file, it compiles a patch and pushes it into the running process; Freya
43//! re-renders the UI so you can see the change immediately.
44//!
45//! To hot reload an example instead of the main binary, pass `--example`:
46//!
47//! ```sh
48//! dx serve --hot-patch --features hotreload --example my_example
49//! ```
50//!
51//! ## What Happens on Each Patch
52//!
53//! When a hot patch arrives, Freya:
54//!
55//! 1. Cancels every running task spawned with `spawn`.
56//! 2. Resets every scope's hook state (`use_state`, `use_memo`, etc.).
57//! 3. Marks every scope dirty and triggers a full re-render.
58//!
59//! In other words, hot reload re-runs your components against the patched
60//! code, but **the application state stored in hooks is reset to its initial
61//! values** on every patch.
62//!
63//! ## Limitations
64//!
65//! Hot reload is a development convenience, not a substitute for a rebuild.
66//! Keep these caveats in mind:
67//!
68//! - **Hook state is reset.** Any value held by `use_state`, `use_memo`, etc.
69//! goes back to its initial value on every patch.
70//! - **Tasks are cancelled.** Tasks spawned with `spawn` are dropped when a
71//! patch lands. Long-running background work will need to be restarted by
72//! the components that own it.
73//! - **Subsecond patching constraints.** Subsecond patches function bodies in
74//! the running binary. Changes that alter the program's structure (adding
75//! or removing functions, types, or trait impls; changing function
76//! signatures; modifying struct layouts; touching `const`/`static`
77//! initializers) cannot be applied as a patch. When `dx` cannot patch a
78//! change, restart the app to pick it up.