Crate leptos_server
source ·Expand description
Leptos Server Functions
This package is based on a simple idea: sometimes it’s useful to write functions that will only run on the server, and call them from the client.
If you’re creating anything beyond a toy app, you’ll need to do this all the time: reading from or writing to a database that only runs on the server, running expensive computations using libraries you don’t want to ship down to the client, accessing APIs that need to be called from the server rather than the client for CORS reasons or because you need a secret API key that’s stored on the server and definitely shouldn’t be shipped down to a user’s browser.
Traditionally, this is done by separating your server and client code, and by setting up something like a REST API or GraphQL API to allow your client to fetch and mutate data on the server. This is fine, but it requires you to write and maintain your code in multiple separate places (client-side code for fetching, server-side functions to run), as well as creating a third thing to manage, which is the API contract between the two.
This package provides two simple primitives that allow you instead to write co-located, isomorphic server functions. (Co-located means you can write them in your app code so that they are “located alongside” the client code that calls them, rather than separating the client and server sides. Isomorphic means you can call them from the client as if you were simply calling a function; the function call has the “same shape” on the client as it does on the server.)
#[server]
The #[server] macro allows you to annotate a function to
indicate that it should only run on the server (i.e., when you have an ssr feature in your
crate that is enabled).
Important: All server functions must be registered by calling ServerFn::register
somewhere within your main function.
#[server(ReadFromDB)]
async fn read_posts(cx: Scope, how_many: usize, query: String) -> Result<Vec<Posts>, ServerFnError> {
// do some server-only work here to access the database
let posts = ...;
Ok(posts)
}
// call the function
spawn_local(async {
let posts = read_posts(3, "my search".to_string()).await;
log::debug!("posts = {posts{:#?}");
})
// make sure you've registered it somewhere in main
fn main() {
_ = ReadFromDB::register();
}If you call this function from the client, it will serialize the function arguments and POST
them to the server as if they were the inputs in <form method="POST">.
Here’s what you need to remember:
- Server functions must be
async. Even if the work being done inside the function body can run synchronously on the server, from the client’s perspective it involves an asynchronous function call. - Server functions must return
Result<T, ServerFnError>. Even if the work being done inside the function body can’t fail, the processes of serialization/deserialization and the network call are fallible. - Return types must be Serializable. This should be fairly obvious: we have to serialize arguments to send them to the server, and we need to deserialize the result to return it to the client.
- Arguments must be implement serde::Serialize. They are serialized as an
application/x-www-form-urlencodedform data usingserde_urlencodedor asapplication/cborusingcbor. - The Scope comes from the server. Optionally, the first argument of a server function can be a Leptos Scope. 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.
Re-exports
pub use form_urlencoded;Structs
async call to the synchronous reactive system.async calls to the reactive system,
tracking the progress of each one.Enums
Traits
ssr is enabled.Functions
async call to the synchronous reactive system.async call to the synchronous reactive system.