Attribute Macro leptos_macro::server

source · 
#[server]
Expand description

Declares that a function is a server function. This means that its body will only run on the server, i.e., when the ssr feature is enabled.

If you call a server function from the client (i.e., when the csr or hydrate features are enabled), it will instead make a network request to the server.

You can specify one, two, or three arguments to the server function:

  1. Required: A type name that will be used to identify and register the server function (e.g., MyServerFn).
  2. Optional: A URL prefix at which the function will be mounted when it’s registered (e.g., "/api"). Defaults to "/".
  3. Optional: either "Cbor" (specifying that it should use the binary cbor format for serialization) or "Url" (specifying that it should be use a URL-encoded form-data string). Defaults to "Url". If you want to use this server function to power a <form> that will 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 Leptos Scope, 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.

ⓘ
#[server(ReadPosts, "/api")]
pub async fn read_posts(how_many: u8, query: String) -> Result<Vec<Post>, ServerFnError> {
  // do some work on the server to access the database
  todo!()   
}

Note the following:

  • You must register the server function by calling T::register() somewhere in your main function.
  • 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 Serialize and DeserializeOwned. They are serialized as an application/x-www-form-urlencoded form data using serde_urlencoded or as application/cbor using cbor.
  • 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.