Difficulty mixing both SSR and CSR support in the same binary

[azriel91]

Heya, I'm having trouble understanding how to write code with the ssr, hydration, and csr feature flags, when I do want to support both SSR and CSR.

Is the following understanding correct?

1. Server Side Rendering (SSR):

   1. Uses cargo-leptos to build both the server binary, and the WASM module.

   2. Functions which should only be compiled for the server binary can be tagged with #[cfg(feature = "ssr")] attribute.

   3. The #[leptos::server] proc macro probably does this behind the scenes.

   4. In lib.rs, we should use leptos_mount::hydrate_body:

      #[cfg(feature = "hydrate")]
      #[wasm_bindgen::prelude::wasm_bindgen]
      pub fn hydrate() {
          use crate::app::App;
          console_error_panic_hook::set_once();
          leptos::mount::hydrate_body(App);
      }

      as used by server_fns_axum lib.rs.

   5. In main.rs we should use the shell:

      #[cfg(feature = "ssr")]
      async fn main() {
          // ..
          let app = Router::new()
              .leptos_routes(&leptos_options, routes, {
                  let leptos_options = leptos_options.clone();
                  move || shell(leptos_options.clone())
              })
              // ..
      }

      as used by server_fns_axum main.rs.

2. Client Side Rendering (CSR):

   1. Uses trunk to build the WASM module.
   2. Does not support shell, because client side has no knowledge of leptos_options.
   3. There is no need for lib.rs, because CSR uses the entry point in main.rs.
   4. In main.rs, we should use leptos::mount::mount_to_body:

   pub fn main() {
       console_error_panic_hook::set_once();
       leptos::logging::log!("csr mode - mounting to body");
       leptos::mount::mount_to_body(App);
   }

   as used by tailwind_csr main.rs.

3. Thus, a combination of the two would be:

   1. In lib.rs

      // For the client-side, when "ssr" is used.
      #[cfg(feature = "hydrate")]
      #[wasm_bindgen::prelude::wasm_bindgen]
      pub fn hydrate() {
          use crate::app::App;
          console_error_panic_hook::set_once();
          leptos::mount::hydrate_body(App);
      }

   2. In main.rs

      #[cfg(feature = "ssr")]
      async fn main() {
          // ..
          let app = Router::new()
              .leptos_routes(&leptos_options, routes, {
                  let leptos_options = leptos_options.clone();
                  move || shell(leptos_options.clone())
              })
              // ..
      
          // .. axum::serve(listener, app.into_make_service())
      }
      
      #[cfg(feature = "csr")]
      pub fn main() {
          console_error_panic_hook::set_once();
          leptos::logging::log!("csr mode - mounting to body");
          leptos::mount::mount_to_body(App);
      }
      
      // To keep Rust happy when neither "ssr" or "csr" are chosen
      // (but in reality we will always choose one or the other)
      #[cfg(not(any(feature = "ssr", feature = "csr")))]
      pub fn main() {}

4. Other open questions:

   1. Should leptos_meta::provide_meta_context be in the shell or the App component?

   2. Should leptos_meta::provide_meta_context be only in SSR, or should it be in CSR as well?

   3. Should shell only be in SSR, or CSR as well?

   4. Should Router be inside App or shell?

      tailwind_csr app.rs and router suggests in App (or RouterExample -- the top level component with no shell).

   5. Should <Stylesheet ..> and <Link ..> be in App or shell?

      • tailwind_csr app.rs suggests in App.
      • server_fns_axum app.rs suggests in shell.

I figured this would be worth a discussion instead of discord, since it's so difficult to figure out, and is worth keeping it searchable.

[gbj]

I think what you wrote in 1, 2, and 3 sounds accurate. So I'll try to answer the open questions:

Should leptos_meta::provide_meta_context be in the shell or the App component?

App.

Should leptos_meta::provide_meta_context be only in SSR, or should it be in CSR as well?

Both.

Should shell only be in SSR, or CSR as well?

SSR.

Should Router be inside App or shell?

App.

Should <Stylesheet ..> and <Link ..> be in App or shell?

App.

[azriel91]

hm, thanks for this, though I guess I need a bit more clarification on the last one.

Based on code I've seen + reading around:

1. <shell> should contain the <head> section.
2. Normally <head> is where <link> and <stylesheet> are expected to live (says MDN).
3. The app also loads <script>s, which I suspect should also live in <App /> (since they need to also be loaded in CSR mode).
4. For SSR, <AutoReload options=options.clone() /> and <HydrationScripts options /> I'm guessing also need to be loaded in <head>.

These constraints can't coexist:

1. <shell> contains <head>scripts, etc.</head>, and <body><App /></body>.
2. <App /> contains <head>scripts, etc.</head>.

and there are two more constraints that could coexist:

3. SSR needs LeptosOptions to be passed to <head> (which from examples lives in <shell>).
4. CSR doesn't need LeptosOptions to be passed to App.

Which of the following options is most correct:

• Option A:

  1. <shell> has <head><AutoReload .. /><HydrationScripts .. /></head> <body><App /></body> with LeptosOptions.
  2. <App /> the script, link, etc. tags.

• Option B:

  1. <shell> has <head><AutoReload .. /><HydrationScripts .. /><script .. /><link ../></head> <body><App /></body> with LeptosOptions.
  2. <SsrApp /> does not contain <script .. /><Link .. /> etc, and this is passed in to hydrate_body.
  3. CSR uses <CsrApp /> which is like <shell> minute the AutoReload/HydrationScripts components.

• Option C:

  1. Ignore <shell>, just have <App /> which contains <head> and <body>.
  2. Have an <App /> has an optional LeptosOptions prop based on a compilation feature.

[gbj]

Normally <head> is where <link> and <stylesheet> are expected to live

This is true, but I think the conclusions you're drawing/the trains of thought you're going down are based on a misunderstanding. The leptos_meta components <Stylesheet/> and <Link/> can be used anywhere, and insert the appropriate tags into the <head>; that is their primary purpose. Whether you're using them in CSR or in SSR, they will end up in the <head>, wherever in the app you use them.

If you are using Trunk for CSR, your index.html fulfills the same function that the shell function fulfills in SSR mode.

So, if you have a few static stylesheets or <link> tags, you can either

1. use <Stylesheet/> and <Link/> from leptos_meta, which will behave correctly in either SSR or CSR; or
2. put HTML <link> elements in the <head>, in your index.html (CSR) and in your shell

[azriel91]

ahh, clever! (didn't realize the builder placed them in the right place in the final dom structure)

That's certainly what I was missing, and resolves my "it doesn't fit together" conundrum.

Thank you very much for the explanation / clarification 🙇‍♂️!

[gbj]

You're welcome! Happy to help any time :-)