diff --git a/Cargo.toml b/Cargo.toml index 0148b2eac..20e939b79 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -20,8 +20,8 @@ dioxus-web = { path = "./packages/web", version = "^0.0.2", optional = true } dioxus-desktop = { path = "./packages/desktop", version = "^0.1.1", optional = true } dioxus-ssr = { path = "./packages/ssr", version = "0.1.1", optional = true } -# dioxus-router = { path = "./packages/router", optional = true } -# dioxus-mobile = { path = "./packages/mobile", optional = true } +dioxus-router = { path = "./packages/router", optional = true } +dioxus-mobile = { path = "./packages/mobile", optional = true } # dioxus-liveview = { path = "./packages/liveview", optional = true } [features] @@ -33,8 +33,8 @@ html = ["dioxus-html"] ssr = ["dioxus-ssr"] web = ["dioxus-web"] desktop = ["dioxus-desktop"] +router = ["dioxus-router"] -# router = ["dioxus-router"] # "dioxus-router/web" # "dioxus-router/desktop" # desktop = ["dioxus-desktop", "dioxus-router/desktop"] diff --git a/README.md b/README.md index 7d68f3737..3588c961b 100644 --- a/README.md +++ b/README.md @@ -91,12 +91,12 @@ cargo run --features desktop --example EXAMPLE - - - - - - + + + + + +
WebDesktopMobileTUIStateToolsTutorialWebDesktopSSRMobileState
diff --git a/docs/reference/.gitignore b/docs/reference/.gitignore new file mode 100644 index 000000000..25d80f5f3 --- /dev/null +++ b/docs/reference/.gitignore @@ -0,0 +1 @@ +reference diff --git a/docs/reference/src/README.md b/docs/reference/src/README.md index e69de29bb..6de14f333 100644 --- a/docs/reference/src/README.md +++ b/docs/reference/src/README.md @@ -0,0 +1,27 @@ +# Dioxus: Reference and Advanced Guides + +![dioxuslogo](./images/dioxuslogo_full.png) + +**Dioxus** is a framework and ecosystem for building fast, scalable, and robust user interfaces with the Rust programming language. This guide will help you get started with Dioxus running on the Web, Desktop, Mobile, and more. + +> This book is the reference and Advanced Guides for the Dioxus framework. For a tutorial on how to actually *use* Dioxus, make sure to check out the [official guide](https://dioxuslabs.com/guide/). + + +## Reference and Guides + +With the reference, we aim to maintain documentation of functionality that might not be mentioned in the official guide to keep the information load to a minimum. Some topics not included by the guide but discussed in the reference include: + +- ThreadSafety of the VirtualDom +- Full usage of `rsx!` and included features +- Spread pattern for component properties +- Testing +- Memoization in Depth +- Custom Elements +- Custom Renderers + + +## Contributing + +If this doc is lacking in any way, is confusing, has a typo, or you'd just like to help improve things, feel free to make a PR against the [Dioxus repo](https://github.com/DioxusLabs/dioxus/tree/master/docs/reference). + +All contributions will be licensed under MIT/Apache2. diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index a83f3c476..3feb9fe36 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -2,60 +2,42 @@ - [Introduction](README.md) -- [Web](web/intro.md) - - [Getting Started](web/setup.md) - - [Events](concepts/errorhandling.md) - -- [Desktop](desktop/intro.md) - - [Getting Started](desktop/setup.md) - - [events](desktop/.md) - -- [Mobile](concepts/managing_state.md) - - [Getting Started](concepts/sharedstate.md) - - [Specifics](concepts/errorhandling.md) - -- [Working with Async](concepts/async.md) +- [Web](web/index.md) +- [Desktop](desktop/index.md) +- [Mobile](mobile/index.md) +- [SSR](ssr/index.md) +- [TUI](tui/index.md) -- [Code Reference]() - - [Code Reference]() - - [Code Reference]() - - [Code Reference]() - - [Code Reference]() +- [Advanced Guides](guide/index.md) + - [RSX in Depth](guide/rsx_in_depth.md) + - [Components](guide/components.md) + - [Props](guide/props.md) + - [Memoization](guide/memoization.md) + - [Performance](guide/performance.md) + - [Testing](guide/testing.md) + - [Building Elements with NodeFactory](guide/rsx.md) + - [Custom Elements](guide/custom_elements.md) + - [Custom Renderer](guide/custom_renderer.md) + - [Server-side components](guide/server_side_components.md) + - [Bundling and Distributing](guide/bundline.md) -- [Topics in Depth](depth/topics.md) - - [RSX](depth/rsx.md) - - [Components](depth/components.md) - - [Props](depth/props.md) - - [Memoization](depth/memoization.md) - - [Performance](depth/performance.md) - - [Testing](depth/testing.md) - -- [Advanced Guides](tutorial/advanced_guides.md) - - [Memoization](concepts/memoization.md) - - [RSX in Depth](concepts/rsx_in_depth.md) - - [Building Elements with NodeFactory](concepts/rsx.md) - - [Custom Elements](concepts/custom_elements.md) - - [Custom Renderer](concepts/custom_renderer.md) - - [Server-side components](concepts/server_side_components.md) - - [Bundling and Distributing](concepts/bundline.md) - -- [Reference Guide]() - - [Anti-patterns]() - - [Children]() - - [Conditional Rendering]() - - [Controlled Inputs]() - - [Custom Elements]() - - [Empty Components]() - - [Error Handling]() - - [Fragments]() - - [Global CSS]() - - [Inline Styles]() - - [Iterators]() - - [Listeners]() - - [Memoization]() - - [Node Refs]() - - [Spread Pattern]() - - [State Management]() - - [Suspense]() - - [task]() - - [Testing]() +- [Reference Guide](reference/reference.md) + - [Anti-patterns](reference/anti.md) + - [Children](reference/children.md) + - [Conditional Rendering](reference/conditional.md) + - [Controlled Inputs](reference/controlled.md) + - [Custom Elements](reference/custom.md) + - [Empty Components](reference/empty.md) + - [Error Handling](reference/error.md) + - [Fragments](reference/fragments.md) + - [Global CSS](reference/global.md) + - [Inline Styles](reference/inline.md) + - [Iterators](reference/iterators.md) + - [Listeners](reference/listeners.md) + - [Memoization](reference/memoization.md) + - [Node Refs](reference/node.md) + - [Spread Pattern](reference/spread.md) + - [State Management](reference/state.md) + - [Suspense](reference/suspense.md) + - [task](reference/task.md) + - [Testing](reference/testing.md) diff --git a/docs/reference/src/desktop/index.md b/docs/reference/src/desktop/index.md new file mode 100644 index 000000000..d96960576 --- /dev/null +++ b/docs/reference/src/desktop/index.md @@ -0,0 +1,6 @@ +# Desktop + + +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't! diff --git a/docs/reference/src/guide/bundline.md b/docs/reference/src/guide/bundline.md new file mode 100644 index 000000000..963cf5490 --- /dev/null +++ b/docs/reference/src/guide/bundline.md @@ -0,0 +1 @@ +# Bundling and Distributing diff --git a/docs/reference/src/guide/components.md b/docs/reference/src/guide/components.md new file mode 100644 index 000000000..0eac4eb52 --- /dev/null +++ b/docs/reference/src/guide/components.md @@ -0,0 +1 @@ +# Components diff --git a/docs/reference/src/guide/custom_elements.md b/docs/reference/src/guide/custom_elements.md new file mode 100644 index 000000000..3b24ad9fe --- /dev/null +++ b/docs/reference/src/guide/custom_elements.md @@ -0,0 +1 @@ +# Custom Elements diff --git a/docs/reference/src/guide/custom_renderer.md b/docs/reference/src/guide/custom_renderer.md new file mode 100644 index 000000000..577b4f5d3 --- /dev/null +++ b/docs/reference/src/guide/custom_renderer.md @@ -0,0 +1 @@ +# Custom Renderer diff --git a/docs/reference/src/guide/index.md b/docs/reference/src/guide/index.md new file mode 100644 index 000000000..53d2cb54f --- /dev/null +++ b/docs/reference/src/guide/index.md @@ -0,0 +1 @@ +# Advanced Guides diff --git a/docs/reference/src/guide/memoization.md b/docs/reference/src/guide/memoization.md new file mode 100644 index 000000000..3ed477f68 --- /dev/null +++ b/docs/reference/src/guide/memoization.md @@ -0,0 +1 @@ +# Memoization diff --git a/docs/reference/src/guide/performance.md b/docs/reference/src/guide/performance.md new file mode 100644 index 000000000..6babb314a --- /dev/null +++ b/docs/reference/src/guide/performance.md @@ -0,0 +1 @@ +# Performance diff --git a/docs/reference/src/guide/props.md b/docs/reference/src/guide/props.md new file mode 100644 index 000000000..d4b69bda7 --- /dev/null +++ b/docs/reference/src/guide/props.md @@ -0,0 +1 @@ +# Props diff --git a/docs/reference/src/guide/rsx.md b/docs/reference/src/guide/rsx.md new file mode 100644 index 000000000..189f5934c --- /dev/null +++ b/docs/reference/src/guide/rsx.md @@ -0,0 +1 @@ +# Building Elements with NodeFactory diff --git a/docs/reference/src/guide/rsx_in_depth.md b/docs/reference/src/guide/rsx_in_depth.md new file mode 100644 index 000000000..e204b22c7 --- /dev/null +++ b/docs/reference/src/guide/rsx_in_depth.md @@ -0,0 +1 @@ +# RSX in Depth diff --git a/docs/reference/src/guide/server_side_components.md b/docs/reference/src/guide/server_side_components.md new file mode 100644 index 000000000..a8c4f6182 --- /dev/null +++ b/docs/reference/src/guide/server_side_components.md @@ -0,0 +1 @@ +# Server-side components diff --git a/docs/reference/src/guide/testing.md b/docs/reference/src/guide/testing.md new file mode 100644 index 000000000..f00b526a9 --- /dev/null +++ b/docs/reference/src/guide/testing.md @@ -0,0 +1 @@ +# Testing diff --git a/docs/reference/src/images/dioxuslogo_full.png b/docs/reference/src/images/dioxuslogo_full.png new file mode 100644 index 000000000..7d08f2af8 Binary files /dev/null and b/docs/reference/src/images/dioxuslogo_full.png differ diff --git a/docs/reference/src/mobile/index.md b/docs/reference/src/mobile/index.md new file mode 100644 index 000000000..71694af59 --- /dev/null +++ b/docs/reference/src/mobile/index.md @@ -0,0 +1,4 @@ +# Mobile +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't! diff --git a/docs/reference/src/mobile/intro.md b/docs/reference/src/mobile/intro.md new file mode 100644 index 000000000..71694af59 --- /dev/null +++ b/docs/reference/src/mobile/intro.md @@ -0,0 +1,4 @@ +# Mobile +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't! diff --git a/docs/reference/src/ssr/index.md b/docs/reference/src/ssr/index.md new file mode 100644 index 000000000..758d3199c --- /dev/null +++ b/docs/reference/src/ssr/index.md @@ -0,0 +1,4 @@ +# SSR +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't! diff --git a/docs/reference/src/ssr/intro.md b/docs/reference/src/ssr/intro.md new file mode 100644 index 000000000..758d3199c --- /dev/null +++ b/docs/reference/src/ssr/intro.md @@ -0,0 +1,4 @@ +# SSR +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't! diff --git a/docs/reference/src/tui/index.md b/docs/reference/src/tui/index.md new file mode 100644 index 000000000..9b9e398f1 --- /dev/null +++ b/docs/reference/src/tui/index.md @@ -0,0 +1 @@ +# TUI diff --git a/docs/reference/src/tui/intro.md b/docs/reference/src/tui/intro.md new file mode 100644 index 000000000..24a7a503c --- /dev/null +++ b/docs/reference/src/tui/intro.md @@ -0,0 +1,4 @@ +# TUI +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't! diff --git a/docs/reference/src/web/index.md b/docs/reference/src/web/index.md new file mode 100644 index 000000000..eefa5e6d8 --- /dev/null +++ b/docs/reference/src/web/index.md @@ -0,0 +1,109 @@ +# Getting Started: Dioxus for Web + +[*"Pack your things, we're going on an adventure!"*](https://trunkrs.dev) + +Dioxus is well supported for the web through WebAssembly. 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. + +Building Dioxus apps for the web requires much less configuration than our JavaScript counterparts. + +## 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. + +Currently, trunk projects can only build the root binary (ie the `main.rs`). To build a new Dioxus compatible project, this should get you up and running. + +First, [install trunk](https://trunkrs.dev/#install): +```shell +$ cargo install trunk +``` + +Make sure the `wasm32-unknown-unknown` target is installed: +```shell +$ rustup target add wasm32-unknown-uknown +``` + +Create a new project: + +```shell +$ cargo new --bin demo +$ cd demo +``` + +Add Dioxus with the `web` features: + +``` +$ cargo add dioxus --features web +``` + +Add an `index.html` for Trunk to use. Make sure your "mount point" element has an ID of "main" (this can be configured later): + +```html + + + + + +
+ + +``` + +Edit your `main.rs`: +```rust +// main.rs + +use dioxus::prelude::*; + +fn main() { + dioxus::web::launch(app); +} + +fn app(cx: Scope) -> Element { + cx.render(rsx!{ + div { "hello, wasm!" } + }) +} +``` + + +And to serve our app: + +```shell +trunk serve +``` + +To build our app and publish it to Github: + +- Make sure Github Pages is set up for your repo +- Build your app with `trunk build --release` +- Move your generated HTML/CSS/JS/Wasm from `dist` into the folder configured for Github Pages +- Add and commit with git +- Push to Github + +That's it! + +## Future Build Tool + +We are currently working on our own build tool called [Dioxus Studio](http://github.com/dioxusLabs/studio) which will support: +- an interactive TUI +- on-the-fly reconfiguration +- hot CSS reloading +- two-way data binding between browser and source code +- an interpreter for `rsx!` +- ability to publish to github/netlify/vercel +- bundling for iOS/Desktop/etc + +## Features + +Currently, the web supports: + +- Pre-rendering/Hydration + +## Events + +The regular events in the `html` crate work just fine in the web. + + +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't! diff --git a/docs/reference/src/web/intro.md b/docs/reference/src/web/intro.md new file mode 100644 index 000000000..eefa5e6d8 --- /dev/null +++ b/docs/reference/src/web/intro.md @@ -0,0 +1,109 @@ +# Getting Started: Dioxus for Web + +[*"Pack your things, we're going on an adventure!"*](https://trunkrs.dev) + +Dioxus is well supported for the web through WebAssembly. 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. + +Building Dioxus apps for the web requires much less configuration than our JavaScript counterparts. + +## 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. + +Currently, trunk projects can only build the root binary (ie the `main.rs`). To build a new Dioxus compatible project, this should get you up and running. + +First, [install trunk](https://trunkrs.dev/#install): +```shell +$ cargo install trunk +``` + +Make sure the `wasm32-unknown-unknown` target is installed: +```shell +$ rustup target add wasm32-unknown-uknown +``` + +Create a new project: + +```shell +$ cargo new --bin demo +$ cd demo +``` + +Add Dioxus with the `web` features: + +``` +$ cargo add dioxus --features web +``` + +Add an `index.html` for Trunk to use. Make sure your "mount point" element has an ID of "main" (this can be configured later): + +```html + + + + + +
+ + +``` + +Edit your `main.rs`: +```rust +// main.rs + +use dioxus::prelude::*; + +fn main() { + dioxus::web::launch(app); +} + +fn app(cx: Scope) -> Element { + cx.render(rsx!{ + div { "hello, wasm!" } + }) +} +``` + + +And to serve our app: + +```shell +trunk serve +``` + +To build our app and publish it to Github: + +- Make sure Github Pages is set up for your repo +- Build your app with `trunk build --release` +- Move your generated HTML/CSS/JS/Wasm from `dist` into the folder configured for Github Pages +- Add and commit with git +- Push to Github + +That's it! + +## Future Build Tool + +We are currently working on our own build tool called [Dioxus Studio](http://github.com/dioxusLabs/studio) which will support: +- an interactive TUI +- on-the-fly reconfiguration +- hot CSS reloading +- two-way data binding between browser and source code +- an interpreter for `rsx!` +- ability to publish to github/netlify/vercel +- bundling for iOS/Desktop/etc + +## Features + +Currently, the web supports: + +- Pre-rendering/Hydration + +## Events + +The regular events in the `html` crate work just fine in the web. + + +## Future Steps + +Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!