clarify book structure + add necessary explanations

leptos-rs · Nov 21, 2023 · 28869f2 · 28869f2
1 parent a496b2d
commit 28869f2
Show file tree

Hide file tree

Showing 6 changed files with 71 additions and 25 deletions.
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -4,7 +4,7 @@
 - [Getting Started](./getting_started/README.md)
   - [Leptos DX](./getting_started/leptos_dx.md)
   - [The Leptos Community and leptos-* Crates](./getting_started/community_crates.md)
-- [Building User Interfaces](./view/README.md)
+- [Part 1: Building User Interfaces](./view/README.md)
   - [A Basic Component](./view/01_basic_component.md)
   - [Dynamic Attributes](./view/02_dynamic_attributes.md)
   - [Components and Props](./view/03_components.md)
@@ -36,7 +36,8 @@
   - [`<Form/>`](./router/20_form.md)
 - [Interlude: Styling](./interlude_styling.md)
 - [Metadata](./metadata.md)
-- [Server Side Rendering](./ssr/README.md)
+- [Client-Side Rendering: Wrapping Up](./csr_wrapping_up.md)
+- [Part 2: Server Side Rendering](./ssr/README.md)
   - [`cargo-leptos`](./ssr/21_cargo_leptos.md)
   - [The Life of a Page Load](./ssr/22_life_cycle.md)
   - [Async Rendering and SSR “Modes”](./ssr/23_ssr_modes.md)

