From 557ff447a9d731f3b637aff2fdebb153c07a4610 Mon Sep 17 00:00:00 2001 From: Evan Almloff Date: Fri, 8 Aug 2025 14:41:17 -0500 Subject: [PATCH 1/4] Split docs-rs and normal readmes --- Cargo.lock | 37 +++ Cargo.toml | 3 + packages/autofmt/README-docs-rs.md | 43 ++++ packages/autofmt/README.md | 22 +- packages/autofmt/src/lib.rs | 2 +- packages/check/README-docs-rs.md | 39 +++ packages/check/README.md | 22 +- packages/check/src/lib.rs | 2 +- packages/cli-config/README-docs-rs.md | 53 ++++ packages/cli-config/README.md | 55 ++++- packages/cli-config/src/lib.rs | 53 +--- packages/cli/README-docs-rs.md | 68 ++++++ packages/cli/README.md | 6 +- packages/cli/src/main.rs | 2 +- packages/config-macro/README-docs-rs.md | 39 +++ packages/config-macro/README.md | 22 +- packages/config-macro/src/lib.rs | 2 +- packages/config-macros/README-docs-rs.md | 15 ++ packages/config-macros/README.md | 5 +- packages/config-macros/src/lib.rs | 2 + packages/const-serialize/README-docs-rs.md | 57 +++++ packages/const-serialize/README.md | 3 +- packages/const-serialize/src/lib.rs | 2 +- packages/core-macro/README-docs-rs.md | 46 ++++ packages/core-macro/README.md | 22 +- packages/core-macro/src/lib.rs | 2 +- packages/core/README-docs-rs.md | 99 ++++++++ packages/core/README.md | 11 +- packages/core/src/lib.rs | 2 +- packages/crates-io-readme/Cargo.toml | 11 + packages/crates-io-readme/src/main.rs | 105 ++++++++ packages/depinfo/README-docs-rs.md | 14 ++ packages/depinfo/README.md | 7 +- packages/depinfo/src/lib.rs | 5 +- packages/desktop/README-docs-rs.md | 51 ++++ packages/desktop/README.md | 24 +- packages/desktop/src/lib.rs | 2 +- packages/dioxus/README-docs-rs.md | 229 ++++++++++++++++++ packages/dioxus/README.md | 15 +- packages/dioxus/src/lib.rs | 2 +- packages/fullstack-hooks/README-docs-rs.md | 32 +++ packages/fullstack-hooks/README.md | 3 +- packages/fullstack-hooks/src/lib.rs | 2 +- packages/fullstack-protocol/README-docs-rs.md | 3 + packages/fullstack-protocol/README.md | 3 +- packages/fullstack-protocol/src/lib.rs | 2 +- packages/fullstack/README-docs-rs.md | 157 ++++++++++++ packages/fullstack/README.md | 22 +- packages/fullstack/src/lib.rs | 2 +- packages/generational-box/README-docs-rs.md | 30 +++ packages/generational-box/README.md | 3 +- packages/generational-box/src/lib.rs | 2 +- packages/hooks/README-docs-rs.md | 80 ++++++ packages/hooks/README.md | 22 +- packages/hooks/src/lib.rs | 2 +- packages/html/README-docs-rs.md | 105 ++++++++ packages/html/README.md | 22 +- packages/html/src/lib.rs | 2 +- packages/interpreter/README-docs-rs.md | 53 ++++ packages/interpreter/README.md | 22 +- packages/interpreter/src/lib.rs | 2 +- packages/liveview/README-docs-rs.md | 49 ++++ packages/liveview/README.md | 22 +- packages/liveview/src/lib.rs | 2 +- packages/logger/README-docs-rs.md | 89 +++++++ packages/logger/README.md | 15 +- packages/logger/src/lib.rs | 1 + .../manganis/manganis-macro/README-docs-rs.md | 3 + packages/manganis/manganis-macro/README.md | 3 +- packages/manganis/manganis-macro/src/lib.rs | 2 +- packages/manganis/manganis/README-docs-rs.md | 31 +++ packages/manganis/manganis/README.md | 3 +- packages/manganis/manganis/src/lib.rs | 2 +- packages/router/README-docs-rs.md | 138 +++++++++++ packages/router/README.md | 22 +- packages/router/src/lib.rs | 2 +- packages/rsx-rosetta/README-docs-rs.md | 54 +++++ packages/rsx-rosetta/README.md | 22 +- packages/rsx-rosetta/src/lib.rs | 2 +- packages/server-macro/src/lib.rs | 2 +- packages/signals/README-docs-rs.md | 127 ++++++++++ packages/signals/README.md | 3 +- packages/signals/src/lib.rs | 2 +- packages/ssr/README-docs-rs.md | 105 ++++++++ packages/ssr/README.md | 10 +- packages/ssr/src/lib.rs | 2 +- packages/stores/README-docs-rs.md | 64 +++++ packages/stores/README.md | 3 +- packages/stores/src/lib.rs | 2 +- packages/web/README-docs-rs.md | 43 ++++ packages/web/README.md | 22 +- packages/web/src/lib.rs | 3 +- 92 files changed, 2343 insertions(+), 279 deletions(-) create mode 100644 packages/autofmt/README-docs-rs.md create mode 100644 packages/check/README-docs-rs.md create mode 100644 packages/cli-config/README-docs-rs.md create mode 100644 packages/cli/README-docs-rs.md create mode 100644 packages/config-macro/README-docs-rs.md create mode 100644 packages/config-macros/README-docs-rs.md create mode 100644 packages/const-serialize/README-docs-rs.md create mode 100644 packages/core-macro/README-docs-rs.md create mode 100644 packages/core/README-docs-rs.md create mode 100644 packages/crates-io-readme/Cargo.toml create mode 100644 packages/crates-io-readme/src/main.rs create mode 100644 packages/depinfo/README-docs-rs.md create mode 100644 packages/desktop/README-docs-rs.md create mode 100644 packages/dioxus/README-docs-rs.md create mode 100644 packages/fullstack-hooks/README-docs-rs.md create mode 100644 packages/fullstack-protocol/README-docs-rs.md create mode 100644 packages/fullstack/README-docs-rs.md create mode 100644 packages/generational-box/README-docs-rs.md create mode 100644 packages/hooks/README-docs-rs.md create mode 100644 packages/html/README-docs-rs.md create mode 100644 packages/interpreter/README-docs-rs.md create mode 100644 packages/liveview/README-docs-rs.md create mode 100644 packages/logger/README-docs-rs.md create mode 100644 packages/manganis/manganis-macro/README-docs-rs.md create mode 100644 packages/manganis/manganis/README-docs-rs.md create mode 100644 packages/router/README-docs-rs.md create mode 100644 packages/rsx-rosetta/README-docs-rs.md create mode 100644 packages/signals/README-docs-rs.md create mode 100644 packages/ssr/README-docs-rs.md create mode 100644 packages/stores/README-docs-rs.md create mode 100644 packages/web/README-docs-rs.md diff --git a/Cargo.lock b/Cargo.lock index 8074b12b17..06aeafae3d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4221,6 +4221,16 @@ dependencies = [ "libc", ] +[[package]] +name = "crates-io-readme" +version = "0.1.0" +dependencies = [ + "anyhow", + "pulldown-cmark", + "pulldown-cmark-to-cmark", + "walkdir", +] + [[package]] name = "crc" version = "2.1.0" @@ -12731,6 +12741,33 @@ dependencies = [ "syn 1.0.109", ] +[[package]] +name = "pulldown-cmark" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e8bbe1a966bd2f362681a44f6edce3c2310ac21e4d5067a6e7ec396297a6ea0" +dependencies = [ + "bitflags 2.9.1", + "memchr", + "pulldown-cmark-escape", + "unicase", +] + +[[package]] +name = "pulldown-cmark-escape" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae" + +[[package]] +name = "pulldown-cmark-to-cmark" +version = "21.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5b6a0769a491a08b31ea5c62494a8f144ee0987d86d670a8af4df1e1b7cde75" +dependencies = [ + "pulldown-cmark", +] + [[package]] name = "qoi" version = "0.4.1" diff --git a/Cargo.toml b/Cargo.toml index 06c12b87c9..f8d9512d07 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -97,6 +97,9 @@ members = [ "packages/subsecond/subsecond-tests/cross-tls-crate-dylib", "packages/subsecond/subsecond-tests/cross-tls-test", + # tools + "packages/crates-io-readme", + # Full project examples "example-projects/fullstack-hackernews", "example-projects/ecommerce-site", diff --git a/packages/autofmt/README-docs-rs.md b/packages/autofmt/README-docs-rs.md new file mode 100644 index 0000000000..4236eef150 --- /dev/null +++ b/packages/autofmt/README-docs-rs.md @@ -0,0 +1,43 @@ +# dioxus-autofmt + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-autofmt.svg +[crates-url]: https://crates.io/crates/dioxus-autofmt +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6) | +[API Docs](https://docs.rs/dioxus-autofmt/latest/dioxus_autofmt) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-autofmt` provides a pretty printer for the `rsx` syntax tree. + +This is done manually with a via set of formatting rules. The output is not guaranteed to be stable between minor versions of the crate as we might tweak the output. + +`dioxus-autofmt` provides an API to perform precision edits as well as just spit out a block of formatted RSX from any RSX syntax tree. This is used by the `rsx-rosetta` crate which can accept various input languages and output valid RSX. + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/autofmt/README.md b/packages/autofmt/README.md index 4236eef150..7c06b3b54b 100644 --- a/packages/autofmt/README.md +++ b/packages/autofmt/README.md @@ -1,3 +1,4 @@ + # dioxus-autofmt [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-autofmt.svg -[crates-url]: https://crates.io/crates/dioxus-autofmt -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6) | [API Docs](https://docs.rs/dioxus-autofmt/latest/dioxus_autofmt) | @@ -36,8 +28,16 @@ This is done manually with a via set of formatting rules. The output is not guar This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-autofmt.svg +[crates-url]: https://crates.io/crates/dioxus-autofmt +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/autofmt/src/lib.rs b/packages/autofmt/src/lib.rs index 553df27bb5..94f86cac1f 100644 --- a/packages/autofmt/src/lib.rs +++ b/packages/autofmt/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/check/README-docs-rs.md b/packages/check/README-docs-rs.md new file mode 100644 index 0000000000..e735e7d5c4 --- /dev/null +++ b/packages/check/README-docs-rs.md @@ -0,0 +1,39 @@ +# dioxus-check + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-autofmt.svg +[crates-url]: https://crates.io/crates/dioxus-check +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6) | +[API Docs](https://docs.rs/dioxus-check) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-check` analyzes Dioxus source code and reports errors and warnings. Primarily, it enforces the [Rules of Hooks](https://dioxuslabs.com/learn/0.6/reference/hooks#rules-of-hooks). + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/check/README.md b/packages/check/README.md index e735e7d5c4..f8c4ef3a01 100644 --- a/packages/check/README.md +++ b/packages/check/README.md @@ -1,3 +1,4 @@ + # dioxus-check [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-autofmt.svg -[crates-url]: https://crates.io/crates/dioxus-check -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6) | [API Docs](https://docs.rs/dioxus-check) | @@ -32,8 +24,16 @@ This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-autofmt.svg +[crates-url]: https://crates.io/crates/dioxus-check +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/check/src/lib.rs b/packages/check/src/lib.rs index 43a164514a..d05b9ef6a3 100644 --- a/packages/check/src/lib.rs +++ b/packages/check/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/cli-config/README-docs-rs.md b/packages/cli-config/README-docs-rs.md new file mode 100644 index 0000000000..ce337cb5ea --- /dev/null +++ b/packages/cli-config/README-docs-rs.md @@ -0,0 +1,53 @@ +
+ Build web, desktop, and mobile apps with a single codebase. +
+ +# Dioxus CLI configuration + +This crate exposes the various configuration options that the Dioxus CLI sets when running the +application during development. + +Note that these functions will return a different value when running under the CLI, so make sure +not to rely on them when running in a production environment. + +## Constants + +The various constants here are the names of the environment variables that the CLI sets. We recommend +using the functions in this crate to access the values of these environment variables indirectly. + +The CLI uses this crate and the associated constants to _set_ the environment variables, but as +a consumer of the CLI, you would want to read the values of these environment variables using +the provided functions. + +## Example Usage + +We recommend using the functions here to access the values of the environment variables set by the CLI. +For example, you might use the [`fullstack_address_or_localhost`] function to get the address that +the CLI is requesting the application to be served on. + +```rust, ignore +async fn launch_axum(app: axum::Router<()>) { +// Read the PORT and ADDR environment variables set by the CLI +let addr = dioxus_cli_config::fullstack_address_or_localhost(); + + // Bind to the address and serve the application + let listener = tokio::net::TcpListener::bind(&addr).await.unwrap(); + axum::serve(listener, app.into_make_service()) + .await + .unwrap(); + +} +``` + +## Stability + +The _values_ that these functions return are _not_ guaranteed to be stable between patch releases +of Dioxus. At any time, we might change the values that the CLI sets or the way that they are read. + +We also don't guarantee the stability of the env var names themselves. If you want to rely on a +particular env var, use the defined constants in your code. diff --git a/packages/cli-config/README.md b/packages/cli-config/README.md index e544837bdb..5f68ea068a 100644 --- a/packages/cli-config/README.md +++ b/packages/cli-config/README.md @@ -1,7 +1,54 @@ -# dioxus-cli-config + +
+ Build web, desktop, and mobile apps with a single codebase. +
-A crate that provides key/value names and types for configuring Dioxus applications at runtime. +# Dioxus CLI configuration -This crate exists for us to very cleanly define the exact fields we want to pass down to Dioxus applications at runtime but without exposing the entire config object. +This crate exposes the various configuration options that the Dioxus CLI sets when running the +application during development. -This leads to faster compile times, smaller binaries, and a clearer distinction between the config and the application. +Note that these functions will return a different value when running under the CLI, so make sure +not to rely on them when running in a production environment. + +## Constants + +The various constants here are the names of the environment variables that the CLI sets. We recommend +using the functions in this crate to access the values of these environment variables indirectly. + +The CLI uses this crate and the associated constants to _set_ the environment variables, but as +a consumer of the CLI, you would want to read the values of these environment variables using +the provided functions. + +## Example Usage + +We recommend using the functions here to access the values of the environment variables set by the CLI. +For example, you might use the [`fullstack_address_or_localhost`] function to get the address that +the CLI is requesting the application to be served on. + +```rust, ignore +async fn launch_axum(app: axum::Router<()>) { +// Read the PORT and ADDR environment variables set by the CLI +let addr = dioxus_cli_config::fullstack_address_or_localhost(); + + // Bind to the address and serve the application + let listener = tokio::net::TcpListener::bind(&addr).await.unwrap(); + axum::serve(listener, app.into_make_service()) + .await + .unwrap(); + +} +``` + +## Stability + +The _values_ that these functions return are _not_ guaranteed to be stable between patch releases +of Dioxus. At any time, we might change the values that the CLI sets or the way that they are read. + +We also don't guarantee the stability of the env var names themselves. If you want to rely on a +particular env var, use the defined constants in your code. \ No newline at end of file diff --git a/packages/cli-config/src/lib.rs b/packages/cli-config/src/lib.rs index e3092266a0..57be723db2 100644 --- a/packages/cli-config/src/lib.rs +++ b/packages/cli-config/src/lib.rs @@ -1,55 +1,4 @@ -//!
-//! Build web, desktop, and mobile apps with a single codebase. -//!
-//! -//! # Dioxus CLI configuration -//! -//! This crate exposes the various configuration options that the Dioxus CLI sets when running the -//! application during development. -//! -//! Note that these functions will return a different value when running under the CLI, so make sure -//! not to rely on them when running in a production environment. -//! -//! ## Constants -//! -//! The various constants here are the names of the environment variables that the CLI sets. We recommend -//! using the functions in this crate to access the values of these environment variables indirectly. -//! -//! The CLI uses this crate and the associated constants to *set* the environment variables, but as -//! a consumer of the CLI, you would want to read the values of these environment variables using -//! the provided functions. -//! -//! ## Example Usage -//! -//! We recommend using the functions here to access the values of the environment variables set by the CLI. -//! For example, you might use the [`fullstack_address_or_localhost`] function to get the address that -//! the CLI is requesting the application to be served on. -//! -//! ```rust, ignore -//! async fn launch_axum(app: axum::Router<()>) { -//! // Read the PORT and ADDR environment variables set by the CLI -//! let addr = dioxus_cli_config::fullstack_address_or_localhost(); -//! -//! // Bind to the address and serve the application -//! let listener = tokio::net::TcpListener::bind(&addr).await.unwrap(); -//! axum::serve(listener, app.into_make_service()) -//! .await -//! .unwrap(); -//! } -//! ``` -//! -//! ## Stability -//! -//! The *values* that these functions return are *not* guaranteed to be stable between patch releases -//! of Dioxus. At any time, we might change the values that the CLI sets or the way that they are read. -//! -//! We also don't guarantee the stability of the env var names themselves. If you want to rely on a -//! particular env var, use the defined constants in your code. +#![doc = include_str!("../README-docs-rs.md")] use std::{ net::{IpAddr, Ipv4Addr, SocketAddr}, diff --git a/packages/cli/README-docs-rs.md b/packages/cli/README-docs-rs.md new file mode 100644 index 0000000000..5913d9f2c3 --- /dev/null +++ b/packages/cli/README-docs-rs.md @@ -0,0 +1,68 @@ +
+

📦✨ Dioxus CLI

+

Tooling to supercharge Dioxus projects

+
+ +The **dioxus-cli** (inspired by wasm-pack and webpack) is a tool for getting Dioxus projects up and running. +It handles building, bundling, development and publishing to simplify development. + +## Installation + +### Install the stable version (recommended) + +```shell +cargo install dioxus-cli +``` + +### Install the latest development build through git + +To get the latest bug fixes and features, you can install the development version from git. +However, this is not fully tested. +That means you're probably going to have more bugs despite having the latest bug fixes. + +```shell +cargo install --git https://github.com/DioxusLabs/dioxus dioxus-cli +``` + +This will download the CLI from the master branch, +and install it in Cargo's global binary directory (`~/.cargo/bin/` by default). + +### Install from local folder +Note: The CLI will fail to build projects in debug profile. This is currently under investigation. +```shell +cargo install --path . +``` + +## Get started + +Use `dx new` to initialize a new Dioxus project. +It will be cloned from the [dioxus-template](https://github.com/DioxusLabs/dioxus-template) repository. + +Alternatively, you can specify the template path: + +```shell +dx new --template gh:dioxuslabs/dioxus-template +``` + +Run `dx --help` for a list of all the available commands. +Furthermore, you can run `dx --help` to get help with a specific command. + +## Dioxus config file + +You can use the `Dioxus.toml` file for further configuration. +Some fields are mandatory, but the CLI tool will tell you which ones are missing. +You can create a `Dioxus.toml` with all fields already set using `dx config init project-name`, +or you can use this bare-bones template (only mandatory fields) to get started: + +```toml +[application] +name = "project-name" +# Currently supported platforms: web, desktop +default_platform = "web" + +[web.app] +title = "Hello" + +[web.resource.dev] +``` + diff --git a/packages/cli/README.md b/packages/cli/README.md index 5913d9f2c3..4e23bf760c 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,3 +1,4 @@ +

📦✨ Dioxus CLI

Tooling to supercharge Dioxus projects

@@ -28,7 +29,9 @@ This will download the CLI from the master branch, and install it in Cargo's global binary directory (`~/.cargo/bin/` by default). ### Install from local folder + Note: The CLI will fail to build projects in debug profile. This is currently under investigation. + ```shell cargo install --path . ``` @@ -64,5 +67,4 @@ default_platform = "web" title = "Hello" [web.resource.dev] -``` - +``` \ No newline at end of file diff --git a/packages/cli/src/main.rs b/packages/cli/src/main.rs index 9184e86e5c..f724960997 100644 --- a/packages/cli/src/main.rs +++ b/packages/cli/src/main.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![cfg_attr(docsrs, feature(doc_cfg))] diff --git a/packages/config-macro/README-docs-rs.md b/packages/config-macro/README-docs-rs.md new file mode 100644 index 0000000000..39ca7e98df --- /dev/null +++ b/packages/config-macro/README-docs-rs.md @@ -0,0 +1,39 @@ +# dioxus-config-macro + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-config-macro.svg +[crates-url]: https://crates.io/crates/dioxus-config-macro +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guide](https://dioxuslabs.com/learn/0.6) | +[API Docs](https://docs.rs/dioxus-config-macro/latest/dioxus_config_macro/) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-config-macro` provides a handful of helpful macros to make it easier to work with optional sections of the launch builder. + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/config-macro/README.md b/packages/config-macro/README.md index 39ca7e98df..94db63647e 100644 --- a/packages/config-macro/README.md +++ b/packages/config-macro/README.md @@ -1,3 +1,4 @@ + # dioxus-config-macro [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-config-macro.svg -[crates-url]: https://crates.io/crates/dioxus-config-macro -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guide](https://dioxuslabs.com/learn/0.6) | [API Docs](https://docs.rs/dioxus-config-macro/latest/dioxus_config_macro/) | @@ -32,8 +24,16 @@ This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-config-macro.svg +[crates-url]: https://crates.io/crates/dioxus-config-macro +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/config-macro/src/lib.rs b/packages/config-macro/src/lib.rs index d54cb84b6b..3d4241e411 100644 --- a/packages/config-macro/src/lib.rs +++ b/packages/config-macro/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/config-macros/README-docs-rs.md b/packages/config-macros/README-docs-rs.md new file mode 100644 index 0000000000..8384525d56 --- /dev/null +++ b/packages/config-macros/README-docs-rs.md @@ -0,0 +1,15 @@ +# Dioxus Config Macros + +These macros are used internally by codegen and are not intended for general use. + +Dioxus will export its feature flags into this crate, allowing downstream codegen to use them under the "dioxus" namespace. + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/config-macros/README.md b/packages/config-macros/README.md index 8384525d56..c4dedc8092 100644 --- a/packages/config-macros/README.md +++ b/packages/config-macros/README.md @@ -1,3 +1,4 @@ + # Dioxus Config Macros These macros are used internally by codegen and are not intended for general use. @@ -8,8 +9,8 @@ Dioxus will export its feature flags into this crate, allowing downstream codege This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/config-macros/src/lib.rs b/packages/config-macros/src/lib.rs index a7fddac1f0..157368cace 100644 --- a/packages/config-macros/src/lib.rs +++ b/packages/config-macros/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README-docs-rs.md")] + /// A macro for deciding whether or not to split the wasm bundle. /// Used by the internal router-macro code. The contents here are considered to be semver exempt. /// diff --git a/packages/const-serialize/README-docs-rs.md b/packages/const-serialize/README-docs-rs.md new file mode 100644 index 0000000000..dfa66de631 --- /dev/null +++ b/packages/const-serialize/README-docs-rs.md @@ -0,0 +1,57 @@ +A rust serialization library that works in const with complex(ish) types like enums, nested structs and arrays. Const rust does not have an allocator, so this library cannot work in a cross architecture environment with Vecs, slices or strings. + +```rust +use const_serialize::{deserialize_const, serialize_const, serialize_eq, ConstVec, SerializeConst}; +#[derive(Clone, Copy, Debug, PartialEq, SerializeConst)] +struct Struct { + a: u32, + b: u8, + c: u32, + d: Enum, +} + +#[derive(Clone, Copy, Debug, PartialEq, SerializeConst)] +#[repr(C, u8)] +enum Enum { + A { one: u32, two: u16 }, + B { one: u8, two: u16 } = 15, +} + +const { + let data = [Struct { + a: 0x11111111, + b: 0x22, + c: 0x33333333, + d: Enum::A { + one: 0x44444444, + two: 0x5555, + }, + }; 3]; + let mut buf = ConstVec::new(); + buf = serialize_const(&data, buf); + let buf = buf.read(); + let (buf, deserialized) = match deserialize_const!([Struct; 3], buf) { + Some(data) => data, + None => panic!("data mismatch"), + }; + if !serialize_eq(&data, &deserialized) { + panic!("data mismatch"); + } +} +``` + +## How it works + +`const-serialize` relies heavily on well defined layouts for the types you want to serialize. The serialization format is the linear sequence of unaligned bytes stored in the order of the fields, items or variants of the type. Numbers are stored in little endian order. + +In order to support complex nested types, serialization is done using a trait. Since functions in traits cannot be const, `const-serialize` uses a macro to generate constant associated items that describe the memory layout of the type. That layout is then used to read all of the bytes in the type into the serialized buffer. + +The deserialization is done in a similar way, but the layout is used to write the bytes from the serialized buffer into the type. + +The rust [nomicon](https://doc.rust-lang.org/nomicon/data.html) defines the memory layout of different types. It is used as a reference for the layout of the types implemented in `const-serialize`. + +## Limitations + +- Only constant sized types are supported. This means that you can't serialize a type like `Vec`. These types are difficult to create in const contexts in general +- Only types with a well defined memory layout are supported (see and ). `repr(Rust)` enums don't have a well defined layout, so they are not supported. `repr(C, u8)` enums can be used instead +- Const rust does not support mutable references or points, so this crate leans heavily on function data structures for data processing. diff --git a/packages/const-serialize/README.md b/packages/const-serialize/README.md index dfa66de631..bc5a282648 100644 --- a/packages/const-serialize/README.md +++ b/packages/const-serialize/README.md @@ -1,3 +1,4 @@ + A rust serialization library that works in const with complex(ish) types like enums, nested structs and arrays. Const rust does not have an allocator, so this library cannot work in a cross architecture environment with Vecs, slices or strings. ```rust @@ -54,4 +55,4 @@ The rust [nomicon](https://doc.rust-lang.org/nomicon/data.html) defines the memo - Only constant sized types are supported. This means that you can't serialize a type like `Vec`. These types are difficult to create in const contexts in general - Only types with a well defined memory layout are supported (see and ). `repr(Rust)` enums don't have a well defined layout, so they are not supported. `repr(C, u8)` enums can be used instead -- Const rust does not support mutable references or points, so this crate leans heavily on function data structures for data processing. +- Const rust does not support mutable references or points, so this crate leans heavily on function data structures for data processing. \ No newline at end of file diff --git a/packages/const-serialize/src/lib.rs b/packages/const-serialize/src/lib.rs index ac27500d06..e6ef49a374 100644 --- a/packages/const-serialize/src/lib.rs +++ b/packages/const-serialize/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![warn(missing_docs)] use std::{char, mem::MaybeUninit}; diff --git a/packages/core-macro/README-docs-rs.md b/packages/core-macro/README-docs-rs.md new file mode 100644 index 0000000000..7a7d1639a6 --- /dev/null +++ b/packages/core-macro/README-docs-rs.md @@ -0,0 +1,46 @@ +# dioxus-core-macro + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-core-macro.svg +[crates-url]: https://crates.io/crates/dioxus-core-macro +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6) | +[API Docs](https://docs.rs/dioxus-core-macro/latest/dioxus_core_macro) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-core-macro` provides a handful of helpful macros used by the `dioxus` crate. These include: + +- The `rsx!` macro that underpins templates and node creation. +- The `component` attribute macro denotes a function as a Dioxus component. Currently, this: + - Transforms function arguments into an auto-derived struct. + - Ensures that your component name uses PascalCase. + - Probably more stuff in the future. This macro allows us to have a way of distinguishing functions and components, which can be quite handy. +- The `format_args_f` macro which allows f-string formatting with support for expressions. + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/core-macro/README.md b/packages/core-macro/README.md index 7a7d1639a6..cb2b95c95b 100644 --- a/packages/core-macro/README.md +++ b/packages/core-macro/README.md @@ -1,3 +1,4 @@ + # dioxus-core-macro [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-core-macro.svg -[crates-url]: https://crates.io/crates/dioxus-core-macro -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6) | [API Docs](https://docs.rs/dioxus-core-macro/latest/dioxus_core_macro) | @@ -39,8 +31,16 @@ This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-core-macro.svg +[crates-url]: https://crates.io/crates/dioxus-core-macro +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/core-macro/src/lib.rs b/packages/core-macro/src/lib.rs index b65351cd66..6a8cd71ae4 100644 --- a/packages/core-macro/src/lib.rs +++ b/packages/core-macro/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/core/README-docs-rs.md b/packages/core/README-docs-rs.md new file mode 100644 index 0000000000..ae568c14da --- /dev/null +++ b/packages/core/README-docs-rs.md @@ -0,0 +1,99 @@ +# dioxus-core + +`dioxus-core` provides a fast and featureful VirtualDom implementation for Rust. + +```rust, no_run +# tokio::runtime::Runtime::new().unwrap().block_on(async { +use dioxus_core::{VirtualDom, Event, Element, Mutations, VNode, ElementId}; + +let mut vdom = VirtualDom::new(app); +let real_dom = SomeRenderer::new(); + +loop { + tokio::select! { + evt = real_dom.event() => { + let evt = Event::new(evt, true); + vdom.runtime().handle_event("onclick", evt, ElementId(0)) + }, + _ = vdom.wait_for_work() => {} + } + vdom.render_immediate(&mut real_dom.apply()) +} + +# fn app() -> Element { VNode::empty() } +# struct SomeRenderer; impl SomeRenderer { fn new() -> SomeRenderer { SomeRenderer } async fn event(&self) -> std::rc::Rc { unimplemented!() } fn apply(&self) -> Mutations { Mutations::default() } } +# }); +``` + +## Features + +A virtualdom is an efficient and flexible tree data structure that allows you to manage state for a graphical user interface. The Dioxus VirtualDom is perhaps the most fully-featured virtualdom implementation in Rust and powers renderers running across Web, Desktop, Mobile, SSR, TUI, LiveView, and more. When you use the Dioxus VirtualDom, you immediately enable users of your renderer to leverage the wide ecosystem of Dioxus components, hooks, and associated tooling. + +Some features of `dioxus-core` include: + +- UI components are just functions +- State is provided by hooks +- Deep integration with async +- Strong focus on performance +- Integrated hotreloading support +- Extensible system for UI elements and their attributes + +If you are just starting, check out the Guides first. + +## Understanding the implementation + +`dioxus-core` is designed to be a lightweight crate that. It exposes a number of flexible primitives without being deeply concerned about the intracices of state management itself. We provide a number of useful abstractions built on these primitives in the `dioxus-hooks` crate as well as the `dioxus-signals` crate. + +The important abstractions to understand are: + +- The [`VirtualDom`] +- The [`Component`] and its [`Properties`] +- Handling events +- Working with async +- Suspense + +## Usage + +The `dioxus` crate exports the `rsx` macro which transforms a helpful, simpler syntax of Rust. + +First, start with your app: + +```rust +# use dioxus::dioxus_core::{Mutations, VirtualDom}; +use dioxus::prelude::*; + +// First, declare a root component +fn app() -> Element { + rsx! { + div { "hello world" } + } +} + +fn main() { + // Next, create a new VirtualDom using this app as the root component. + let mut dom = VirtualDom::new(app); + + // The initial render of the dom will generate a stream of edits for the real dom to apply + let mutations = dom.rebuild_to_vec(); +} +``` + +## Contributing + +- Check out the website [section on contributing](https://dioxuslabs.com/learn/0.6/contributing). +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- [Join](https://discord.gg/XgGxMSkvUM) the discord and ask questions! + + + + + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you, shall be licensed as MIT, without any additional +terms or conditions. diff --git a/packages/core/README.md b/packages/core/README.md index ae568c14da..15dc87cc32 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,9 +1,9 @@ + # dioxus-core `dioxus-core` provides a fast and featureful VirtualDom implementation for Rust. ```rust, no_run -# tokio::runtime::Runtime::new().unwrap().block_on(async { use dioxus_core::{VirtualDom, Event, Element, Mutations, VNode, ElementId}; let mut vdom = VirtualDom::new(app); @@ -19,10 +19,6 @@ loop { } vdom.render_immediate(&mut real_dom.apply()) } - -# fn app() -> Element { VNode::empty() } -# struct SomeRenderer; impl SomeRenderer { fn new() -> SomeRenderer { SomeRenderer } async fn event(&self) -> std::rc::Rc { unimplemented!() } fn apply(&self) -> Mutations { Mutations::default() } } -# }); ``` ## Features @@ -59,7 +55,6 @@ The `dioxus` crate exports the `rsx` macro which transforms a helpful, simpler s First, start with your app: ```rust -# use dioxus::dioxus_core::{Mutations, VirtualDom}; use dioxus::prelude::*; // First, declare a root component @@ -92,8 +87,8 @@ fn main() { This project is licensed under the [MIT license]. -[mit license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you, shall be licensed as MIT, without any additional terms or conditions. + +[MIT license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-MIT \ No newline at end of file diff --git a/packages/core/src/lib.rs b/packages/core/src/lib.rs index c093003e0e..7914f676ae 100644 --- a/packages/core/src/lib.rs +++ b/packages/core/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![warn(missing_docs)] diff --git a/packages/crates-io-readme/Cargo.toml b/packages/crates-io-readme/Cargo.toml new file mode 100644 index 0000000000..5ce7be865c --- /dev/null +++ b/packages/crates-io-readme/Cargo.toml @@ -0,0 +1,11 @@ +[package] +name = "crates-io-readme" +version = "0.1.0" +edition = "2024" +publish = false + +[dependencies] +pulldown-cmark = { version = "0.13.0", default-features = false, features = ["simd"] } +anyhow = "1.0" +walkdir = "2.5" +pulldown-cmark-to-cmark = "21.0.0" diff --git a/packages/crates-io-readme/src/main.rs b/packages/crates-io-readme/src/main.rs new file mode 100644 index 0000000000..4be68ba0f5 --- /dev/null +++ b/packages/crates-io-readme/src/main.rs @@ -0,0 +1,105 @@ +/// We use the readme as the frontpage of the docs.rs for most crates, but Crates.io and github render code blocks slightly different from docs.rs. +/// This CLI searches through the current directory for markdown files that have the `-docs-rs` suffix and transforms them to remove lines that start with `# ` in fenced rust code blocks. +/// +/// # Usage +/// +/// Run this command in the root of the workspace: +/// ```bash +/// cargo run --package crates-io-readme +/// ``` +use anyhow::{Context, Result}; +use pulldown_cmark::{CodeBlockKind, Event, Tag, TagEnd}; +use std::fs; +use std::path::Path; +use walkdir::WalkDir; + +fn main() -> Result<()> { + let current_dir = std::env::current_dir()?; + + // Process all markdown files in the current directory + for entry in WalkDir::new(¤t_dir) { + let entry = entry?; + let path = entry.path(); + + if path.extension().and_then(|s| s.to_str()) == Some("md") { + let stem_name = path + .file_stem() + .and_then(|s| s.to_str()) + .unwrap_or_default(); + if let Some(base_name) = stem_name.strip_suffix("-docs-rs") { + process_markdown_file(&path, &path.with_file_name(base_name).with_extension("md"))?; + } + } + } + + println!("✅ Transformation complete!"); + Ok(()) +} + +fn process_markdown_file(path: &Path, output_path: &Path) -> Result<()> { + // Read the markdown file + let content = fs::read_to_string(path) + .with_context(|| format!("Failed to read file: {}", path.display()))?; + + let source_file_name = path + .file_name() + .and_then(|s| s.to_str()) + .unwrap_or_default(); + + // Transform the markdown content + let mut output_writer = format!( + "\n" + ); + transform_markdown_to(&content, &mut output_writer)?; + + // Write the transformed content to the output file + fs::write(output_path, output_writer) + .with_context(|| format!("Failed to write file: {}", output_path.display()))?; + + println!(" ✅ Transformed: {}", path.display()); + Ok(()) +} + +fn transform_markdown_to(content: &str, writer: impl std::fmt::Write) -> Result<()> { + let parser = pulldown_cmark::Parser::new(content); + let iterator = pulldown_cmark::TextMergeWithOffset::new(parser.into_offset_iter()); + + let mut in_rust_block = false; + let iterator = iterator.map(|(event, offset)| match &event { + Event::Start(Tag::CodeBlock(info)) => { + // docs.rs strips lines in rust blocks that start with `# ` + if let CodeBlockKind::Fenced(lang) = info { + let is_rust = + lang.starts_with("rust") || lang.starts_with("rs") || lang.starts_with("rsx"); + in_rust_block = is_rust; + } + (event, Some(offset)) + } + Event::End(TagEnd::CodeBlock) => { + in_rust_block = false; + (event, Some(offset)) + } + Event::Text(text) if in_rust_block => { + // Strip lines that start with `# ` + let stripped_text = text + .lines() + .filter(|line| !line.starts_with("# ")) + .collect::>() + .join("\n"); + (Event::Text(stripped_text.into()), None) + } + _ => (event, Some(offset)), + }); + + let options = pulldown_cmark_to_cmark::Options { + code_block_token_count: 3, + list_token: '-', + emphasis_token: '_', + ..Default::default() + }; + pulldown_cmark_to_cmark::cmark_with_source_range_and_options( + iterator, content, writer, options, + )?; + + Ok(()) +} diff --git a/packages/depinfo/README-docs-rs.md b/packages/depinfo/README-docs-rs.md new file mode 100644 index 0000000000..cc9bebc996 --- /dev/null +++ b/packages/depinfo/README-docs-rs.md @@ -0,0 +1,14 @@ +# Rustc Dep-Info Parser + +This crate parses the output of rustc's `.d` dep-info file. It is used by the hot-reloading engine and other libraries to provide higher quality dependency analysis for the user's project. + +## License + +This project is licensed under either the [MIT license] or the [Apache-2 License]. + +[apache-2 license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-APACHE +[mit license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you, shall be licensed as MIT or Apache-2, without any additional +terms or conditions. diff --git a/packages/depinfo/README.md b/packages/depinfo/README.md index cc9bebc996..65a47c5314 100644 --- a/packages/depinfo/README.md +++ b/packages/depinfo/README.md @@ -1,3 +1,4 @@ + # Rustc Dep-Info Parser This crate parses the output of rustc's `.d` dep-info file. It is used by the hot-reloading engine and other libraries to provide higher quality dependency analysis for the user's project. @@ -6,9 +7,9 @@ This crate parses the output of rustc's `.d` dep-info file. It is used by the ho This project is licensed under either the [MIT license] or the [Apache-2 License]. -[apache-2 license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-APACHE -[mit license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you, shall be licensed as MIT or Apache-2, without any additional terms or conditions. + +[MIT license]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-MIT +[Apache-2 License]: https://github.com/DioxusLabs/dioxus/blob/master/LICENSE-APACHE \ No newline at end of file diff --git a/packages/depinfo/src/lib.rs b/packages/depinfo/src/lib.rs index c5ef6e9fe1..b13be17826 100644 --- a/packages/depinfo/src/lib.rs +++ b/packages/depinfo/src/lib.rs @@ -1,7 +1,4 @@ -//! Parse the output of rustc's `.d` dep-info file. -//! -//! Used by the hot-reloading engine and other libraries to provide higher quality dependency analysis -//! for the user's project. +#![doc = include_str!("../README-docs-rs.md")] use std::path::{Path, PathBuf}; diff --git a/packages/desktop/README-docs-rs.md b/packages/desktop/README-docs-rs.md new file mode 100644 index 0000000000..cebf39cbca --- /dev/null +++ b/packages/desktop/README-docs-rs.md @@ -0,0 +1,51 @@ +# Dioxus Desktop (webview) + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-desktop.svg +[crates-url]: https://crates.io/crates/dioxus-desktop +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6) | +[API Docs](https://docs.rs/dioxus-desktop/latest/dioxus_desktop) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-desktop` provides a webview-based desktop renderer for the Dioxus VirtualDom. + +This requires that webview is installed on the target system. WebView is installed by default on macOS and iOS devices, but might not come preinstalled on Windows or Linux devices. To fix these issues, follow the [instructions in the guide](guide-url). + +[guide-url]: https://dioxuslabs.com/learn/0.6/getting_started + +## Features + +- Simple, one-line launch for desktop apps +- Dioxus VirtualDom running on a native thread +- Full HTML/CSS support via `wry` and `tao` +- Exposed `window` and `Proxy` types from tao for direct window manipulation +- Helpful hooks for accessing the window, WebView, and running javascript. + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/desktop/README.md b/packages/desktop/README.md index cebf39cbca..5c7bbaa2dc 100644 --- a/packages/desktop/README.md +++ b/packages/desktop/README.md @@ -1,3 +1,4 @@ + # Dioxus Desktop (webview) [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-desktop.svg -[crates-url]: https://crates.io/crates/dioxus-desktop -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6) | [API Docs](https://docs.rs/dioxus-desktop/latest/dioxus_desktop) | @@ -25,8 +17,6 @@ This requires that webview is installed on the target system. WebView is installed by default on macOS and iOS devices, but might not come preinstalled on Windows or Linux devices. To fix these issues, follow the [instructions in the guide](guide-url). -[guide-url]: https://dioxuslabs.com/learn/0.6/getting_started - ## Features - Simple, one-line launch for desktop apps @@ -44,8 +34,16 @@ This requires that webview is installed on the target system. WebView is install This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-desktop.svg +[crates-url]: https://crates.io/crates/dioxus-desktop +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/desktop/src/lib.rs b/packages/desktop/src/lib.rs index d4051bf4be..aa8f4e882d 100644 --- a/packages/desktop/src/lib.rs +++ b/packages/desktop/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("readme.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![deny(missing_docs)] diff --git a/packages/dioxus/README-docs-rs.md b/packages/dioxus/README-docs-rs.md new file mode 100644 index 0000000000..b0a8eec427 --- /dev/null +++ b/packages/dioxus/README-docs-rs.md @@ -0,0 +1,229 @@ + + +--- + +Dioxus is a framework for building cross-platform apps in Rust. With one codebase, you can build web, desktop, and mobile apps with fullstack server functions. Dioxus is designed to be easy to learn for developers familiar with web technologies like HTML, CSS, and JavaScript. + +
+ App with dioxus +
+ +## At a glance + +Dioxus is crossplatform app framework that empowers developer to build beautiful, fast, type-safe apps with Rust. By default, Dioxus apps are declared with HTML and CSS. Dioxus includes a number of useful features: + +- Hotreloading of RSX markup and assets +- Interactive CLI with logging, project templates, linting, and more +- Integrated bundler for deploying to the web, macOS, Linux, and Windows +- Support for modern web features like SSR, Hydration, and HTML streaming +- Direct access to system APIs through JNI (Android), CoreFoundation (Apple), and web-sys (web) +- Type-safe application routing and server functions + +## Quick start + +To get started with Dioxus, you'll want to grab the dioxus-cli tool: `dx`. We distribute `dx` with `cargo-binstall` - if you already have binstall skip this step. + +```shell +# skip if you already have cargo-binstall +cargo install cargo-binstall + +# install the precompiled `dx` tool +cargo binstall dioxus-cli + +# create a new app, following the template +dx new my-app && cd my-app + +# and then serve! +dx serve --desktop +``` + +## Your first app + +All Dioxus apps are built by composing functions return an `Element`. + +To launch an app, we use the `launch` method. In the launch function, we pass the app's root `Component`. + +```rust, no_run +use dioxus::prelude::*; + +fn main() { + dioxus::launch(App); +} + +// The #[component] attribute streamlines component creation. +// It's not required, but highly recommended. It will lint incorrect component definitions and help you create props structs. +#[component] +fn App() -> Element { + rsx! { "hello world!" } +} +``` + +## Elements & your first component + +You can use the `rsx!` macro to create elements with a jsx-like syntax. +Any element in `rsx!` can have attributes, listeners, and children. For +consistency, we force all attributes and listeners to be listed _before_ +children. + +```rust, no_run +# use dioxus::prelude::*; +let value = "123"; + +rsx! { + div { + class: "my-class {value}", // <--- attribute + onclick: move |_| println!("clicked!"), // <--- listener + h1 { "hello world" } // <--- child + } +}; +``` + +The `rsx!` macro accepts attributes in "struct form". Any rust expression contained within curly braces that implements [`IntoDynNode`](dioxus_core::IntoDynNode) will be parsed as a child. We make two exceptions: both `for` loops and `if` statements are parsed where their body is parsed as a rsx nodes. + +```rust, no_run +# use dioxus::prelude::*; +rsx! { + div { + for _ in 0..10 { + span { "hello world" } + } + } +}; +``` + +Putting everything together, we can write a simple component that renders a list of +elements: + +```rust, no_run +# use dioxus::prelude::*; +#[component] +fn App() -> Element { + let name = "dave"; + rsx! { + h1 { "Hello, {name}!" } + div { class: "my-class", id: "my-id", + for i in 0..5 { + div { "FizzBuzz: {i}" } + } + } + } +} +``` + +## Components + +We can compose these function components to build a complex app. Each new component takes some Properties. For components with no explicit properties, we can omit the type altogether. + +In Dioxus, all properties are memoized by default with `Clone` and `PartialEq`. For props you can't clone, simply wrap the fields in a [`ReadSignal`](dioxus_signals::ReadSignal) and Dioxus will handle converting types for you. + +```rust, no_run +# use dioxus::prelude::*; +# #[component] fn Header(title: String, color: String) -> Element { todo!() } +#[component] +fn App() -> Element { + rsx! { + Header { + title: "My App", + color: "red", + } + } +} +``` + +The `#[component]` macro will help us automatically create a props struct for our component: + +```rust, no_run +# use dioxus::prelude::*; +// The component macro turns the arguments for our function into named fields we can pass in to the component in rsx +#[component] +fn Header(title: String, color: String) -> Element { + rsx! { + div { + background_color: "{color}", + h1 { "{title}" } + } + } +} +``` + +> You can read more about props in the [reference](https://dioxuslabs.com/learn/0.6/reference/component_props). + +## Hooks + +While components are reusable forms of UI elements, hooks are reusable forms of logic. Hooks provide a way of retrieving state from Dioxus' internal `Scope` and using +it to render UI elements. + +By convention, all hooks are functions that should start with `use_`. We can use hooks to define the state and modify it from within listeners. + +```rust, no_run +# use dioxus::prelude::*; +#[component] +fn App() -> Element { + // The use signal hook runs once when the component is created and then returns the current value every run after the first + let name = use_signal(|| "world"); + + rsx! { "hello {name}!" } +} +``` + +Hooks are sensitive to how they are used. To use hooks, you must abide by the ["rules of hooks"](https://dioxuslabs.com/learn/0.6/reference/hooks#rules-of-hooks): + +- Hooks can only be called in the body of a component or another hook. Not inside of another expression like a loop, conditional or function call. +- Hooks should start with "use\_" + +Hooks let us add a field of state to our component without declaring an explicit state struct. However, this means we need to "load" the struct in the right order. If that order is wrong, then the hook will pick the wrong state and panic. + +Dioxus includes many built-in hooks that you can use in your components. If those hooks don't fit your use case, you can also extend Dioxus with custom hooks. + +## Putting it all together + +Using components, rsx, and hooks, we can build a simple app. + +```rust, no_run +use dioxus::prelude::*; + +fn main() { + dioxus::launch(App); +} + +#[component] +fn App() -> Element { + let mut count = use_signal(|| 0); + + rsx! { + div { "Count: {count}" } + button { onclick: move |_| count += 1, "Increment" } + button { onclick: move |_| count -= 1, "Decrement" } + } +} +``` + +## Conclusion + +This overview doesn't cover everything. Make sure to check out the [tutorial](https://dioxuslabs.com/learn/0.6/guide) and [guides](https://dioxuslabs.com/learn/0.6/guides) on the official +website for more details. + +Beyond this overview, Dioxus supports: + +- Server-side rendering +- Concurrent rendering (with async support) +- Web/Desktop/Mobile support +- Pre-rendering and hydration +- Fragments, and Suspense +- Inline-styles +- Custom event handlers +- Custom elements +- Basic fine-grained reactivity (IE SolidJS/Svelte) +- and more! + +Build cool things ✌️ diff --git a/packages/dioxus/README.md b/packages/dioxus/README.md index b0a8eec427..2a086f4cbc 100644 --- a/packages/dioxus/README.md +++ b/packages/dioxus/README.md @@ -1,3 +1,4 @@ +
Element { let name = "dave"; @@ -127,8 +125,6 @@ We can compose these function components to build a complex app. Each new compon In Dioxus, all properties are memoized by default with `Clone` and `PartialEq`. For props you can't clone, simply wrap the fields in a [`ReadSignal`](dioxus_signals::ReadSignal) and Dioxus will handle converting types for you. ```rust, no_run -# use dioxus::prelude::*; -# #[component] fn Header(title: String, color: String) -> Element { todo!() } #[component] fn App() -> Element { rsx! { @@ -143,7 +139,6 @@ fn App() -> Element { The `#[component]` macro will help us automatically create a props struct for our component: ```rust, no_run -# use dioxus::prelude::*; // The component macro turns the arguments for our function into named fields we can pass in to the component in rsx #[component] fn Header(title: String, color: String) -> Element { @@ -156,7 +151,8 @@ fn Header(title: String, color: String) -> Element { } ``` -> You can read more about props in the [reference](https://dioxuslabs.com/learn/0.6/reference/component_props). + > + > You can read more about props in the [reference](https://dioxuslabs.com/learn/0.6/reference/component_props). ## Hooks @@ -166,7 +162,6 @@ it to render UI elements. By convention, all hooks are functions that should start with `use_`. We can use hooks to define the state and modify it from within listeners. ```rust, no_run -# use dioxus::prelude::*; #[component] fn App() -> Element { // The use signal hook runs once when the component is created and then returns the current value every run after the first @@ -179,7 +174,7 @@ fn App() -> Element { Hooks are sensitive to how they are used. To use hooks, you must abide by the ["rules of hooks"](https://dioxuslabs.com/learn/0.6/reference/hooks#rules-of-hooks): - Hooks can only be called in the body of a component or another hook. Not inside of another expression like a loop, conditional or function call. -- Hooks should start with "use\_" +- Hooks should start with "use_" Hooks let us add a field of state to our component without declaring an explicit state struct. However, this means we need to "load" the struct in the right order. If that order is wrong, then the hook will pick the wrong state and panic. @@ -226,4 +221,4 @@ Beyond this overview, Dioxus supports: - Basic fine-grained reactivity (IE SolidJS/Svelte) - and more! -Build cool things ✌️ +Build cool things ✌️ \ No newline at end of file diff --git a/packages/dioxus/src/lib.rs b/packages/dioxus/src/lib.rs index 9a200476f6..518ddddd78 100644 --- a/packages/dioxus/src/lib.rs +++ b/packages/dioxus/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] //! //! ## Dioxus Crate Features //! diff --git a/packages/fullstack-hooks/README-docs-rs.md b/packages/fullstack-hooks/README-docs-rs.md new file mode 100644 index 0000000000..f025fd32c3 --- /dev/null +++ b/packages/fullstack-hooks/README-docs-rs.md @@ -0,0 +1,32 @@ +# Dioxus Fullstack Hooks + +Dioxus fullstack hooks provides hooks and contexts for [`dioxus-fullstack`](https://crates.io/crates/dioxus-fullstack). Libraries that need to integrate with dioxus-fullstack should rely on this crate instead of the renderer for quicker build times. + +## Usage + +To start using this crate, you can run the following command: + +```bash +cargo add dioxus-fullstack-hooks +``` + +Then you can use hooks like `use_server_future` in your components: + +```rust +use dioxus::prelude::*; +async fn fetch_article(id: u32) -> String { + format!("Article {}", id) +} + +fn App() -> Element { + let mut article_id = use_signal(|| 0); + // `use_server_future` will spawn a task that runs on the server and serializes the result to send to the client. + // The future will rerun any time the + // Since we bubble up the suspense with `?`, the server will wait for the future to resolve before rendering + let article = use_server_future(move || fetch_article(article_id()))?; + + rsx! { + "{article().unwrap()}" + } +} +``` diff --git a/packages/fullstack-hooks/README.md b/packages/fullstack-hooks/README.md index f025fd32c3..5e3ba45bbc 100644 --- a/packages/fullstack-hooks/README.md +++ b/packages/fullstack-hooks/README.md @@ -1,3 +1,4 @@ + # Dioxus Fullstack Hooks Dioxus fullstack hooks provides hooks and contexts for [`dioxus-fullstack`](https://crates.io/crates/dioxus-fullstack). Libraries that need to integrate with dioxus-fullstack should rely on this crate instead of the renderer for quicker build times. @@ -29,4 +30,4 @@ fn App() -> Element { "{article().unwrap()}" } } -``` +``` \ No newline at end of file diff --git a/packages/fullstack-hooks/src/lib.rs b/packages/fullstack-hooks/src/lib.rs index 83637de732..b48c2bb297 100644 --- a/packages/fullstack-hooks/src/lib.rs +++ b/packages/fullstack-hooks/src/lib.rs @@ -1,5 +1,5 @@ #![warn(missing_docs)] -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] pub mod history; mod hooks; diff --git a/packages/fullstack-protocol/README-docs-rs.md b/packages/fullstack-protocol/README-docs-rs.md new file mode 100644 index 0000000000..cd0f68c0cc --- /dev/null +++ b/packages/fullstack-protocol/README-docs-rs.md @@ -0,0 +1,3 @@ +# Fullstack Protocol + +Dioxus-fullstack-protocol is the internal protocol the dioxus web and server renderers use to communicate with each other in dioxus fullstack. It is used to send futures and values from the server to the client during fullstack rendering. diff --git a/packages/fullstack-protocol/README.md b/packages/fullstack-protocol/README.md index cd0f68c0cc..6aa81e153e 100644 --- a/packages/fullstack-protocol/README.md +++ b/packages/fullstack-protocol/README.md @@ -1,3 +1,4 @@ + # Fullstack Protocol -Dioxus-fullstack-protocol is the internal protocol the dioxus web and server renderers use to communicate with each other in dioxus fullstack. It is used to send futures and values from the server to the client during fullstack rendering. +Dioxus-fullstack-protocol is the internal protocol the dioxus web and server renderers use to communicate with each other in dioxus fullstack. It is used to send futures and values from the server to the client during fullstack rendering. \ No newline at end of file diff --git a/packages/fullstack-protocol/src/lib.rs b/packages/fullstack-protocol/src/lib.rs index 5f81d12030..c16a25828f 100644 --- a/packages/fullstack-protocol/src/lib.rs +++ b/packages/fullstack-protocol/src/lib.rs @@ -1,5 +1,5 @@ #![warn(missing_docs)] -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] use base64::Engine; use dioxus_core::CapturedError; diff --git a/packages/fullstack/README-docs-rs.md b/packages/fullstack/README-docs-rs.md new file mode 100644 index 0000000000..23dcaffaa0 --- /dev/null +++ b/packages/fullstack/README-docs-rs.md @@ -0,0 +1,157 @@ +# Dioxus Fullstack + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-fullstack.svg +[crates-url]: https://crates.io/crates/dioxus-fullstack +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/) | +[API Docs](https://docs.rs/dioxus-fullstack/latest/dioxus_fullstack/) | +[Chat](https://discord.gg/XgGxMSkvUM) + +Fullstack utilities for the [`Dioxus`](https://dioxuslabs.com) framework. + +# Features + +- Integrates with the [Axum](./examples/axum-hello-world/src/main.rs) server framework with utilities for serving and rendering Dioxus applications. +- [Server functions](https://docs.rs/dioxus-fullstack/latest/dioxus_fullstack/prelude/attr.server.html) allow you to call code on the server from the client as if it were a normal function. +- Instant RSX Hot reloading with [`dioxus-hot-reload`](https://crates.io/crates/dioxus-hot-reload). +- Passing root props from the server to the client. + +# Example + +Full stack Dioxus in under 30 lines of code + +```rust, no_run +#![allow(non_snake_case)] +use dioxus::prelude::*; + +fn main() { + dioxus::launch(App); +} + +#[component] +fn App() -> Element { + let mut meaning = use_signal(|| None); + + rsx! { + h1 { "Meaning of life: {meaning:?}" } + button { + onclick: move |_| async move { + if let Ok(data) = get_meaning("life the universe and everything".into()).await { + meaning.set(data); + } + }, + "Run a server function" + } + } +} + +#[server] +async fn get_meaning(of: String) -> ServerFnResult> { + Ok(of.contains("life").then(|| 42)) +} +``` + +## Axum Integration + +If you have an existing Axum router or you need more control over the server, you can use the [`DioxusRouterExt`](https://docs.rs/dioxus-fullstack/0.6.0-alpha.2/dioxus_fullstack/prelude/trait.DioxusRouterExt.html) trait to integrate with your existing Axum router. + +First, make sure your `axum` dependency is optional and enabled by the server feature flag. Axum cannot be compiled to wasm, so if it is enabled by default, it will cause a compile error: + +```toml +[dependencies] +dioxus = { version = "*", features = ["fullstack"] } +axum = { version = "0.8.0", optional = true } +tokio = { version = "1.0", features = ["full"], optional = true } +dioxus-cli-config = { version = "*", optional = true } + +[features] +server = ["dioxus/server", "dep:axum", "dep:tokio", "dioxus-cli-config"] +web = ["dioxus/web"] +``` + +Then we can set up dioxus with the axum server: + +```rust, no_run +#![allow(non_snake_case)] +use dioxus::prelude::*; +use dioxus_fullstack::ServeConfig; + +// The entry point for the server +#[cfg(feature = "server")] +#[tokio::main] +async fn main() { + // Get the address the server should run on. If the CLI is running, the CLI proxies fullstack into the main address + // and we use the generated address the CLI gives us + let address = dioxus::cli_config::fullstack_address_or_localhost(); + + // Set up the axum router + let router = axum::Router::new() + // You can add a dioxus application to the router with the `serve_dioxus_application` method + // This will add a fallback route to the router that will serve your component and server functions + .serve_dioxus_application(ServeConfig::new().unwrap(), App); + + // Finally, we can launch the server + let router = router.into_make_service(); + let listener = tokio::net::TcpListener::bind(address).await.unwrap(); + axum::serve(listener, router).await.unwrap(); +} + +// For any other platform, we just launch the app +#[cfg(not(feature = "server"))] +fn main() { + dioxus::launch(App); +} + +#[component] +fn App() -> Element { + let mut meaning = use_signal(|| None); + + rsx! { + h1 { "Meaning of life: {meaning:?}" } + button { + onclick: move |_| async move { + if let Ok(data) = get_meaning("life the universe and everything".into()).await { + meaning.set(data); + } + }, + "Run a server function" + } + } +} + +#[server] +async fn get_meaning(of: String) -> ServerFnResult> { + Ok(of.contains("life").then(|| 42)) +} +``` + +## Getting Started + +To get started with full stack Dioxus, check out our [getting started guide](https://dioxuslabs.com/learn/0.6/getting_started), or the [full stack examples](https://github.com/DioxusLabs/dioxus/tree/master/examples). + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/fullstack/README.md b/packages/fullstack/README.md index 23dcaffaa0..24e1189814 100644 --- a/packages/fullstack/README.md +++ b/packages/fullstack/README.md @@ -1,3 +1,4 @@ + # Dioxus Fullstack [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-fullstack.svg -[crates-url]: https://crates.io/crates/dioxus-fullstack -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/) | [API Docs](https://docs.rs/dioxus-fullstack/latest/dioxus_fullstack/) | @@ -150,8 +142,16 @@ To get started with full stack Dioxus, check out our [getting started guide](htt This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-fullstack.svg +[crates-url]: https://crates.io/crates/dioxus-fullstack +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/fullstack/src/lib.rs b/packages/fullstack/src/lib.rs index 9156d839c1..2f36cb70cf 100644 --- a/packages/fullstack/src/lib.rs +++ b/packages/fullstack/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![warn(missing_docs)] diff --git a/packages/generational-box/README-docs-rs.md b/packages/generational-box/README-docs-rs.md new file mode 100644 index 0000000000..983f79d2f9 --- /dev/null +++ b/packages/generational-box/README-docs-rs.md @@ -0,0 +1,30 @@ +# Generational Box + +Generational Box is a runtime for Rust that allows any static type to implement `Copy`. It can be combined with a global runtime to create an ergonomic state solution like `dioxus-signals`. This crate doesn't have any `unsafe` code. + +Three main types manage state in Generational Box: + +- `Store`: Handles recycling generational boxes that have been dropped. Your application should have one store or one store per thread. +- `Owner`: Handles dropping generational boxes. The owner acts like a runtime lifetime guard. Any states that you create with an owner will be dropped when that owner is dropped. +- `GenerationalBox`: The core Copy state type. The generational box will be dropped when the owner is dropped. + +Example: + +```rust +use generational_box::{UnsyncStorage, AnyStorage}; + +// Create an owner for some state for a scope +let owner = UnsyncStorage::owner(); + +// Create some non-copy data, move it into a owner, and work with copy data +let data: String = "hello world".to_string(); +let key = owner.insert(data); + +// The generational box can be read from and written to like a RefCell +let value = key.read(); +assert_eq!(*value, "hello world"); +``` + +## How it works + +Internally, `generational-box` creates an arena of generational `RefCell`s that are recycled when the owner is dropped. You can think of the cells as something like `&'static RefCell>` with a generational check to make recycling a cell easier to debug. Then `GenerationalBox`es are `Copy` because the `&'static` pointer is `Copy`. diff --git a/packages/generational-box/README.md b/packages/generational-box/README.md index 983f79d2f9..74e24072bd 100644 --- a/packages/generational-box/README.md +++ b/packages/generational-box/README.md @@ -1,3 +1,4 @@ + # Generational Box Generational Box is a runtime for Rust that allows any static type to implement `Copy`. It can be combined with a global runtime to create an ergonomic state solution like `dioxus-signals`. This crate doesn't have any `unsafe` code. @@ -27,4 +28,4 @@ assert_eq!(*value, "hello world"); ## How it works -Internally, `generational-box` creates an arena of generational `RefCell`s that are recycled when the owner is dropped. You can think of the cells as something like `&'static RefCell>` with a generational check to make recycling a cell easier to debug. Then `GenerationalBox`es are `Copy` because the `&'static` pointer is `Copy`. +Internally, `generational-box` creates an arena of generational `RefCell`s that are recycled when the owner is dropped. You can think of the cells as something like `&'static RefCell>` with a generational check to make recycling a cell easier to debug. Then `GenerationalBox`es are `Copy` because the `&'static` pointer is `Copy`. \ No newline at end of file diff --git a/packages/generational-box/src/lib.rs b/packages/generational-box/src/lib.rs index 6c1592679e..999be41cb4 100644 --- a/packages/generational-box/src/lib.rs +++ b/packages/generational-box/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![warn(missing_docs)] use parking_lot::Mutex; diff --git a/packages/hooks/README-docs-rs.md b/packages/hooks/README-docs-rs.md new file mode 100644 index 0000000000..2e944d0955 --- /dev/null +++ b/packages/hooks/README-docs-rs.md @@ -0,0 +1,80 @@ +# Dioxus Hooks + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-hooks.svg +[crates-url]: https://crates.io/crates/dioxus-hooks +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/) | +[API Docs](https://docs.rs/dioxus-hooks/latest/dioxus_hooks) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-hooks` includes some basic useful hooks for Dioxus such as: + +- use_signal +- use_effect +- use_resource +- use_memo +- use_coroutine + +Unlike React, none of these hooks are foundational since they all build off the primitive `use_hook`. You can extend these hooks with [custom hooks](https://dioxuslabs.com/learn/0.6/cookbook/state/custom_hooks) in your own code. If you think they would be useful for the broader community, you can open a PR to add your hook to the [Dioxus Awesome](https://github.com/DioxusLabs/awesome-dioxus) list. + +## State Cheat Sheet + +If you aren't sure what hook to use, you can use this cheat sheet to help you decide: + +### State Location + +Depending on where you need to access the state, you can put your state in one of three places: + +| Location | Where can you access the state? | Recommended for Libraries? | Examples | +| ---------------------------------------------------------------------------------------- | ------------------------------- | -------------------------- | --------------------------------------------------------------------------- | +| [Hooks](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_signal.html) | Any components you pass it to | ✅ | `use_signal(\|\| 0)`, `use_memo(\|\| state() * 2)` | +| [Context](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_context_provider.html) | Any child components | ✅ | `use_context_provider(\|\| Signal::new(0))`, `use_context::>()` | +| [Global](https://docs.rs/dioxus/latest/dioxus/prelude/struct.Signal.html#method.global) | Anything in your app | ❌ | `Signal::global(\|\| 0)` | + +### Derived State + +If you don't have an initial value for your state, you can derive your state from other states with a closure or asynchronous function: + +| Hook | Reactive (reruns when dependencies change) | Async | Memorizes Output | Example | +| ----------------------------------------------------------------------------------- | ------------------------------------------ | ----- | ---------------- | ----------------------------------------------------------------------------------- | +| [`use_memo`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_memo.html) | ✅ | ❌ | ✅ | `use_memo(move \|\| count() * 2)` | +| [`use_resource`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_resource.html) | ✅ | ✅ | ❌ | `use_resource(move \|\| reqwest::get(format!("/users/{user_id}")))` | +| [`use_future`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_future.html) | ❌ | ✅ | ❌ | `use_future(move \|\| println!("{:?}", reqwest::get(format!("/users/{user_id}"))))` | + +### Persistent State + +The core hooks library doesn't provide hooks for persistent state, but you can extend the core hooks with hooks from [dioxus-sdk](https://crates.io/crates/dioxus-sdk) and the [dioxus-router](https://crates.io/crates/dioxus-router) to provide persistent state management. + +| State | Sharable | Example | +| ---------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | +| [`use_persistent`](https://github.com/DioxusLabs/sdk/tree/master/examples/storage) | ❌ | `use_persistent("unique_key", move \|\| initial_state)` | +| [`Router {}`](https://dioxuslabs.com/learn/0.6/router) | ✅ | `#[derive(Routable, Clone, PartialEq)] enum Route { #[route("/user/:id")] Homepage { id: u32 } }` | + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/hooks/README.md b/packages/hooks/README.md index 2e944d0955..62a83ee968 100644 --- a/packages/hooks/README.md +++ b/packages/hooks/README.md @@ -1,3 +1,4 @@ + # Dioxus Hooks [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-hooks.svg -[crates-url]: https://crates.io/crates/dioxus-hooks -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/) | [API Docs](https://docs.rs/dioxus-hooks/latest/dioxus_hooks) | @@ -73,8 +65,16 @@ The core hooks library doesn't provide hooks for persistent state, but you can e This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-hooks.svg +[crates-url]: https://crates.io/crates/dioxus-hooks +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/hooks/src/lib.rs b/packages/hooks/src/lib.rs index be9c07b841..3ede83227f 100644 --- a/packages/hooks/src/lib.rs +++ b/packages/hooks/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/html/README-docs-rs.md b/packages/html/README-docs-rs.md new file mode 100644 index 0000000000..167d607640 --- /dev/null +++ b/packages/html/README-docs-rs.md @@ -0,0 +1,105 @@ +# `dioxus-html`: Html (and SVG) Namespace for Dioxus + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-html.svg +[crates-url]: https://crates.io/crates/dioxus-html +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/) | +[API Docs](https://docs.rs/dioxus-html/latest/dioxus_html) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +The Dioxus `rsx!` macro can accept any compile-time correct namespace on top of NodeFactory. This crate provides the HTML (and SVG) namespaces which get imported in the Dioxus prelude. + +However, this abstraction enables you to add any namespace of elements, provided they're in scope when rsx! is called. For an example, a UI that is designed for Augmented Reality might use different primitives than HTML: + +```rust, ignore +use ar_namespace::*; + +rsx! { + magic_div { + magic_header {} + magic_paragraph { + on_magic_click: move |event| { + // + } + } + } +} +``` + +This is currently a not-very-explored part of Dioxus. However, the namespacing system does make it possible to provide syntax highlighting, documentation, "go to definition" and compile-time correctness, so it's worth having it abstracted. + +## How it works: + +Elements for dioxus must implement the (simple) DioxusElement trait to be used in the rsx! macro. + +```rust, ignore +struct div; +impl DioxusElement for div { + const TAG_NAME: &'static str = "div"; + const NAME_SPACE: Option<&'static str> = None; +} +``` + +All elements should be defined as a zero-sized-struct (also known as unit struct). These structs are zero-cost and just provide the type-level trickery to Rust for compile-time correct templates. + +Attributes would then be implemented as constants on these unit structs. + +The HTML namespace is defined mostly with macros. However, the expanded form would look something like this: + +```rust, ignore +struct base; +impl DioxusElement for base { + const TAG_NAME: &'static str = "base"; + const NAME_SPACE: Option<&'static str> = None; +} +impl base { + const href: (&'static str, Option<'static str>, bool) = ("href", None, false); + const target: (&'static str, Option<'static str>, bool) = ("target", None, false); +} +``` + +Because attributes are defined as methods on the unit struct, they guard the attribute creation behind a compile-time correct interface. + +## How to extend it: + +Whenever the rsx! macro is called, it relies on a module `dioxus_elements` to be in scope. When you enable the `html` feature in dioxus, this module gets imported in the prelude. However, you can extend this with your own set of custom elements by making your own `dioxus_elements` module and re-exporting the html namespace. + +```rust, ignore +mod dioxus_elements { + use dioxus::prelude::dioxus_elements::*; + struct my_element; + impl DioxusElement for my_element { + const TAG_NAME: &'static str = "base"; + const NAME_SPACE: Option<&'static str> = None; + } +} +``` + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/html/README.md b/packages/html/README.md index 167d607640..0b67770742 100644 --- a/packages/html/README.md +++ b/packages/html/README.md @@ -1,3 +1,4 @@ + # `dioxus-html`: Html (and SVG) Namespace for Dioxus [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-html.svg -[crates-url]: https://crates.io/crates/dioxus-html -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/) | [API Docs](https://docs.rs/dioxus-html/latest/dioxus_html) | @@ -98,8 +90,16 @@ mod dioxus_elements { This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-html.svg +[crates-url]: https://crates.io/crates/dioxus-html +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/html/src/lib.rs b/packages/html/src/lib.rs index 090b4783d4..968af08aab 100644 --- a/packages/html/src/lib.rs +++ b/packages/html/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![allow(non_snake_case)] diff --git a/packages/interpreter/README-docs-rs.md b/packages/interpreter/README-docs-rs.md new file mode 100644 index 0000000000..8778e18fe0 --- /dev/null +++ b/packages/interpreter/README-docs-rs.md @@ -0,0 +1,53 @@ +# `dioxus-interpreter-js` + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-interpreter-js.svg +[crates-url]: https://crates.io/crates/dioxus-interpreter-js +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/) | +[API Docs](https://docs.rs/dioxus-interpreter-js/latest/dioxus_interpreter_js) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-interpreter-js` provides the high-performance JavaScript glue that interprets the stream of edits produced by the Dioxus VirtualDom and converts them into mutations on the actual web DOM. + +This crate features bindings for the web and sledgehammer for increased performance. + +## Architecture + +We use TypeScript to write the bindings and a very simple build.rs along with bun to convert them to javascript, minify them, and glue them into the rest of the project. + +Not every snippet of JS will be used, so we split out the snippets from the core interpreter. + +In theory, we _could_ use Rust in the browser to do everything these bindings are doing. In reality, we want to stick with JS to skip the need for a WASM build step when running the LiveView and WebView renderers. We also want to use JS to prevent diverging behavior of things like canceling events, uploading files, and collecting form inputs. These details are tough to ensure 1:1 compatibility when implementing them in two languages. + +If you want to contribute to the bindings, you'll need to have the typescript compiler installed on your machine as well as bun: + + + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/interpreter/README.md b/packages/interpreter/README.md index 8778e18fe0..818d68ae81 100644 --- a/packages/interpreter/README.md +++ b/packages/interpreter/README.md @@ -1,3 +1,4 @@ + # `dioxus-interpreter-js` [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-interpreter-js.svg -[crates-url]: https://crates.io/crates/dioxus-interpreter-js -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/) | [API Docs](https://docs.rs/dioxus-interpreter-js/latest/dioxus_interpreter_js) | @@ -46,8 +38,16 @@ If you want to contribute to the bindings, you'll need to have the typescript co This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-interpreter-js.svg +[crates-url]: https://crates.io/crates/dioxus-interpreter-js +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/interpreter/src/lib.rs b/packages/interpreter/src/lib.rs index 5e028a15eb..e23b1e3235 100644 --- a/packages/interpreter/src/lib.rs +++ b/packages/interpreter/src/lib.rs @@ -1,5 +1,5 @@ #![allow(clippy::empty_docs)] -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/liveview/README-docs-rs.md b/packages/liveview/README-docs-rs.md new file mode 100644 index 0000000000..9bc987a374 --- /dev/null +++ b/packages/liveview/README-docs-rs.md @@ -0,0 +1,49 @@ +# Dioxus Liveview + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-liveview.svg +[crates-url]: https://crates.io/crates/dioxus-liveview +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/) | +[API Docs](https://docs.rs/dioxus-liveview/latest/dioxus_liveview) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +`dioxus-liveview` provides adapters for running the Dioxus VirtualDom over a WebSocket connection. + +The current backend frameworks supported include: + +- Axum + +Dioxus-LiveView exports some primitives to wire up an app into an existing backend framework. + +- A ThreadPool for spawning the `!Send` VirtualDom and interacting with it from WebSockets +- An adapter for transforming various socket types into the `LiveViewSocket` type +- The glue to load the interpreter into your app + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/liveview/README.md b/packages/liveview/README.md index 9bc987a374..914bc312ba 100644 --- a/packages/liveview/README.md +++ b/packages/liveview/README.md @@ -1,3 +1,4 @@ + # Dioxus Liveview [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-liveview.svg -[crates-url]: https://crates.io/crates/dioxus-liveview -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/) | [API Docs](https://docs.rs/dioxus-liveview/latest/dioxus_liveview) | @@ -42,8 +34,16 @@ Dioxus-LiveView exports some primitives to wire up an app into an existing backe This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-liveview.svg +[crates-url]: https://crates.io/crates/dioxus-liveview +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/liveview/src/lib.rs b/packages/liveview/src/lib.rs index 354a9629b9..b91bc9f666 100644 --- a/packages/liveview/src/lib.rs +++ b/packages/liveview/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/logger/README-docs-rs.md b/packages/logger/README-docs-rs.md new file mode 100644 index 0000000000..2c322ada7c --- /dev/null +++ b/packages/logger/README-docs-rs.md @@ -0,0 +1,89 @@ +
+

📡 Dioxus Logger 🛰️

+

A logging utility to provide a standard interface whether you're targeting web, desktop, fullstack, and more.

+
+ +
+ + + Crates.io version + + + + Download + + + + docs.rs docs + +
+ +----- + +`dioxus-logger` is a basic cross-platform facade for logging in [Dioxus](https://dioxuslabs.com/) that uses the [tracing](https://crates.io/crates/tracing) crate. + + +```rust +use dioxus::prelude::*; +use dioxus_logger::tracing::{Level, info}; + +fn main() { + dioxus_logger::init(Level::INFO).expect("logger failed to init"); + dioxus::launch(App); +} + +#[component] +fn App() -> Element { + info!("App rendered"); + rsx! { + p { "hi" } + } +} +``` + +## Dioxus support + +As of v0.6, dioxus_logger is part of dioxus itself. Dioxus will call `init` with a default Level, though you can still override the default with `init`. + +```rust +use dioxus::prelude::*; +use dioxus::logger::tracing::{Level, info}; + +fn main() { + dioxus::logger::init(Level::INFO).expect("logger failed to init"); + dioxus::launch(App); +} + +#[component] +fn App() -> Element { + info!("App rendered"); + rsx! { + p { "hi" } + } +} +``` +For non-wasm targets, runtime filtering is based on the `RUST_LOG` environment variable. e.g. for `RUST_LOG=none,crateName=trace` only logs trace and above for `crateName` will be captured. See [here](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives) for syntax. For crates with `-` in the name, these need to be changed to `_` in `RUST_LOG`. + +## Platform Support +Dioxus logger will eventually support every target that Dioxus does. Currently mobile and TUI are not supported. + +## Installation +`dioxus_logger` is part of Dioxus v0.6. If you're using Dioxus v0.6, then no installation is required! + + +If you're on Dioxus v0.5 and below, you can add `dioxus-logger` to your application by adding it to your dependencies. +```toml +[dependencies] +dioxus-logger = "0.5" +``` + + +## License +This project is licensed under the [MIT license]. + +[mit license]: ./LICENSE + +Every contribution intentionally submitted for inclusion in `dioxus-logger` by you, shall be licensed as MIT, without any additional terms or conditions. diff --git a/packages/logger/README.md b/packages/logger/README.md index 2c322ada7c..a288f55315 100644 --- a/packages/logger/README.md +++ b/packages/logger/README.md @@ -1,3 +1,4 @@ +

📡 Dioxus Logger 🛰️

A logging utility to provide a standard interface whether you're targeting web, desktop, fullstack, and more.

@@ -21,11 +22,10 @@
------ +--- `dioxus-logger` is a basic cross-platform facade for logging in [Dioxus](https://dioxuslabs.com/) that uses the [tracing](https://crates.io/crates/tracing) crate. - ```rust use dioxus::prelude::*; use dioxus_logger::tracing::{Level, info}; @@ -65,25 +65,28 @@ fn App() -> Element { } } ``` + For non-wasm targets, runtime filtering is based on the `RUST_LOG` environment variable. e.g. for `RUST_LOG=none,crateName=trace` only logs trace and above for `crateName` will be captured. See [here](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives) for syntax. For crates with `-` in the name, these need to be changed to `_` in `RUST_LOG`. ## Platform Support + Dioxus logger will eventually support every target that Dioxus does. Currently mobile and TUI are not supported. ## Installation -`dioxus_logger` is part of Dioxus v0.6. If you're using Dioxus v0.6, then no installation is required! +`dioxus_logger` is part of Dioxus v0.6. If you're using Dioxus v0.6, then no installation is required! If you're on Dioxus v0.5 and below, you can add `dioxus-logger` to your application by adding it to your dependencies. + ```toml [dependencies] dioxus-logger = "0.5" ``` - ## License -This project is licensed under the [MIT license]. -[mit license]: ./LICENSE +This project is licensed under the [MIT license]. Every contribution intentionally submitted for inclusion in `dioxus-logger` by you, shall be licensed as MIT, without any additional terms or conditions. + +[MIT license]: ./LICENSE \ No newline at end of file diff --git a/packages/logger/src/lib.rs b/packages/logger/src/lib.rs index bfc7fd6d8e..63517a9c65 100644 --- a/packages/logger/src/lib.rs +++ b/packages/logger/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README-docs-rs.md")] use tracing::{ subscriber::{set_global_default, SetGlobalDefaultError}, Level, diff --git a/packages/manganis/manganis-macro/README-docs-rs.md b/packages/manganis/manganis-macro/README-docs-rs.md new file mode 100644 index 0000000000..fde983fef5 --- /dev/null +++ b/packages/manganis/manganis-macro/README-docs-rs.md @@ -0,0 +1,3 @@ +# Manganis Macro + +This crate contains the macro used to interact with the Manganis asset system. diff --git a/packages/manganis/manganis-macro/README.md b/packages/manganis/manganis-macro/README.md index fde983fef5..b5b681b289 100644 --- a/packages/manganis/manganis-macro/README.md +++ b/packages/manganis/manganis-macro/README.md @@ -1,3 +1,4 @@ + # Manganis Macro -This crate contains the macro used to interact with the Manganis asset system. +This crate contains the macro used to interact with the Manganis asset system. \ No newline at end of file diff --git a/packages/manganis/manganis-macro/src/lib.rs b/packages/manganis/manganis-macro/src/lib.rs index e497d805b9..a81cb953c9 100644 --- a/packages/manganis/manganis-macro/src/lib.rs +++ b/packages/manganis/manganis-macro/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![deny(missing_docs)] use std::{ diff --git a/packages/manganis/manganis/README-docs-rs.md b/packages/manganis/manganis/README-docs-rs.md new file mode 100644 index 0000000000..81a5486dd7 --- /dev/null +++ b/packages/manganis/manganis/README-docs-rs.md @@ -0,0 +1,31 @@ +# Manganis + +The Manganis allows you to submit assets to any build tool that supports collecting assets. It makes it easy to self-host assets that are distributed throughout your libraries. Manganis also handles optimizing, converting, and fetching assets. + +If you defined this in a component library: + +```rust +use manganis::{Asset, asset}; +const AVIF_ASSET: Asset = manganis::asset!("/assets/image.png"); +``` + +AVIF_ASSET will be set to a new file name that will be served by some CLI. That file can be collected by any package that depends on the component library. + +```rust +use manganis::{ImageFormat, Asset, asset, ImageSize, AssetOptions}; +// You can collect arbitrary files. Absolute paths are resolved relative to the package root +const _: Asset = asset!("/assets/script.js"); + +// You can collect images which will be automatically optimized +pub const PNG_ASSET: Asset = + asset!("/assets/image.png"); +// Resize the image at compile time to make the assets smaller +pub const RESIZED_PNG_ASSET: Asset = + asset!("/assets/image.png", AssetOptions::image().with_size(ImageSize::Manual { width: 52, height: 52 })); +// Or convert the image at compile time to a web friendly format +pub const AVIF_ASSET: Asset = asset!("/assets/image.png", AssetOptions::image().with_format(ImageFormat::Avif)); +``` + +## Adding Support to Your CLI + +To add support for your CLI, you need to integrate with the [manganis_cli_support](https://github.com/DioxusLabs/manganis/tree/main/cli-support) crate. This crate provides utilities to collect assets that integrate with the Manganis macro. It makes it easy to integrate an asset collection and optimization system into a build tool. diff --git a/packages/manganis/manganis/README.md b/packages/manganis/manganis/README.md index 81a5486dd7..e72ec70f00 100644 --- a/packages/manganis/manganis/README.md +++ b/packages/manganis/manganis/README.md @@ -1,3 +1,4 @@ + # Manganis The Manganis allows you to submit assets to any build tool that supports collecting assets. It makes it easy to self-host assets that are distributed throughout your libraries. Manganis also handles optimizing, converting, and fetching assets. @@ -28,4 +29,4 @@ pub const AVIF_ASSET: Asset = asset!("/assets/image.png", AssetOptions::image(). ## Adding Support to Your CLI -To add support for your CLI, you need to integrate with the [manganis_cli_support](https://github.com/DioxusLabs/manganis/tree/main/cli-support) crate. This crate provides utilities to collect assets that integrate with the Manganis macro. It makes it easy to integrate an asset collection and optimization system into a build tool. +To add support for your CLI, you need to integrate with the [manganis_cli_support](https://github.com/DioxusLabs/manganis/tree/main/cli-support) crate. This crate provides utilities to collect assets that integrate with the Manganis macro. It makes it easy to integrate an asset collection and optimization system into a build tool. \ No newline at end of file diff --git a/packages/manganis/manganis/src/lib.rs b/packages/manganis/manganis/src/lib.rs index fdb8876f82..d9e168603f 100644 --- a/packages/manganis/manganis/src/lib.rs +++ b/packages/manganis/manganis/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![deny(missing_docs)] #[doc(hidden)] diff --git a/packages/router/README-docs-rs.md b/packages/router/README-docs-rs.md new file mode 100644 index 0000000000..0d73931f3d --- /dev/null +++ b/packages/router/README-docs-rs.md @@ -0,0 +1,138 @@ +# Dioxus Router + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-router.svg +[crates-url]: https://crates.io/crates/dioxus-router +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/router/) | +[API Docs](https://docs.rs/dioxus-router/latest/dioxus_router) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +Dioxus Router is a first-party Router for all your Dioxus Apps. It provides an +interface similar to React Router, but takes advantage of types for more +expressiveness. + +```rust, no_run +use dioxus::prelude::*; +use std::str::FromStr; + +#[rustfmt::skip] +#[derive(Clone, Debug, PartialEq, Routable)] +enum Route { + #[nest("/blog")] + #[layout(Blog)] + #[route("/")] + BlogList {}, + + #[route("/:blog_id")] + BlogPost { blog_id: usize }, + #[end_layout] + #[end_nest] + #[route("/")] + Index {}, +} + +#[component] +fn App() -> Element { + rsx! { + Router:: { } + } +} + +#[component] +fn Index() -> Element { + rsx! { + h1 { "Index" } + Link { + to: Route::BlogList {}, + "Go to the blog" + } + } +} + +#[component] +fn Blog() -> Element { + rsx! { + h1 { "Blog" } + Outlet:: { } + } +} + +#[component] +fn BlogList() -> Element { + rsx! { + h2 { "List of blog posts" } + Link { + to: Route::BlogPost { blog_id: 0 }, + "Blog post 1" + } + Link { + to: Route::BlogPost { blog_id: 1 }, + "Blog post 2" + } + } +} + +#[component] +fn BlogPost(blog_id: usize) -> Element { + rsx! { + h2 { "Blog Post" } + } +} +``` + +You need to enable the right features for the platform you're targeting since these are not determined automatically! + +## Bundle Splitting + +The Dioxus Router supports automatic bundle splitting along route variants. To enable this, you need to manually turn on the `wasm-split` feature explicitly on the dioxus-router crate: + +```toml +[dependencies] +dioxus = { version = "*", features = ["router", "wasm-split"] } +dioxus-router = { version = "*", features = ["wasm-split"] } +``` + +Note that `wasm-split` must also be turned on in dioxus since the macro uses the re-exported `wasm-split` from the dioxus prelude. + +Enabling splitting disconnects the call graph, meaning if you try to run your app with a normal `dx serve`, it won't work. When running with router splitting, you need to pass `--experimental-wasm-split`. + +```sh +dx serve --experimental-wasm-split +``` + +In practice, we recommend passing `dioxus-router?/wasm-split` as a feature only when bundling: + +```sh +dx bundle --features "dioxus-router?/wasm-split" --experimental-wasm-split +``` + +Note that the router will call `.suspend()` so you should add a SuspenseBoundary above the Outlet to prevent suspending the entire page. + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/router/README.md b/packages/router/README.md index 0d73931f3d..4ad70d339a 100644 --- a/packages/router/README.md +++ b/packages/router/README.md @@ -1,3 +1,4 @@ + # Dioxus Router [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-router.svg -[crates-url]: https://crates.io/crates/dioxus-router -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/router/) | [API Docs](https://docs.rs/dioxus-router/latest/dioxus_router) | @@ -131,8 +123,16 @@ Note that the router will call `.suspend()` so you should add a SuspenseBoundary This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-router.svg +[crates-url]: https://crates.io/crates/dioxus-router +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/router/src/lib.rs b/packages/router/src/lib.rs index 6e9804f324..9c39ad7519 100644 --- a/packages/router/src/lib.rs +++ b/packages/router/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] // cannot use forbid, because props derive macro generates #[allow(missing_docs)] diff --git a/packages/rsx-rosetta/README-docs-rs.md b/packages/rsx-rosetta/README-docs-rs.md new file mode 100644 index 0000000000..67aabbe754 --- /dev/null +++ b/packages/rsx-rosetta/README-docs-rs.md @@ -0,0 +1,54 @@ +# `rsx-rosetta` + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/rsx-rosetta.svg +[crates-url]: https://crates.io/crates/rsx-rosetta +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/) | +[API Docs](https://docs.rs/rsx-rosetta/latest/rsx-rosetta) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +Dioxus sports its own templating language inspired by C#/Kotlin/RTMP, etc. It's pretty straightforward. + +However, it's NOT HTML. This is done since HTML is verbose and you'd need a dedicated LSP or IDE integration to get a good DX in .rs files. + +RSX is simple... It's similar enough to regular Rust code to trick most IDEs into automatically providing support for things like block selections, folding, highlighting, etc. + +To accommodate the transition from HTML to RSX, you might need to translate some existing code. + +This library provides a central AST that can accept a number of inputs: + +- HTML +- Syn (todo) +- Akama (todo) +- Jinja (todo) + +From there, you can convert directly to a string or into some other AST. + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you, shall be licensed as MIT, without any additional +terms or conditions. diff --git a/packages/rsx-rosetta/README.md b/packages/rsx-rosetta/README.md index 67aabbe754..67ae363866 100644 --- a/packages/rsx-rosetta/README.md +++ b/packages/rsx-rosetta/README.md @@ -1,3 +1,4 @@ + # `rsx-rosetta` [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/rsx-rosetta.svg -[crates-url]: https://crates.io/crates/rsx-rosetta -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/) | [API Docs](https://docs.rs/rsx-rosetta/latest/rsx-rosetta) | @@ -47,8 +39,16 @@ From there, you can convert directly to a string or into some other AST. This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you, shall be licensed as MIT, without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/rsx-rosetta.svg +[crates-url]: https://crates.io/crates/rsx-rosetta +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/rsx-rosetta/src/lib.rs b/packages/rsx-rosetta/src/lib.rs index 85604a2049..860a905800 100644 --- a/packages/rsx-rosetta/src/lib.rs +++ b/packages/rsx-rosetta/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/server-macro/src/lib.rs b/packages/server-macro/src/lib.rs index 7440ce8451..4b5b8f2198 100644 --- a/packages/server-macro/src/lib.rs +++ b/packages/server-macro/src/lib.rs @@ -1,4 +1,4 @@ -// TODO: Create README, uncomment this: #![doc = include_str!("../README.md")] +// TODO: Create README, uncomment this: #![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/signals/README-docs-rs.md b/packages/signals/README-docs-rs.md new file mode 100644 index 0000000000..5ec2256ddf --- /dev/null +++ b/packages/signals/README-docs-rs.md @@ -0,0 +1,127 @@ +# Dioxus Signals + +Dioxus Signals is an ergonomic Copy runtime for data with local subscriptions. + +## Copy Data + +All signals implement Copy, even if the inner value does not implement copy. This makes it easy to move any data into futures or children. + +```rust +use dioxus::prelude::*; +use dioxus_signals::*; + +#[component] +fn App() -> Element { + let signal = use_signal(|| "hello world".to_string()); + + spawn(async move { + // signal is Copy even though String is not copy + print!("{signal}"); + }); + + rsx! { + "{signal}" + } +} +``` + +## Local Subscriptions + +Signals will only subscribe to components when you read from the signal in that component. It will never subscribe to a component when reading data in a future or event handler. + +```rust +use dioxus::prelude::*; +use dioxus_signals::*; + +#[component] +fn App() -> Element { + // Because signal is never read in this component, this component will not rerun when the signal changes + let mut signal = use_signal(|| 0); + + rsx! { + button { + onclick: move |_| { + signal += 1; + }, + "Increase" + } + for id in 0..10 { + Child { + signal, + } + } + } +} + +#[derive(Props, Clone, PartialEq)] +struct ChildProps { + signal: Signal, +} + +fn Child(props: ChildProps) -> Element { + // This component does read from the signal, so when the signal changes it will rerun + rsx! { + "{props.signal}" + } +} +``` + +Because subscriptions happen when you read from (not create) the data, you can provide signals through the normal context API: + +```rust +use dioxus::prelude::*; +use dioxus_signals::*; + +#[component] +fn App() -> Element { + // Because signal is never read in this component, this component will not rerun when the signal changes + use_context_provider(|| Signal::new(0)); + + rsx! { + Child {} + } +} + +#[component] +fn Child() -> Element { + let signal: Signal = use_context(); + // This component does read from the signal, so when the signal changes it will rerun + rsx! { + "{signal}" + } +} +``` + +## Computed Data + +In addition to local subscriptions in components, `dioxus-signals` provides a way to derive data with local subscriptions. + +The use_memo hook will only rerun when any signals inside the hook change: + +```rust +use dioxus::prelude::*; +use dioxus_signals::*; + +#[component] +fn App() -> Element { + let mut signal = use_signal(|| 0); + let doubled = use_memo(move || signal * 2); + + rsx! { + button { + onclick: move |_| signal += 1, + "Increase" + } + Child { + signal: doubled + } + } +} + +#[component] +fn Child(signal: ReadSignal) -> Element { + rsx! { + "{signal}" + } +} +``` diff --git a/packages/signals/README.md b/packages/signals/README.md index 5ec2256ddf..c6ed3cbd9a 100644 --- a/packages/signals/README.md +++ b/packages/signals/README.md @@ -1,3 +1,4 @@ + # Dioxus Signals Dioxus Signals is an ergonomic Copy runtime for data with local subscriptions. @@ -124,4 +125,4 @@ fn Child(signal: ReadSignal) -> Element { "{signal}" } } -``` +``` \ No newline at end of file diff --git a/packages/signals/src/lib.rs b/packages/signals/src/lib.rs index 926cba75d9..1162dad97e 100644 --- a/packages/signals/src/lib.rs +++ b/packages/signals/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![warn(missing_docs)] diff --git a/packages/ssr/README-docs-rs.md b/packages/ssr/README-docs-rs.md new file mode 100644 index 0000000000..5290fa6880 --- /dev/null +++ b/packages/ssr/README-docs-rs.md @@ -0,0 +1,105 @@ +
+

Dioxus Server-Side Rendering (SSR)

+

+ Render Dioxus to valid html. +

+
+ +## Resources + +This crate is a part of the broader Dioxus ecosystem. For more resources about Dioxus, check out: + +- [Getting Started](https://dioxuslabs.com/learn/0.6/getting_started) +- [Book](https://dioxuslabs.com/learn/0.6/) +- [Examples](https://github.com/DioxusLabs/dioxus/tree/main/examples) + +## Overview + +Dioxus SSR provides utilities to render Dioxus components to valid HTML. Once rendered, the HTML can be rehydrated client-side or served from your web server of choice. + +```rust +# use dioxus::prelude::*; +fn app() -> Element { + rsx! { + div {"hello world!"} + } +} + +let mut vdom = VirtualDom::new(app); +vdom.rebuild_in_place(); + +let text = dioxus_ssr::render(&vdom); +assert_eq!(text, "
hello world!
") +``` + +## Basic Usage + +The simplest example is to simply render some `rsx!` nodes to HTML. This can be done with the [`render_element`] API. + +```rust, no_run +# use dioxus::prelude::*; +let content = dioxus_ssr::render_element(rsx! { + div { + for i in 0..5 { + "Number: {i}" + } + } +}); +``` + +## Rendering a VirtualDom + +```rust, no_run +# use dioxus::prelude::*; +# fn app() -> Element { todo!() } +let mut vdom = VirtualDom::new(app); +vdom.rebuild_in_place(); + +let content = dioxus_ssr::render(&vdom); +``` + +## Usage in pre-rendering + +This crate is particularly useful in pre-generating pages server-side and then selectively loading Dioxus client-side to pick up the reactive elements. + +This crate supports hydration out of the box. However, both the client and server must generate the _exact_ same VirtualDOMs - the client picks up its VirtualDOM assuming that the pre-rendered page output is the same. To do this, you need to make sure that your VirtualDOM implementation is deterministic! This could involve either serializing our app state and sending it to the client, hydrating only parts of the page, or building tests to ensure what's rendered on the server is the same as the client. + +With pre-rendering enabled, this crate will generate element nodes with Element IDs pre-associated. During hydration, the Dioxus-WebSys renderer will attach the Virtual nodes to these real nodes after a page query. + +To enable pre-rendering, simply set the pre-rendering flag to true. + +```rust, no_run +# use dioxus::prelude::*; +# fn App() -> Element { todo!() } +let mut vdom = VirtualDom::new(App); + +vdom.rebuild_in_place(); + +let mut renderer = dioxus_ssr::Renderer::new(); +renderer.pre_render = true; + +let text = renderer.render(&vdom); +``` + +## Usage in server-side rendering + +Dioxus SSR can also be used to render on the server. You can just render the VirtualDOM to a string and send that to the client. + +```rust +# use dioxus::prelude::*; +fn App() -> Element { + rsx! { div { "hello world!" } } +} +let mut vdom = VirtualDom::new(App); +vdom.rebuild_in_place(); +let text = dioxus_ssr::render(&vdom); +assert_eq!(text, "
hello world!
") +``` + +The rest of the space - IE doing this more efficiently, caching the VirtualDom, etc, will all need to be a custom implementation for now. + +## Usage in static site generation + +Dioxus SSR is a powerful tool to generate static sites. Using Dioxus for static site generation _is_ a bit overkill, however. The new documentation generation library, Doxie, is essentially Dioxus SSR on steroids designed for static site generation with client-side hydration. + +Again, simply render the VirtualDOM to a string using `render` or any of the other render methods. diff --git a/packages/ssr/README.md b/packages/ssr/README.md index 5290fa6880..cc0101bed9 100644 --- a/packages/ssr/README.md +++ b/packages/ssr/README.md @@ -1,3 +1,4 @@ +

Dioxus Server-Side Rendering (SSR)

@@ -18,7 +19,6 @@ This crate is a part of the broader Dioxus ecosystem. For more resources about D Dioxus SSR provides utilities to render Dioxus components to valid HTML. Once rendered, the HTML can be rehydrated client-side or served from your web server of choice. ```rust -# use dioxus::prelude::*; fn app() -> Element { rsx! { div {"hello world!"} @@ -37,7 +37,6 @@ assert_eq!(text, "

hello world!
") The simplest example is to simply render some `rsx!` nodes to HTML. This can be done with the [`render_element`] API. ```rust, no_run -# use dioxus::prelude::*; let content = dioxus_ssr::render_element(rsx! { div { for i in 0..5 { @@ -50,8 +49,6 @@ let content = dioxus_ssr::render_element(rsx! { ## Rendering a VirtualDom ```rust, no_run -# use dioxus::prelude::*; -# fn app() -> Element { todo!() } let mut vdom = VirtualDom::new(app); vdom.rebuild_in_place(); @@ -69,8 +66,6 @@ With pre-rendering enabled, this crate will generate element nodes with Element To enable pre-rendering, simply set the pre-rendering flag to true. ```rust, no_run -# use dioxus::prelude::*; -# fn App() -> Element { todo!() } let mut vdom = VirtualDom::new(App); vdom.rebuild_in_place(); @@ -86,7 +81,6 @@ let text = renderer.render(&vdom); Dioxus SSR can also be used to render on the server. You can just render the VirtualDOM to a string and send that to the client. ```rust -# use dioxus::prelude::*; fn App() -> Element { rsx! { div { "hello world!" } } } @@ -102,4 +96,4 @@ The rest of the space - IE doing this more efficiently, caching the VirtualDom, Dioxus SSR is a powerful tool to generate static sites. Using Dioxus for static site generation _is_ a bit overkill, however. The new documentation generation library, Doxie, is essentially Dioxus SSR on steroids designed for static site generation with client-side hydration. -Again, simply render the VirtualDOM to a string using `render` or any of the other render methods. +Again, simply render the VirtualDOM to a string using `render` or any of the other render methods. \ No newline at end of file diff --git a/packages/ssr/src/lib.rs b/packages/ssr/src/lib.rs index 18764c1e3b..3a1321bc1f 100644 --- a/packages/ssr/src/lib.rs +++ b/packages/ssr/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] diff --git a/packages/stores/README-docs-rs.md b/packages/stores/README-docs-rs.md new file mode 100644 index 0000000000..71795ac942 --- /dev/null +++ b/packages/stores/README-docs-rs.md @@ -0,0 +1,64 @@ +# Dioxus Stores + +Stores are an extension to the Dioxus signals system for reactive nested data structures. Each store will lazily create signals for each field/member of the data structure as needed. + +By default stores act a lot like [`dioxus_signals::Signal`]s, but they provide more granular +subscriptions without requiring nested signals. You should derive [`Store`](dioxus_stores_macro::Store) on your data +structures to generate selectors that let you scope the store to a specific part of your data structure. + +```rust, no_run +use dioxus::prelude::*; +use dioxus_stores::*; + +fn main() { + dioxus::launch(app); +} + +// Deriving the store trait provides methods to scope the store to specific parts of your data structure. +// The `Store` macro generates a `count` and `children` method for `Store` +#[derive(Store, Default)] +struct CounterTree { + count: i32, + children: Vec, +} + +fn app() -> Element { + let value = use_store(Default::default); + + rsx! { + Tree { + value + } + } +} + +#[component] +fn Tree(value: Store) -> Element { + // Calling the generated `count` method returns a new store that can only + // read and write the count field + let mut count = value.count(); + let mut children = value.children(); + + rsx! { + button { + // Incrementing the count will only rerun parts of the app that have read the count field + onclick: move |_| count += 1, + "Increment" + } + button { + // Stores are aware of data structures like `Vec` and `Hashmap`. When we push an item to the vec + // it will only rerun the parts of the app that depend on the length of the vec + onclick: move |_| children.push(Default::default()), + "Push child" + } + ul { + // Iterating over the children gives us stores scoped to each child. + for value in children.iter() { + li { + Tree { value } + } + } + } + } +} +``` diff --git a/packages/stores/README.md b/packages/stores/README.md index 71795ac942..dd5ba1efd2 100644 --- a/packages/stores/README.md +++ b/packages/stores/README.md @@ -1,3 +1,4 @@ + # Dioxus Stores Stores are an extension to the Dioxus signals system for reactive nested data structures. Each store will lazily create signals for each field/member of the data structure as needed. @@ -61,4 +62,4 @@ fn Tree(value: Store) -> Element { } } } -``` +``` \ No newline at end of file diff --git a/packages/stores/src/lib.rs b/packages/stores/src/lib.rs index 3d2b8dbf48..87f7b569b7 100644 --- a/packages/stores/src/lib.rs +++ b/packages/stores/src/lib.rs @@ -1,4 +1,4 @@ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![warn(missing_docs)] diff --git a/packages/web/README-docs-rs.md b/packages/web/README-docs-rs.md new file mode 100644 index 0000000000..29f32b3348 --- /dev/null +++ b/packages/web/README-docs-rs.md @@ -0,0 +1,43 @@ +# Dioxus-web + +[![Crates.io][crates-badge]][crates-url] +[![MIT licensed][mit-badge]][mit-url] +[![Build Status][actions-badge]][actions-url] +[![Discord chat][discord-badge]][discord-url] + +[crates-badge]: https://img.shields.io/crates/v/dioxus-web.svg +[crates-url]: https://crates.io/crates/dioxus-web +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM + +[Website](https://dioxuslabs.com) | +[Guides](https://dioxuslabs.com/learn/0.6/) | +[API Docs](https://docs.rs/dioxus-web/latest/dioxus_web) | +[Chat](https://discord.gg/XgGxMSkvUM) + +## Overview + +Run Dioxus in the browser using WebAssembly. + +- Relies on [sledgehammer-bindgen](https://github.com/Demonthos/sledgehammer_bindgen) and [web-sys](https://github.com/rustwasm/wasm-bindgen/tree/main/crates/web-sys) to modify the dom +- Supports instant hot reloading via the Dioxus CLI +- Around 60k gzipped + +## Contributing + +- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues). +- Join the discord and ask questions! + +## License + +This project is licensed under the [MIT license]. + +[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Dioxus by you shall be licensed as MIT without any additional +terms or conditions. diff --git a/packages/web/README.md b/packages/web/README.md index 29f32b3348..1d02534fb1 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -1,3 +1,4 @@ + # Dioxus-web [![Crates.io][crates-badge]][crates-url] @@ -5,15 +6,6 @@ [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] -[crates-badge]: https://img.shields.io/crates/v/dioxus-web.svg -[crates-url]: https://crates.io/crates/dioxus-web -[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg -[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT -[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg -[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster -[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square -[discord-url]: https://discord.gg/XgGxMSkvUM - [Website](https://dioxuslabs.com) | [Guides](https://dioxuslabs.com/learn/0.6/) | [API Docs](https://docs.rs/dioxus-web/latest/dioxus_web) | @@ -36,8 +28,16 @@ Run Dioxus in the browser using WebAssembly. This project is licensed under the [MIT license]. -[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT - Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions. + +[crates-badge]: https://img.shields.io/crates/v/dioxus-web.svg +[crates-url]: https://crates.io/crates/dioxus-web +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT +[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg +[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster +[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square +[discord-url]: https://discord.gg/XgGxMSkvUM +[MIT license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT \ No newline at end of file diff --git a/packages/web/src/lib.rs b/packages/web/src/lib.rs index d851f35e0a..46ded3751c 100644 --- a/packages/web/src/lib.rs +++ b/packages/web/src/lib.rs @@ -1,9 +1,8 @@ +#![doc = include_str!("../README-docs-rs.md")] #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![deny(missing_docs)] -//! # Dioxus Web - use std::time::Duration; pub use crate::cfg::Config; From e032ebbe883b1ca00dc9b88dfb5ac6636ad64685 Mon Sep 17 00:00:00 2001 From: Evan Almloff Date: Fri, 8 Aug 2025 15:30:31 -0500 Subject: [PATCH 2/4] fix msrv --- packages/crates-io-readme/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/crates-io-readme/Cargo.toml b/packages/crates-io-readme/Cargo.toml index 5ce7be865c..0a96eb25b4 100644 --- a/packages/crates-io-readme/Cargo.toml +++ b/packages/crates-io-readme/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "crates-io-readme" version = "0.1.0" -edition = "2024" +edition = "2021" publish = false [dependencies] From 52d08a66d4e8539b104f8d13574b468094c857e4 Mon Sep 17 00:00:00 2001 From: Evan Almloff Date: Fri, 8 Aug 2025 15:56:32 -0500 Subject: [PATCH 3/4] fix doc tests --- Cargo.lock | 1 + packages/crates-io-readme/Cargo.toml | 1 + packages/crates-io-readme/src/main.rs | 24 ++++++++++++++++++++++-- packages/logger/README-docs-rs.md | 14 ++++++++------ packages/logger/README.md | 4 ++-- 5 files changed, 34 insertions(+), 10 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 06aeafae3d..ad8a17a355 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4226,6 +4226,7 @@ name = "crates-io-readme" version = "0.1.0" dependencies = [ "anyhow", + "ignore", "pulldown-cmark", "pulldown-cmark-to-cmark", "walkdir", diff --git a/packages/crates-io-readme/Cargo.toml b/packages/crates-io-readme/Cargo.toml index 0a96eb25b4..6b969d7cd3 100644 --- a/packages/crates-io-readme/Cargo.toml +++ b/packages/crates-io-readme/Cargo.toml @@ -9,3 +9,4 @@ pulldown-cmark = { version = "0.13.0", default-features = false, features = ["si anyhow = "1.0" walkdir = "2.5" pulldown-cmark-to-cmark = "21.0.0" +ignore = "0.4.23" diff --git a/packages/crates-io-readme/src/main.rs b/packages/crates-io-readme/src/main.rs index 4be68ba0f5..a362f284cc 100644 --- a/packages/crates-io-readme/src/main.rs +++ b/packages/crates-io-readme/src/main.rs @@ -8,6 +8,7 @@ /// cargo run --package crates-io-readme /// ``` use anyhow::{Context, Result}; +use ignore::gitignore; use pulldown_cmark::{CodeBlockKind, Event, Tag, TagEnd}; use std::fs; use std::path::Path; @@ -15,9 +16,28 @@ use walkdir::WalkDir; fn main() -> Result<()> { let current_dir = std::env::current_dir()?; + // walk up looking for a git root + let mut git_root = current_dir.as_path(); + while !git_root.join(".git").exists() { + if let Some(parent) = git_root.parent() { + git_root = parent; + } else { + break; + } + } + let git_folder = git_root.join(".git"); + let gitignore_path = git_root.join(".gitignore"); + + // Ignore files in the gitignore + let (ignore, _) = ignore::gitignore::Gitignore::new(&gitignore_path); // Process all markdown files in the current directory - for entry in WalkDir::new(¤t_dir) { + for entry in WalkDir::new(¤t_dir).into_iter().filter_entry(|e| { + let path = e.path(); + let is_dir = path.is_dir(); + // Ignore files in the gitignore + ignore.matched(path, is_dir).is_none() && !path.starts_with(&git_folder) + }) { let entry = entry?; let path = entry.path(); @@ -27,7 +47,7 @@ fn main() -> Result<()> { .and_then(|s| s.to_str()) .unwrap_or_default(); if let Some(base_name) = stem_name.strip_suffix("-docs-rs") { - process_markdown_file(&path, &path.with_file_name(base_name).with_extension("md"))?; + process_markdown_file(path, &path.with_file_name(base_name).with_extension("md"))?; } } } diff --git a/packages/logger/README-docs-rs.md b/packages/logger/README-docs-rs.md index 2c322ada7c..de62524b94 100644 --- a/packages/logger/README-docs-rs.md +++ b/packages/logger/README-docs-rs.md @@ -21,12 +21,11 @@
------ +--- `dioxus-logger` is a basic cross-platform facade for logging in [Dioxus](https://dioxuslabs.com/) that uses the [tracing](https://crates.io/crates/tracing) crate. - -```rust +```rust, no_run use dioxus::prelude::*; use dioxus_logger::tracing::{Level, info}; @@ -48,7 +47,7 @@ fn App() -> Element { As of v0.6, dioxus_logger is part of dioxus itself. Dioxus will call `init` with a default Level, though you can still override the default with `init`. -```rust +```rust, no_run use dioxus::prelude::*; use dioxus::logger::tracing::{Level, info}; @@ -65,23 +64,26 @@ fn App() -> Element { } } ``` + For non-wasm targets, runtime filtering is based on the `RUST_LOG` environment variable. e.g. for `RUST_LOG=none,crateName=trace` only logs trace and above for `crateName` will be captured. See [here](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives) for syntax. For crates with `-` in the name, these need to be changed to `_` in `RUST_LOG`. ## Platform Support + Dioxus logger will eventually support every target that Dioxus does. Currently mobile and TUI are not supported. ## Installation -`dioxus_logger` is part of Dioxus v0.6. If you're using Dioxus v0.6, then no installation is required! +`dioxus_logger` is part of Dioxus v0.6. If you're using Dioxus v0.6, then no installation is required! If you're on Dioxus v0.5 and below, you can add `dioxus-logger` to your application by adding it to your dependencies. + ```toml [dependencies] dioxus-logger = "0.5" ``` - ## License + This project is licensed under the [MIT license]. [mit license]: ./LICENSE diff --git a/packages/logger/README.md b/packages/logger/README.md index a288f55315..d36c9cbfbc 100644 --- a/packages/logger/README.md +++ b/packages/logger/README.md @@ -26,7 +26,7 @@ `dioxus-logger` is a basic cross-platform facade for logging in [Dioxus](https://dioxuslabs.com/) that uses the [tracing](https://crates.io/crates/tracing) crate. -```rust +```rust, no_run use dioxus::prelude::*; use dioxus_logger::tracing::{Level, info}; @@ -48,7 +48,7 @@ fn App() -> Element { As of v0.6, dioxus_logger is part of dioxus itself. Dioxus will call `init` with a default Level, though you can still override the default with `init`. -```rust +```rust, no_run use dioxus::prelude::*; use dioxus::logger::tracing::{Level, info}; From 1eaf61897efe8e402571a851d60859d92419d0b4 Mon Sep 17 00:00:00 2001 From: Evan Almloff Date: Fri, 8 Aug 2025 15:57:33 -0500 Subject: [PATCH 4/4] remove unused import --- packages/crates-io-readme/src/main.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/crates-io-readme/src/main.rs b/packages/crates-io-readme/src/main.rs index a362f284cc..03d12eb149 100644 --- a/packages/crates-io-readme/src/main.rs +++ b/packages/crates-io-readme/src/main.rs @@ -8,7 +8,6 @@ /// cargo run --package crates-io-readme /// ``` use anyhow::{Context, Result}; -use ignore::gitignore; use pulldown_cmark::{CodeBlockKind, Event, Tag, TagEnd}; use std::fs; use std::path::Path;