feat: provide api to customize server address (#5263)

Users who need to control the server address
programmatically are forced to use
std::env::set_var("PORT", ...), which is unsafe
in Rust edition 2024.

Adds serve_at(addr, cb) as a safe alternative.
serve() now delegates to it internally.

Author: seflue

examples/07-fullstack/custom_axum_serve.rs

@@ -11,9 +11,9 @@
 //! `dioxus::serve` is most useful for customizing the server setup, such as adding middleware,
 //! custom routes, or integrating with existing axum backend code.
 //!
-//! Note that `dioxus::serve` is accepts a Router from `axum`. Dioxus will use the IP and PORT
+//! Note that `dioxus::serve` accepts a Router from `axum`. Dioxus will use the IP and PORT
 //! environment variables to determine where to bind the server. To customize the port, use environment
-//! variables or a `.env` file.
+//! variables, a `.env` file, or `dioxus::serve_at` to pass a `SocketAddr` directly.
 //!
 //! On other platforms (like desktop or mobile), you'll want to use `dioxus::launch` instead and then
 //! handle async loading of data through hooks like `use_future` or `use_resource` and give the user

packages/dioxus/src/lib.rs

@@ -88,6 +88,9 @@ pub use dioxus_server as server;
 #[cfg(feature = "server")]
 pub use dioxus_server::serve;
 
+#[cfg(feature = "server")]
+pub use dioxus_server::serve_at;
+
 #[cfg(feature = "devtools")]
 #[cfg_attr(docsrs, doc(cfg(feature = "devtools")))]
 pub use dioxus_devtools as devtools;
@@ -215,7 +218,7 @@ pub mod prelude {
     #[cfg(feature = "server")]
     #[cfg_attr(docsrs, doc(cfg(feature = "server")))]
     #[doc(inline)]
-    pub use dioxus_server::{self, DioxusRouterExt, ServeConfig, ServerFunction, serve};
+    pub use dioxus_server::{self, DioxusRouterExt, ServeConfig, ServerFunction, serve, serve_at};
 
     #[cfg(feature = "router")]
     #[cfg_attr(docsrs, doc(cfg(feature = "router")))]

packages/fullstack-server/src/launch.rs

@@ -111,16 +111,41 @@ pub fn router(app: fn() -> Element) -> Router {
 /// The axum router will be bound to the address specified by the `IP` and `PORT` environment variables,
 /// defaulting to `127.0.0.1:8080` if not set.
 ///
+/// To bind to a specific address, use [`serve_at`] instead.
+///
+/// This function uses axum to block on serving the application, and will not return.
+pub fn serve<F>(serve_it: impl FnMut() -> F) -> !
+where
+    F: Future<Output = Result<Router, anyhow::Error>> + 'static,
+{
+    serve_at(dioxus_cli_config::fullstack_address_or_localhost(), serve_it)
+}
+
+/// Serve a fullstack dioxus application with a custom axum router, bound to the given address.
+///
+/// This is the same as [`serve`], but allows you to specify the address to bind to programmatically
+/// instead of relying on the `IP` and `PORT` environment variables.
+///
+/// # Example
+///
+/// ```rust,ignore
+/// use std::net::SocketAddr;
+///
+/// let addr = SocketAddr::from(([0, 0, 0, 0], 3000));
+/// dioxus::serve_at(addr, || async {
+///     Ok(dioxus::server::router(app)
+///         .route("/health", axum::routing::get(|| async { "ok" })))
+/// });
+/// ```
+///
 /// This function uses axum to block on serving the application, and will not return.
-pub fn serve<F>(mut serve_it: impl FnMut() -> F) -> !
+pub fn serve_at<F>(addr: SocketAddr, mut serve_it: impl FnMut() -> F) -> !
 where
     F: Future<Output = Result<Router, anyhow::Error>> + 'static,
 {
     let cb = move || Box::pin(serve_it()) as _;
 
-    block_on(
-        async move { serve_router(cb, dioxus_cli_config::fullstack_address_or_localhost()).await },
-    );
+    block_on(async move { serve_router(cb, addr).await });
 
     unreachable!("Serving a fullstack app should never return")
 }

packages/fullstack-server/src/lib.rs

@@ -39,6 +39,7 @@ pub(crate) mod streaming;
 
 pub use launch::router;
 pub use launch::serve;
+pub use launch::serve_at;
 
 pub mod serverfn;
 pub use serverfn::*;