swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs to reflect changes in master (#670)

Browse Source 
* work on updating docs to master version

* more updates

* more polishing

* finish interactivity chapter

* finish updating core guide

* fix grammer mistakes and typos

* more grammer fixes

* add liveview guide

* remove doc build

* WIP custom renderer docs

* add axum as dev-dependancy to guide

* fix examples

* fix overview example

* use md book fork to fix compilation
This commit is contained in:
ealmloff authored and GitHub committed 2023-01-06 15:00:12 -08:00
1 parent a616a8fa9d
commit cd4474cc4f
51 files changed
+870 -549
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/guide/src/en/getting_started/desktop.md
+42 -5
View File
@@ -1,21 +1,58 @@
# Desktop Application
# Desktop Overview
Build a standalone native desktop app that looks and feels the same across operating systems.
Apps built with Dioxus are typically <5mb in size and use existing system resources, so they won't hog extreme amounts of RAM or memory.
Examples:
- [File explorer](https://github.com/DioxusLabs/example-projects/blob/master/file-explorer)
- [WiFi scanner](https://github.com/DioxusLabs/example-projects/blob/master/wifi-scanner)
- [File Explorer](https://github.com/DioxusLabs/example-projects/blob/master/file-explorer)
- [WiFi Scanner](https://github.com/DioxusLabs/example-projects/blob/master/wifi-scanner)
[![File ExplorerExample](https://raw.githubusercontent.com/DioxusLabs/example-projects/master/file-explorer/image.png)](https://github.com/DioxusLabs/example-projects/tree/master/file-explorer)
## Support
The desktop is a powerful target for Dioxus, but is currently limited in capability when compared to the Web platform. Currently, desktop apps are rendered with the platform's WebView library, but your Rust code is running natively on a native thread. 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, filesystem, etc are all viable APIs. In the future, we plan to move to a custom webrenderer-based DOM renderer with WGPU integrations.
The desktop is a powerful target for Dioxus but is currently limited in capability when compared to the Web platform. Currently, desktop apps are rendered with the platform's WebView library, but your Rust code is running natively on a native thread. 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, filesystem, etc are all viable APIs. In the future, we plan to move to a custom web renderer-based DOM renderer with WGPU integrations.
Dioxus Desktop is built off [Tauri](https://tauri.app/). Right now there aren't any Dioxus abstractions over keyboard shortcuts, menubar, handling, etc, so you'll want to leverage Tauri – mostly [Wry](http://github.com/tauri-apps/wry/) and [Tao](http://github.com/tauri-apps/tao)) directly.
# Getting started
## Platform-Specific Dependencies
Dioxus desktop renders through a web view. Depending on your platform, you might need to install some dependancies.
### Windows
Windows Desktop apps depend on WebView2 – a library that should be installed in all modern Windows distributions. If you have Edge installed, then Dioxus will work fine. If you *don't* have Webview2, [then you can install it through Microsoft](https://developer.microsoft.com/en-us/microsoft-edge/webview2/). MS provides 3 options:
1. A tiny "evergreen" *bootstrapper* that fetches an installer from Microsoft's CDN
2. A tiny *installer* that fetches Webview2 from Microsoft's CDN
3. A statically linked version of Webview2 in your final binary for offline users
For development purposes, use Option 1.
### Linux
Webview Linux apps require WebkitGtk. When distributing, this can be part of your dependency tree in your `.rpm` or `.deb`. However, likely, your users will already have WebkitGtk.
```bash
sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev libappindicator3-dev
```
When using Debian/bullseye `libappindicator3-dev` is no longer available but replaced by `libayatana-appindicator3-dev`.
```bash
# on Debian/bullseye use:
sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev libayatana-appindicator3-dev
```
If you run into issues, make sure you have all the basics installed, as outlined in the [Tauri docs](https://tauri.studio/v1/guides/getting-started/prerequisites#setting-up-linux).
### MacOS
Currently – everything for macOS is built right in! However, you might run into an issue if you're using nightly Rust due to some permissions issues in our Tao dependency (which have been resolved but not published).
## Creating a Project
Create a new crate:
@@ -25,7 +62,7 @@ cargo new --bin demo
cd demo
```
Add Dioxus and the `desktop` renderer (this will edit `Cargo.toml`):
Add Dioxus and the desktop renderer as dependencies (this will edit your `Cargo.toml`):
```shell
cargo add dioxus
docs/guide/src/en/getting_started/hot_reload.md
+4 -7
View File
@@ -1,15 +1,12 @@
# Setting Up Hot Reload
1. Hot reloading allows much faster iteration times inside of rsx calls by interperting them and streaming the edits.
1. Hot reloading allows much faster iteration times inside of rsx calls by interpreting them and streaming the edits.
2. It is useful when changing the styling/layout of a program, but will not help with changing the logic of a program.
3. Currently the cli only implements hot reloading for the web renderer.
# Setup
Install [dioxus-cli](https://github.com/DioxusLabs/cli).
Enable the hot-reload feature on dioxus:
```toml
dioxus = { version = "*", features = ["hot-reload"] }
```
Hot reloading is automatically enabled when using the web renderer on debug builds.
# Usage
1. run:
@@ -21,5 +18,5 @@ dioxus serve --hot-reload
4. save and watch the style change without recompiling
# Limitations
1. The interperter can only use expressions that existed on the last full recompile. If you introduce a new variable or expression to the rsx call, it will trigger a full recompile to capture the expression.
2. Components and Iterators can contain abritary rust code, and will trigger a full recompile when changed.
1. The interpreter can only use expressions that existed on the last full recompile. If you introduce a new variable or expression to the rsx call, it will trigger a full recompile to capture the expression.
2. Components and Iterators can contain arbitrary rust code and will trigger a full recompile when changed.
docs/guide/src/en/getting_started/index.md
+9 -49
View File
@@ -12,63 +12,23 @@ Dioxus integrates very well with the [Rust-Analyzer LSP plugin](https://rust-ana
Head over to [https://rust-lang.org](http://rust-lang.org) and install the Rust compiler.
We strongly recommend going through the [official Rust book](https://doc.rust-lang.org/book/ch01-00-getting-started.html) _completely_. However, our hope is that a Dioxus app can serve as a great first Rust project. With Dioxus, you'll learn about:
We strongly recommend going through the [official Rust book](https://doc.rust-lang.org/book/ch01-00-getting-started.html) _completely_. However, we hope that a Dioxus app can serve as a great first Rust project. With Dioxus, you'll learn about:
- Error handling
- Structs, Functions, Enums
- Closures
- Macros
We've put a lot of care into making Dioxus syntax familiar and easy to understand, so you won't need deep knowledge on async, lifetimes, or smart pointers until you really start building complex Dioxus apps.
### Platform-Specific Dependencies
#### Windows
Windows Desktop apps depend on WebView2 – a library which should be installed in all modern Windows distributions. If you have Edge installed, then Dioxus will work fine. If you *don't* have Webview2, [then you can install it through Microsoft](https://developer.microsoft.com/en-us/microsoft-edge/webview2/). MS provides 3 options:
1. A tiny "evergreen" *bootstrapper* which will fetch an installer from Microsoft's CDN
2. A tiny *installer* which will fetch Webview2 from Microsoft's CDN
3. A statically linked version of Webview2 in your final binary for offline users
For development purposes, use Option 1.
#### Linux
Webview Linux apps require WebkitGtk. When distributing, this can be part of your dependency tree in your `.rpm` or `.deb`. However, it's very likely that your users will already have WebkitGtk.
```bash
sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev libappindicator3-dev
```
When using Debian/bullseye `libappindicator3-dev` is no longer available but replaced by `libayatana-appindicator3-dev`.
```bash
# on Debian/bullseye use:
sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev libayatana-appindicator3-dev
```
If you run into issues, make sure you have all the basics installed, as outlined in the [Tauri docs](https://tauri.studio/v1/guides/getting-started/prerequisites#setting-up-linux).
#### MacOS
Currently – everything for macOS is built right in! However, you might run into an issue if you're using nightly Rust due to some permissions issues in our Tao dependency (which have been resolved but not published).
### Suggested Cargo Extensions
If you want to keep your traditional `npm install XXX` workflow for adding packages, you might want to install `cargo-edit` and a few other fun `cargo` extensions:
- [cargo-expand](https://github.com/dtolnay/cargo-expand) for expanding macro calls
- [cargo tree](https://doc.rust-lang.org/cargo/commands/cargo-tree.html) – an integrated cargo command that lets you inspect your dependency tree
We've put a lot of care into making Dioxus syntax familiar and easy to understand, so you won't need deep knowledge of async, lifetimes, or smart pointers until you start building complex Dioxus apps.
## Setup Guides
Dioxus supports multiple platforms. Depending on what you want, the setup is a bit different.
Dioxus supports multiple platforms. Choose the platform you want to target below to get platform-specific setup instructions:
- [Web](web.md): running in the browser using WASM
- [Server Side Rendering](ssr.md): render Dioxus HTML as text
- [Desktop](desktop.md): a standalone app using webview
- [Mobile](mobile.md)
- [Terminal UI](tui.md): terminal text-based graphic interface
- [Web](web.md): runs in the browser through WebAssembly
- [Server Side Rendering](ssr.md): renders to HTML text on the server
- [Liveview](liveview.md): runs on the server, renders in the browser using WebSockets
- [Desktop](desktop.md): runs in a web view on desktop
- [Mobile](mobile.md): runs in a web view on mobile
- [Terminal UI](tui.md): renders text-based graphics in the terminal
docs/guide/src/en/getting_started/liveview.md
+66
View File
@@ -0,0 +1,66 @@
# Liveview
Liveview allows apps to *run* on the server and *render* in the browser. It uses WebSockets to communicate between the server and the browser.
Examples:
- [Axum Example](https://github.com/DioxusLabs/dioxus/tree/master/packages/liveview/examples/axum.rs)
- [Salvo Example](https://github.com/DioxusLabs/dioxus/tree/master/packages/liveview/examples/salvo.rs)
- [Warp Example](https://github.com/DioxusLabs/dioxus/tree/master/packages/liveview/examples/warp.rs)
## Support
Liveview is currently limited in capability when compared to the Web platform. Liveview apps run on the server in a native thread. 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, filesystem, etc are all viable APIs.
## Setup
For this guide, we're going to show how to use Dioxus Liveview with [Axum](https://docs.rs/axum/latest/axum/).
Make sure you have Rust and Cargo installed, and then create a new project:
```shell
cargo new --bin demo
cd app
```
Add Dioxus and the liveview renderer with the Axum feature as dependencies:
```shell
cargo add dioxus
cargo add dioxus-liveview --features axum
```
Next, add all the Axum dependencies. This will be different if you're using a different Web Framework
```
cargo add tokio --features full
cargo add axum
```
Your dependencies should look roughly like this:
```toml
[dependencies]
axum = "0.4.5"
dioxus = { version = "*" }
dioxus-liveview = { version = "*", features = ["axum"] }
tokio = { version = "1.15.0", features = ["full"] }
```
Now, set up your Axum app to respond on an endpoint.
```rust
{{#include ../../../examples/hello_world_liveview.rs:glue}}
```
And then add our app component:
```rust
{{#include ../../../examples/hello_world_liveview.rs:app}}
```
And that's it!
docs/guide/src/en/getting_started/mobile.md
+3 -3
View File
@@ -5,12 +5,12 @@ Build a mobile app with Dioxus!
Example: [Todo App](https://github.com/DioxusLabs/example-projects/blob/master/ios_demo)
## Support
Mobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with either the platform's WebView or experimentally through WGPU. WebView doesn't support animations, transparency, and native widgets.
Mobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with either the platform's WebView or experimentally through [WGPU](https://github.com/DioxusLabs/blitz). WebView doesn't support animations, transparency, and native widgets.
Mobile support is currently best suited for CRUD-style apps, ideally for internal teams who need to develop quickly but don't care much about animations or native widgets.
This guide is primarily targetted for iOS apps, however, you can follow it while using the `android` guide in `cargo-mobile`.
This guide is primarily targeted at iOS apps, however, you can follow it while using the `android` guide in `cargo-mobile`.
## Getting Set up
@@ -35,7 +35,7 @@ We're going to completely clear out the `dependencies` it generates for us, swap
[package]
name = "dioxus-ios-demo"
version = "0.1.0"
authors = ["Jonathan Kelley <jkelleyrtp@gmail.com>"]
authors = []
edition = "2018"
docs/guide/src/en/getting_started/ssr.md
+9 -16
View File
@@ -15,19 +15,7 @@ When working with web frameworks that require `Send`, it is possible to render a
## Setup
If you just want to render `rsx!` or a VirtualDom to HTML, check out the API docs. It's pretty simple:
```rust
// We can render VirtualDoms
let mut vdom = VirtualDom::new(app);
let _ = vdom.rebuild();
println!("{}", dioxus_ssr::render_vdom(&vdom));
// Or we can render rsx! calls directly
println!( "{}", dioxus_ssr::render_lazy(rsx! { h1 { "Hello, world!" } } );
```
However, for this guide, we're going to show how to use Dioxus SSR with `Axum`.
For this guide, we're going to show how to use Dioxus SSR with [Axum](https://docs.rs/axum/latest/axum/).
Make sure you have Rust and Cargo installed, and then create a new project:
@@ -36,7 +24,7 @@ cargo new --bin demo
cd app
```
Add Dioxus and the `ssr` renderer feature:
Add Dioxus and the ssr renderer as dependencies:
```shell
cargo add dioxus
@@ -86,8 +74,9 @@ And then add our endpoint. We can either render `rsx!` directly:
```rust
async fn app_endpoint() -> Html<String> {
// render the rsx! macro to HTML
Html(dioxus_ssr::render_lazy(rsx! {
h1 { "hello world!" }
div { "hello world!" }
}))
}
```
@@ -96,12 +85,16 @@ Or we can render VirtualDoms.
```rust
async fn app_endpoint() -> Html<String> {
// create a component that renders a div with the text "hello world"
fn app(cx: Scope) -> Element {
cx.render(rsx!(h1 { "hello world" }))
cx.render(rsx!(div { "hello world" }))
}
// create a VirtualDom with the app component
let mut app = VirtualDom::new(app);
// rebuild the VirtualDom before rendering
let _ = app.rebuild();
// render the VirtualDom to HTML
Html(dioxus_ssr::render_vdom(&app))
}
```
docs/guide/src/en/getting_started/tui.md
+10 -10
View File
@@ -8,12 +8,19 @@ You can build a text-based interface that will run in the terminal using Dioxus.
## Support
TUI support is currently quite experimental. Even the project name will change. But, if you're willing to venture into the realm of the unknown, this guide will get you started.
TUI support is currently quite experimental. But, if you're willing to venture into the realm of the unknown, this guide will get you started.
- It uses flexbox for the layout
- It only supports a subset of the attributes and elements
- Regular widgets will not work in the tui render, but the tui renderer has its own widget components that start with a capital letter. See the [widgets example](https://github.com/DioxusLabs/dioxus/blob/master/packages/tui/examples/tui_widgets.rs)
- 1px is one character line height. Your regular CSS px does not translate
- If your app panics, your terminal is wrecked. This will be fixed eventually
## Getting Set up
Start by making a new package and adding our TUI renderer.
Start by making a new package and adding Dioxus and the TUI renderer as dependancies.
```shell
cargo new --bin demo
@@ -34,15 +41,8 @@ To run our app:
cargo run
```
Press "ctrl-c" to close the app. To switch from "ctrl-c" to just "q" to quit you can launch the app with a configuration to disable the default quit and use the root TuiContext to quit on your own.
Press "ctrl-c" to close the app. To switch from "ctrl-c" to just "q" to quit you can launch the app with a configuration to disable the default quit and use the root TuiContext to quit on your own.
```rust
{{#include ../../../examples/hello_world_tui_no_ctrl_c.rs}}
```
## Notes
- Our TUI package uses flexbox for layout
- Regular widgets will not work in the tui render, but the tui renderer has it's own widget components (see [the widgets example](https://github.com/DioxusLabs/dioxus/blob/master/packages/tui/examples/tui_widgets.rs)).
- 1px is one character lineheight. Your regular CSS px does not translate.
- If your app panics, your terminal is wrecked. This will be fixed eventually.
docs/guide/src/en/getting_started/web.md
+11 -23
View File
@@ -1,8 +1,8 @@
# Web
Build single-page applications that run in the browser with Dioxus. To run on the Web, your app must be compiled to WebAssembly and depend on the `dioxus` crate with the `web` feature enabled.
Build single-page applications that run in the browser with Dioxus. 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 will load significantly faster due to [WebAssembly's StreamingCompile](https://hacks.mozilla.org/2018/01/making-webassembly-even-faster-firefoxs-new-streaming-and-tiering-compiler/) option.
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/example-projects/tree/master/todomvc)
@@ -10,21 +10,24 @@ Examples:
[![TodoMVC example](https://github.com/DioxusLabs/example-projects/raw/master/todomvc/example.png)](https://github.com/DioxusLabs/example-projects/blob/master/todomvc)
> Note: Because of the limitations of Wasm, not every crate will work with your web apps, so you'll need to make sure that your crates work without native system calls (timers, IO, etc).
> 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).
## Support
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-bingen](https://rustwasm.github.io/docs/wasm-bindgen/introduction.html).
- Dioxus provides hydration to resume apps that are rendered on the server. See the [hydration example](https://github.com/DioxusLabs/dioxus/blob/master/packages/web/examples/hydrate.rs) for more details.
## Tooling
To develop your Dioxus app for the web, you'll need a tool to build and serve your assets. We recommend using [trunk](https://trunkrs.dev) which includes a build system, Wasm optimization, a dev server, and support for SASS/CSS:
To develop your Dioxus app for the web, you'll need a tool to build and serve your assets. We recommend using [dioxus-cli](https://github.com/DioxusLabs/cli) which includes a build system, Wasm optimization, a dev server, and support hot reloading:
```shell
cargo install trunk
cargo install dioxus-cli
```
Make sure the `wasm32-unknown-unknown` target is installed:
Make sure the `wasm32-unknown-unknown` target for rust is installed:
```shell
rustup target add wasm32-unknown-unknown
```
@@ -38,28 +41,13 @@ cargo new --bin demo
cd demo
```
Add Dioxus as a dependency and add the web renderer:
Add Dioxus and the web renderer as dependencies (this will edit your `Cargo.toml`):
```bash
cargo add dioxus
cargo add dioxus-web
```
Add an `index.html` for Trunk to use. Make sure your "mount point" element has an ID of "main":
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<div id="main"> </div>
</body>
</html>
```
Edit your `main.rs`:
```rust
{{#include ../../../examples/hello_world_web.rs}}
@@ -69,5 +57,5 @@ Edit your `main.rs`:
And to serve our app:
```bash
trunk serve
dioxus serve
```