Ideas for improvements

[qknight]

I'm trying to port my app from client side rendering CSR into server side rendering SSR with the help of this repository.

The documentation in https://book.leptos.dev/ssr/index.html is fairly limited, for instance:

• https://book.leptos.dev/server/25_server_functions.html (this got me confused because i wonder: is this about SSR or any other server function?) Please add a sentence at the top like:

(as outlined with the red error, move this text down) and extend this text:

Leptos is one of a number of modern frameworks that introduce the concept of server functions. Server side rendering (SSR) is archived with a combination of a server function and a leptos component using it.

Concepts to teach

Using SSR means that we still work on a GET request basis (like in PHP) so we can't use signals the way we can in CSR mode. SSR still supports the concept of signals, but they are on a 'per-request-basis' and have a rather short time-span to live.

You can use leptos with CSR without accessing remote resources this way you can store data in the localStore of your browser. If you want to access remote data from a server in CSR, these are your options:

• you access a REST interface, like a JSON API
• you can use Websockets

Leptos with SSR offers these concepts:

• on the server, we read/write to and from a database using crates like sqlx, and create the webpage based on that. Page updates are explicitly done when the user using F5 (reload). This shows changes other users caused to the database.
  See https://github.com/leptos-rs/leptos/blob/main/examples/todo_app_sqlite_axum/src/todo.rs
• or we can stream updates using websockets! See https://github.com/leptos-rs/leptos/tree/main/examples/websocket

Create new example from examples

I'm coming from leptos CSR with server data coming via REST. The leptos SSR concepts are new for me and I am used to:

• passing huge amounts of RwSignals/Signals down different routes (they embody the global state of the application and can be updated using calls to external REST) - SSR would use a database for global state and WS for server push.
• I use <Router><Routes fallback=|| "Not found."> ... but leptos SSR requires a rewrite into rust functions.

But reading https://github.com/leptos-rs/leptos/blob/main/examples/websocket confuses me greatly:

• Having main.rs, lib.rs and websocket.rs with all the different entry points
• The SSR router works differently than CSR

Extending the book

The book should be a continuous story of small extensions to the template starting with https://github.com/leptos-rs/start-axum-workspace and then:

1. create a router 2 "/" (home) and "/todos"
2. extend it with a function fn gen_content_from_server() which is running on the server only and called from a component on the UI
3. extend the server core routine with a context, for server variables and then use that in fn gen_content_from_server()
4. create a function which is only evaluated on the client
5. extend the server with a db like sqlite and extend fn gen_content_from_server() to get data from the db
6. create fn my_editor_component which loads and saves data from a fn on the server but uses a client side only editor
7. extend server and client with a websocket and have a todo list which always updates all devices in sync

[gbj]

Just for the sake of clarification: When you started transitioning from CSR to SSR, did you start at the beginning of Part 2: Server Side Rendering and read through the sections following (The Life of a Page Load, Async Rendering and SSR Modes, Hydration Bugs), or go straight to 15.1 Server Functions?

[qknight]

@gbj I read most parts. For example:

• we did not understand why 'cargo leptos serve' did build and serve the correct things with the https://github.com/leptos-rs/start-axum-workspace template:
  it is probably because of this Cargo.toml code:

  # the package in the workspace that contains the server binary (binary crate)
  bin-package = "server"
  
  # the package in the workspace that contains the frontend wasm binary (library crate)
  lib-package = "frontend"
  

• the book is written with CSR in mind and later SSR was added, which means confusion on what to use where. for instance:
  • the template https://github.com/leptos-rs/start-axum-workspace template does not use #[cfg(feature = "ssr")]
  • this example https://github.com/leptos-rs/leptos/blob/main/examples/todo_app_sqlite_axum/src/main.rs has two main functions with lots of macro-magic
• most of the time, when trying something, the rust error messages resulting from the macros where next to no use