diff --git a/docs/book/src/csr_wrapping_up.md b/docs/book/src/csr_wrapping_up.md
@@ -0,0 +1,26 @@
+# Wrapping Up Part 1: Client-Side Rendering
+
+So far, everything we’ve written has been rendered almost entirely in the browser. When we create an app using Trunk, it’s served using a local development server. If you build it for production and deploy it, it’s served by whatever server or CDN you’re using. In either case, what’s served is an HTML page with
+
+1. the URL of your Leptos app, which has been compiled to WebAssembly (WASM)
+2. the URL of the JavaScript used to initialized this WASM blob
+3. an empty `<body>` element
+
+When the JS and WASM have loaded, Leptos will render your app into the `<body>`. This means that nothing appears on the screen until JS/WASM have loaded and run. This has some drawbacks:
+
+1. It increases load time, as your user’s screen is blank until additional resources have been downloaded.
+2. It’s bad for SEO, as load times are longer and the HTML you serve has no meaningful content.
+3. It’s broken for users for whom JS/WASM don’t load for some reason (e.g., they’re on a train and just went into a tunnel before WASM finished loading; they’re using an older device that doesn’t support WASM; they have JavaScript or WASM turned off for some reason; etc.)
+
+These downsides apply across the web ecosystem, but especially to WASM apps.
+
+However, depending the on the requirements of your project, you may be fine with these limitations.
+
+If you just want to deploy your Client-Side Rendered website, skip ahead to the chapter on ["Deployment"](https://leptos-rs.github.io/leptos/deployment/index.html) - there, you'll find directions on how best to deploy your Leptos CSR site.
+
+
+But what do you do if you want to return more than just an empty `<body>` tag in your `index.html` page? Use “Server-Side Rendering”!
+
+Whole books could be (and probably have been) written about this topic, but at its core, it’s really simple: rather than returning an empty `<body>` tag, with SSR, you'll return an initial HTML page that reflects the actual starting state of your app or site, so that while JS/WASM are loading, and until they load, the user can access the plain HTML version.
+
+Part 2 of this book, on Leptos SSR, will cover this topic in some detail!
diff --git a/docs/book/src/getting_started/README.md b/docs/book/src/getting_started/README.md
@@ -5,17 +5,32 @@ There are two basic paths to getting started with Leptos:
 1. Client-side rendering with [Trunk](https://trunkrs.dev/) - a great option if you just want to make a snappy website with Leptos, or work with a pre-existing server or 3rd-party API's.
 2. Full-stack / Universal server-side rendering with [`cargo-leptos`](https://github.com/leptos-rs/cargo-leptos) - a great option for building a CRUD-style website or a web-app with Rust powering both frontend and backend. Universal apps rely on either Actix-web or Axum on the server (so you may want to keep their docs handy, too), or you can even go Universal WASM/WASI with the Leptos and Axum integration (more on these options later).
 
-In Part 1 of this book, we'll start with Client-side rendering Leptos sites and building reactive UI's using `Trunk` to serve our JS+Wasm bundle to the browser.
+In Part 1 of this book, we'll start with Client-side rendering  Leptos sites and building reactive UI's using `Trunk` to serve our JS+Wasm bundle to the browser.
 
 We’ll introduce `cargo-leptos` in Part 2 of this book, which is all about working with the full power of Leptos in its Full-stack, SSR mode.
 
-If you don’t already have it installed, you can install Trunk by running
+```admonish note
+If you're coming from the Javascript world and terms like Client-Side Rendering (CSR) and server-side rendering (SSR) are unfamiliar to you, the easiest way to understand the difference is by analogy:
+
+CSR is similar to working with React (or a 'signals'-based framework like SolidJS), and focuses on producing a client-side UI which you can use with any tech stack on the server.
+
+SSR is like working with a full-stack framework like Next.js in the React world (or Solid's "SolidStart" framework) - SSR helps you build sites and apps using JS on both the client and the server.
+
+Leptos is similar: you can use it to either just make your UI, or you can use full-stack / 'Universal' Leptos to build an app powered by Rust on both client and server.
+
+```
+
+## Hello World! Getting Set up for Leptos CSR Development
+
+First up, make sure Rust is installed and up-to-date ([see here if you need instructions](https://www.rust-lang.org/tools/install)).
+
+If you don’t have it installed already, you can install the "Trunk" tool for running Leptos CSR sites by running the following on the command-line:
 
 ```bash
 cargo install trunk
 ```
 
-Create a basic Rust project
+And then create a basic Rust project
 
 ```bash
 cargo init leptos-tutorial
@@ -97,4 +112,9 @@ Trunk should automatically compile your app and open it in your default browser.
 If you make edits to `main.rs`, Trunk will recompile your source code and
 live-reload the page.
 
-But before we get started building UI's, there's a couple of things you might want to know to help make your experience with Leptos a little bit smoother.
+
+Welcome to the world of UI development with Rust and WebAssembly (WASM), powered by Leptos and Trunk!
+
+---
+
+Now before we get started building your first real UI's with Leptos, there's a couple of things you might want to know to help make your experience with Leptos just a little bit easier.
diff --git a/docs/book/src/getting_started/community_crates.md b/docs/book/src/getting_started/community_crates.md
@@ -2,15 +2,15 @@
 
 ## The Community
 
-One final note before we get to building with Leptos: if you haven't already, feel free to join the growing community on the Leptos Discord and on Github. Our Discord channel in particular is very active and friendly - we'd love to have you there!
+One final note before we get to building with Leptos: if you haven't already, feel free to join the growing community on the Leptos [Discord](https://discord.gg/YdRAhS7eQB) and on [Github](https://github.com/leptos-rs/leptos). Our Discord channel in particular is very active and friendly - we'd love to have you there!
 
 ```admonish note
 If you find a chapter or an explanation that isn't clear while you're working your way through the Leptos book, just mention it in the "docs-and-education" channel or ask a question in "help" so we can clear things up and update the book for others.
 ```
 
 As you get further along in your Leptos journey and find that you have questions about "how to do 'x' with Leptos", then search the Discord "help" channel to see if a similar question has been asked before, or feel free to post your own question - the community is quite helpful and very responsive.
 
-The "[Discussions](https://github.com/leptos-rs/leptos/discussions)" on Githbub are also a great place for asking questions and keeping up with Leptos announcements.
+The "[Discussions](https://github.com/leptos-rs/leptos/discussions)" on Github are also a great place for asking questions and keeping up with Leptos announcements.
 
 And of course, if you run into any bugs while developing with Leptos or would like to make a feature request (or contribute a bug fix / new feature), open up an issue on the [Github issue tracker](https://github.com/leptos-rs/leptos/issues).
 

diff --git a/docs/book/src/ssr/README.md b/docs/book/src/ssr/README.md
@@ -1,21 +1,19 @@
-# Server Side Rendering
+# Part 2: Server Side Rendering
 
-So far, everything we’ve written has been rendered almost entirely in the browser. When we create an app using Trunk, it’s served using a local development server. If you build it for production and deploy it, it’s served by whatever server or CDN you’re using. In either case, what’s served is an HTML page with
+The second part of the book is all about how to turn your beautiful UI's into full-stack, "Universal" Rust + Leptos powered websites and applications.
 
-1. the URL of your Leptos app, which has been compiled to WebAssembly (WASM)
-2. the URL of the JavaScript used to initialized this WASM blob
-3. an empty `<body>` element
+As you read in the last chapter, there are some limitations to using Client-Side Rendered Leptos apps - over the next few chapters, you'll see how we can overcome those limitations
+and get the best performance and SEO out of your Leptos apps.
 
-When the JS and WASM have loaded, Leptos will render your app into the `<body>`. This means that nothing appears on the screen until JS/WASM have loaded and run. This has some drawbacks:
+Let's see how we can use the full power of Leptos and Rust on the server to make your next cutting-edge application!
 
-1. It increases load time, as your user’s screen is blank until additional resources have been downloaded.
-2. It’s bad for SEO, as load times are longer and the HTML you serve has no meaningful content.
-3. It’s broken for users for whom JS/WASM don’t load for some reason (e.g., they’re on a train and just went into a tunnel before WASM finished loading; they’re using an older device that doesn’t support WASM; they have JavaScript or WASM turned off for some reason; etc.)
 
-These downsides apply across the web ecosystem, but especially to WASM apps.
+```admonish info
 
-So what do you do if you want to return more than just an empty `<body>` tag? Use “server-side rendering.”
+When working with Leptos on the server side, you're free to choose either the Actix-web or the Axum integrations - the full feature set of Leptos is available with either option.
 
-Whole books could be (and probably have been) written about this topic, but at its core, it’s really simple: rather than returning an empty `<body>` tag, return an initial HTML page that reflects the actual starting state of your app or site, so that while JS/WASM are loading, and until they load, the user can access the plain HTML version.
+If, however, you need deploy to a WinterCG-compatible runtime like Deno, Cloudflare, etc., then choose the Axum integration as this deployment option is only available with Axum on the server. Lastly, if you'd like to go full-stack WASM/WASI and deploy to WASM-based serverless runtimes, then Axum is your go-to choice here too.
 
-The rest of this section will cover this topic in some detail!
+NB: this is a limitation of the web frameworks themselves, not Leptos.
+
+```
diff --git a/docs/book/src/view/README.md b/docs/book/src/view/README.md
@@ -1,5 +1,6 @@
-# Building User Interfaces
+# Part 1: Building User Interfaces
 
-This first section will introduce you to the basic tools you need to build a reactive
-user interface using Leptos. By the end of this section, you should be able to 
-build a simple, synchronous application that is rendered in the browser.
+In the first part of the book, we're going to look at building user interfaces on the client-side using Leptos. Under the hood, Leptos and Trunk are bundling up a snippet of Javascript which will load up the Leptos UI, which has been compiled to WebAssembly to drive the interactivity in your CSR (client-side rendered) website.
+
+Part 1 will introduce you to the basic tools you need to build a reactive user interface powered by Leptos and Rust. By the end of Part 1, you should be able to
+build a snappy synchronous website that's rendered in the browser and which you can deploy on any static-site hosting service, like Github Pages or Vercel.