diff --git a/packages/server/Cargo.toml b/packages/server/Cargo.toml index fddeccbde..8709cb57d 100644 --- a/packages/server/Cargo.toml +++ b/packages/server/Cargo.toml @@ -2,6 +2,12 @@ name = "dioxus-server" version = "0.1.0" edition = "2021" +description = "Fullstack Dioxus Utilities" +license = "MIT/Apache-2.0" +repository = "https://github.com/DioxusLabs/dioxus/" +homepage = "https://dioxuslabs.com" +documentation = "https://dioxuslabs.com" +keywords = ["dom", "ui", "gui", "react", "ssr", "fullstack"] # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html diff --git a/packages/server/README.md b/packages/server/README.md new file mode 100644 index 000000000..92f878684 --- /dev/null +++ b/packages/server/README.md @@ -0,0 +1,103 @@ +# Dioxus Server + +[![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-server.svg +[crates-url]: https://crates.io/crates/dioxus-server +[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg +[mit-url]: https://github.com/dioxuslabs/dioxus/blob/master/LICENSE +[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/docs/0.3/guide/en/) | +[API Docs](https://docs.rs/dioxus-server/latest/dioxus_sever) | +[Chat](https://discord.gg/XgGxMSkvUM) + +Fullstack utilities for the [`Dioxus`](https://dioxuslabs.com) framework. + +# Features + +- Intigrations with the [Axum](https::/docs.rs/dioxus-server/latest/dixous_server/axum_adapter/index.html), [Salvo](https::/docs.rs/dioxus-server/latest/dixous_server/salvo_adapter/index.html), and [Warp](https::/docs.rs/dioxus-server/latest/dixous_server/warp_adapter/index.html) server frameworks with utilities for serving and rendering Dioxus applications. +- [Server functions](https::/docs.rs/dioxus-server/latest/dixous_server/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). + +# Example + +Full stack Dioxus in under 50 lines of code + +```rust +#![allow(non_snake_case)] +use dioxus::prelude::*; +use dioxus_server::prelude::*; + +fn main() { + #[cfg(feature = "web")] + dioxus_web::launch_cfg(app, dioxus_web::Config::new().hydrate(true)); + #[cfg(feature = "ssr")] + { + GetMeaning::register().unwrap(); + tokio::runtime::Runtime::new() + .unwrap() + .block_on(async move { + warp::serve( + // Automatically handles server side rendering, hot reloading intigration, and hosting server functions + serve_dioxus_application( + "", + ServeConfigBuilder::new(app, ()), + ) + ) + .run(([127, 0, 0, 1], 8080)) + .await; + }); + } +} + +fn app(cx: Scope) -> Element { + let meaning = use_state(cx, || None); + cx.render(rsx! { + button { + onclick: move |_| { + to_owned![meaning]; + async move { + if let Ok(data) = get_meaning("life the universe and everything".into()).await { + meaning.set(data); + } + } + }, + "Run a server function" + } + "Server said: {meaning:?}" + }) +} + +// This code will only run on the server +#[server(GetMeaning)] +async fn get_meaning(of: String) -> Result, ServerFnError> { + Ok(of.contains("life").then(|| 42)) +} +``` + +## Getting Started + +To get started with full stack Dioxus, check out our [getting started guide](https://dioxuslabs.com/docs/nightly/guide/en/getting_started/ssr.html), or the [full stack examples](https://github.com/DioxusLabs/dioxus/tree/master/packages/server/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/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/server/server-macro/src/lib.rs b/packages/server/server-macro/src/lib.rs index e34a440d4..14fc0ac77 100644 --- a/packages/server/server-macro/src/lib.rs +++ b/packages/server/server-macro/src/lib.rs @@ -19,7 +19,7 @@ use server_fn_macro::*; /// work without WebAssembly, the encoding must be `"Url"`. /// /// The server function itself can take any number of arguments, each of which should be serializable -/// and deserializable with `serde`. Optionally, its first argument can be a [DioxusServerContext](https::/docs.rs/dioxus_server/latest/dixous_server/prelude/struct.DioxusServerContext.html), +/// and deserializable with `serde`. Optionally, its first argument can be a [DioxusServerContext](https::/docs.rs/dioxus-server/latest/dixous_server/prelude/struct.DioxusServerContext.html), /// which will be injected *on the server side.* This can be used to inject the raw HTTP request or other /// server-side context into the server function. /// @@ -50,8 +50,8 @@ use server_fn_macro::*; /// They are serialized as an `application/x-www-form-urlencoded` /// form data using [`serde_urlencoded`](https://docs.rs/serde_urlencoded/latest/serde_urlencoded/) or as `application/cbor` /// using [`cbor`](https://docs.rs/cbor/latest/cbor/). -/// - **The [DioxusServerContext](https::/docs.rs/dioxus_server/latest/dixous_server/prelude/struct.DioxusServerContext.html) comes from the server.** Optionally, the first argument of a server function -/// can be a [DioxusServerContext](https::/docs.rs/dioxus_server/latest/dixous_server/prelude/struct.DioxusServerContext.html). This scope can be used to inject dependencies like the HTTP request +/// - **The [DioxusServerContext](https::/docs.rs/dioxus-server/latest/dixous_server/prelude/struct.DioxusServerContext.html) comes from the server.** Optionally, the first argument of a server function +/// can be a [DioxusServerContext](https::/docs.rs/dioxus-server/latest/dixous_server/prelude/struct.DioxusServerContext.html). This scope can be used to inject dependencies like the HTTP request /// or response or other server-only dependencies, but it does *not* have access to reactive state that exists in the client. #[proc_macro_attribute] pub fn server(args: proc_macro::TokenStream, s: TokenStream) -> TokenStream { diff --git a/packages/server/src/lib.rs b/packages/server/src/lib.rs index 4738ef00f..c61b26429 100644 --- a/packages/server/src/lib.rs +++ b/packages/server/src/lib.rs @@ -1,64 +1,7 @@ -//! Fullstack utilities for the [`dioxus`](https://dioxuslabs.com) framework. -//! -//! # Features -//! - Intigrations with the [axum](crate::adapters::axum_adapter), [salvo](crate::adapters::salvo_adapter), and [warp](crate::adapters::warp_adapter) server frameworks with utilities for serving and rendering Dioxus applications. -//! - [Server functions](crate::prelude::server) that 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). -//! -//! # Example -//! Full stack Dioxus in under 50 lines of code -//! ```rust -//! #![allow(non_snake_case)] -//! use dioxus::prelude::*; -//! use dioxus_server::prelude::*; -//! -//! fn main() { -//! #[cfg(feature = "web")] -//! dioxus_web::launch_cfg(app, dioxus_web::Config::new().hydrate(true)); -//! #[cfg(feature = "ssr")] -//! { -//! GetMeaning::register().unwrap(); -//! tokio::runtime::Runtime::new() -//! .unwrap() -//! .block_on(async move { -//! warp::serve(serve_dioxus_application( -//! "", -//! ServeConfigBuilder::new(app, ()), -//! )) -//! .run(([127, 0, 0, 1], 8080)) -//! .await; -//! }); -//! } -//! } -//! -//! fn app(cx: Scope) -> Element { -//! let meaning = use_state(cx, || None); -//! cx.render(rsx! { -//! button { -//! onclick: move |_| { -//! to_owned![meaning]; -//! async move { -//! if let Ok(data) = get_meaning("life the universe and everything".into()).await { -//! meaning.set(data); -//! } -//! } -//! }, -//! "Run a server function" -//! } -//! "Server said: {meaning:?}" -//! }) -//! } -//! -//! // This code will only run on the server -//! #[server(GetMeaning)] -//! async fn get_meaning(of: String) -> Result, ServerFnError> { -//! Ok(of.contains("life").then(|| 42)) -//! } -//! ``` - -#![warn(missing_docs)] -#[allow(unused)] -use dioxus_core::prelude::*; +#![doc = include_str!("../README.md")] +#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] +#![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] +#![deny(missing_docs)] pub use adapters::*;