don't get me wrong, i love leptos and i want it to succeed but the SSR project of mine, trying to get https://planicus.eu/ (currently CSR) as SSR, failed and i'll pause it for some time.

[gbj]

Okay. So, there are a number of mis-statements or misconceptions in your two posts. I don't want to come across as being pedantic, but I'm going to address as many of them as I can, in the hopes that it's helpful to you or someone else in the future. Please understand I'm not trying to be argumentative, just to correct incorrect information in case it is helpful.

Server side rendering (SSR) is archived with a combination of a server function and a leptos component using it.

This is not accurate. Server functions are not required for server side rendering, and server functions can be used without server side rendering. They are separate features.

Server functions are, specifically, a tool for creating ad hoc API endpoints that are guaranteed to run on the server. That is why the three paragraphs are written in the order they are written. They introduce the problem and then introduce the solution.

Using SSR means that we still work on a GET request basis (like in PHP)

This is not quite right, or at least misleading. A PHP site would only work on a GET request basis, so that you continue going back to the server for new pages as you navigate around the application. Leptos supports hydration, which means that the initial page load is on the server, and all subsequent navigations are done in the browser.

so we can't use signals the way we can in CSR mode.

I'm not sure I understand what this means. You can definitely use signals in the same way you can in CSR mode. If your application is configured correctly to use SSR + hydration, after hydration the entire application behaves as if it is a CSR app, because (after hydration) all the rendering is done on the client.

SSR still supports the concept of signals, but they are on a 'per-request-basis' and have a rather short time-span to live.

This part is true: If you do something like spawn a tokio task on the server that outlives the request/response cycle and then tries to update a signal, that will have no effect. Leptos does not provide a utility that abstracts over websocket connections so you can update a signal in a long-lived task of some kind and have updates pushed to the client, although there are several userland libraries that do that.

The rest of the "Concepts to Teach" header is accurate, but the important thing to know is that these things are true in either CSR or SSR: to fetch data, you can either fetch data using an HTTP request/response, or you can connect to a long-lived server session with a websocket. Server functions provide a useful wrapper around ad hoc API endpoints and that is it.

I'm coming from leptos CSR with server data coming via REST.

You can continue accessing server data via REST while using SSR. SSR is about server-side rendering: you can continue fetching data using the same approach you were before, or you can switch to using server functions if you'd like an ad hoc API.

I am used to passing huge amounts of RwSignals/Signals down different routes (they embody the global state of the application and can be updated using calls to external REST) - SSR would use a database for global state and WS for server push.

This seems like an apples-to-oranges comparison. You have an existing REST API which means you already have a database; if your application already supports websockets it already supports websockets. Replacing a global state signal with a database and websockets does not make sense to me -- it is talking about two totally different layers of your application.

I use <Router><Routes fallback=|| "Not found."> ... but leptos SSR requires a rewrite into rust functions.

The SSR router works differently than CSR

I don't understand this part. Route definitions and the router in general work identically between CSR and SSR.

Or are you talking about .leptos_routes()? In the example you point to, Router::new() in main.rs is the Axum router. The Leptos router gets plugged into Axum with .leptos_router()

the book is written with CSR in mind and later SSR was added

This is not actually true; both CSR and SSR were fully supported when the book was written. It is written in two parts like this because all the features of CSR are also supported in SSR, and you need to know about them.

So having worked through your posts piece by piece, I guess I think things fall into two categories:

1. The key piece of understanding that cargo-leptos builds a) a WASM file from a library from lib.rs with the hydrate feature activated and a hydrate function (or from frontend/src/lib.rs in the workspace template), and b) a server binary from main.rs (or from server/src/main.rs in the workspace template). In single-crate setups, dependencies that are only available on the server can be gated with #[cfg(feature = "ssr")] to make sure they are not compiled for the frontend.
2. Some broader architectural confusion or possibly misconfiguration that I can't quite figure out, in the discussion about global state/signals/databases/websockets and so on.