docs(book): wrote docs on live reloading and hsr

framesurge · Jan 29, 2022 · 4cf292f · 4cf292f
1 parent 469732a
commit 4cf292f
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 0 deletions.
diff --git a/docs/next/en-US/SUMMARY.md b/docs/next/en-US/SUMMARY.md
@@ -13,6 +13,7 @@
 -   [`define_app!`](/docs/reference/define-app)
 -   [Writing Views](/docs/reference/views)
 -   [Debugging](/docs/reference/debugging)
+-   [Live Reloading](/docsr/reference/live-reloading)
 -   [Templates and Routing](/docs/reference/templates/intro)
     -   [Modifying the `<head>`](/docs/reference/templates/metadata-modification)
     -   [Modifying HTTP Headers](/docs/reference/templates/setting-headers)
@@ -36,6 +37,7 @@
     -   [Global State](/docs/reference/state/global)
     -   [State Freezing](/docs/reference/state/freezing)
         -   [Freezing to IndexedDB](/docs/reference/state/idb-freezing)
+    -   [Hot State Reloading (HSR)](/docs/reference/state/hsr)
 -   [CLI](/docs/reference/cli)
     -   [Ejecting](/docs/reference/ejecting)
     -   [Snooping](/docs/reference/snooping)

diff --git a/docs/next/en-US/reference/live-reloading.md b/docs/next/en-US/reference/live-reloading.md
@@ -0,0 +1,9 @@
+# Live Reloading
+
+When you develop a Perseus app, you'll usually be using `-w` on the command you're running (e.g. `perseus serve -w`, `perseus export -sw`), which will make the CLI watch your code and rebuild your app when it changes. In addition to that, Perseus will automatically reload any browser sessions that are connected to your app, meaning you can just change your code and save the file, and then your updated app will be ready for you!
+
+In production of course, the code of your app won't change, so Perseus disables live reloading automatically when you build for production (e.g. with `perseus deploy`).
+
+If you find that live reloading isn't to your liking, you can disable it by adding `default-features = false` to the `perseus` dependency in your `Cargo.toml`, which will disable all default features, including live reloading. Currently, it's the only default feature (along with [HSR](:reference/state/hsr), which depends on it), so you don't need to enable any other features after doing this.
+
+To achieve live reloading, Perseus runs a server at <http://localhost:3100>, though, if you have something else on this port, this would be problematic. You can change the port by setting the `PERSEUS_RELOAD_SERVER_PORT` environment variable (and `PERSEUS_RELOAD_SERVER_HOST` also exists if you need to change the host).
diff --git a/docs/next/en-US/reference/state/hsr.md b/docs/next/en-US/reference/state/hsr.md
@@ -0,0 +1,27 @@
+# Hot State Reloading
+
+If you've started using Perseus with reactive state, you may have already noticed something pretty cool. If you're using `-w` in the CLI to rebuild your app when you change your code, you'll find that the state of your app is maintained! This is called *hot state reloading*, and it's currently a feature entirely unique to Perseus.
+
+If you've come from the JavaScript world, you might have heard of *hot module reloading*, or HMR, which is used by many JS frameworks to figure out which parts of your code you changed in development so that they only need to change the smallest part, meaning most of your app's state is retained. This approach requires being able to break your code up into many chunks, which is easy with JS, but currently extremely difficult with Wasm, so Perseus takes a different approach.
+
+Perseus supports [state freezing](:reference/state/freezing) automatically, which allows you to store the entire state of your app in a string and reload from that at any time. Perseus also supports [freezing that state to IndexedDB](:reference/state/idb-freezing). When you combine that with Perseus' [live reloading](:reference/live-reloading) system, why not freeze the state before every live reload and thaw it afterward? This is exactly what Perseus does, and it means that you can change your code and pick up from *exactly* where you were in your app without missing a beat.
+
+If you ever want to ditch the current state completely, just manually reload the page in your browser (usually by pressing `Ctrl+R` or the reload button) and Perseus will start your app afresh!
+
+HSR is inbuilt into Perseus, and it automatically enabled for all development builds. When you build for production (e.g. with `perseus deploy`), HSR will automatically be turned off, and you won't have to worry about it anymore. If you feel HSR gets in your way, you can easily disable it by disabling Perseus' default features (by adding `default-features = false` to the properties of the dependency `perseus` in your `Cargo.toml`). Note though that this will also disable [live reloading](:reference/live-reloading), and you'll need to manually the `live-reload` feature to get that back.
+
+## Problems
+
+HSR is far less buggy than most implementations of HMR because it takes advantage of features built into Perseus' core, though there are some cases in which it won't work. If you're finding that you make a modification to your code and your last state isn't being restored, you'll probably find the reason here.
+
+### Incorrect Data Model
+
+This is the most common case. If you're finding that most state properties are being restored except one or two, then you'll probably find that that those properties aren't in your template's data model. In other words, they aren't part of the state for your template that you're providing to Perseus, which usually means you're setting them up as `Signal`s separately. Moving them into your data model should solve your problems.
+
+### New Data Model
+
+If you've changed the structure of your template's data model, for example by adding a new property that it includes, then you'll find that Perseus can't deserialize the state it kept from before properly (it saved your old data model, which is different to the new one), so it'll abort attempting to thaw the old state and regenerate from scratch. Unfortunately, due to the strictness of Rust's type system, this is unavoidable.
+
+### Corrupt Entry
+
+If your state isn't restored and the above reasons don't fit, then it's possible that the state may have somehow been corrupted. That said, this is very unlikely, and really shouldn't happen outside contrived scenarios. That said, Perseus should automatically resolve this by clearing the stale state and the next reload should work properly. If it doesn't, you should manually reload the page to get out of any strange logic issues. If that still doesn't work, try going into your browser's developer tools and making the console logs persist across reloads, there could be some helpful error messages in there (if they occur just before the CLi-induced reload, they'll be wiped away by the browser).