doc(examples): reference run instructions (#1705)

.github/workflows/get-changed-examples-matrix.yml

@@ -35,7 +35,7 @@ jobs:
             !examples/cargo-make
             !examples/gtk
             !examples/Makefile.toml
-            !examples/README.md
+            !examples/*.md
           json: true
           quotepath: false
 

examples/README.md

@@ -8,6 +8,27 @@ To the extent that new features have been released or breaking changes have been
 
 To see the examples as they were at the time of the `0.4.9` release, [click here](https://github.com/leptos-rs/leptos/tree/v0.4.9/examples).
 
+## Cargo Make
+
+[Cargo Make](https://sagiegurari.github.io/cargo-make/) is used to build, test, and run examples.
+
+Here are the highlights.
+
+- Extendable custom task files are located in the [cargo-make](./cargo-make/) directory
+- Running a task will automatically install `cargo` dependencies 
+- Each `Makefile.toml` file must extend the [cargo-make/main.toml](./cargo-make/main.toml) file
+- [cargo-make](./cargo-make/) files that end in `*-test.toml` configure web testing strategies
+- Run `cargo make test-report` to learn which examples have web tests
+
+## Getting Started
+
+Follow these steps to get any example up and running.
+
+1. `cd` to the example root directory
+2. Run `cargo make ci` to setup and test the example
+3. Run `cargo make start` to run the example
+4. Open the client URL in the console output (<http://127.0.0.1:8080> or <http://127.0.0.1:3000> by default)
+
 ## Prerequisites
 
 Example projects depend on the following tools. Please install them as needed.
@@ -22,24 +43,3 @@ Example projects depend on the following tools. Please install them as needed.
 - [Node Version Manager](https://github.com/nvm-sh/nvm/) (**_Optional_**)
 - [Node.js](https://nodejs.org/)
 - [pnpm](https://pnpm.io/) (**_Optional_**)
-
-## Getting Started
-
-Follow these steps to get any example up and running.
-
-1. `cd` to the example root directory
-2. Run `cargo make ci` to setup and test the example
-3. Run `cargo make start` to run the example
-4. Open the client URL in the console output (<http://127.0.0.1:8080> or <http://127.0.0.1:3000> by default)
-
-## Cargo Make
-
-[Cargo Make](https://sagiegurari.github.io/cargo-make/) supports `ci` and common development tasks.
-
-Here are the highlights.
-
-- Extendable custom task files are located in the [cargo-make](./cargo-make/) directory
-- Running a task will automatically install `cargo` dependencies 
-- Each `Makefile.toml` file must extend the [cargo-make/main.toml](./cargo-make/main.toml) file
-- [cargo-make](./cargo-make/) files that end in `*-test.toml` configure end-to-end web testing
-- Run `cargo make test-report` to learn which examples have web tests

examples/SSR_NOTES.md

@@ -0,0 +1,68 @@
+# Server Side Rendering
+
+## Cargo Leptos
+
+cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
+
+1. Install cargo-leptos
+
+```bash
+cargo install --locked cargo-leptos
+```
+
+2. Build the site in watch mode, recompiling on file changes
+
+```bash
+cargo leptos watch
+```
+
+Open browser on [http://localhost:3000/](http://localhost:3000/)
+
+3. When ready to deploy, run
+
+```bash
+cargo leptos build --release
+```
+
+## WASM Pack
+
+To run it as a server side app with hydration, you'll need to have wasm-pack installed.
+
+0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. For examples with CSS you also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
+
+1. Install wasm-pack
+
+```bash
+cargo install wasm-pack
+```
+
+2. Build the Webassembly used to hydrate the HTML from the server
+
+```bash
+wasm-pack build --target=web --debug --no-default-features --features=hydrate
+```
+
+3. Run the server to serve the Webassembly, JS, and HTML
+
+```bash
+cargo run --no-default-features --features=ssr
+```
+
+### Server Side Rendering With Hydration
+
+To run it as a server side app with hydration, first you should run
+
+```bash
+wasm-pack build --target=web --debug --no-default-features --features=hydrate
+```
+
+to generate the WebAssembly to hydrate the HTML delivered from the server.
+
+Then run the server with `cargo run` to serve the server side rendered HTML and the WASM bundle for hydration.
+
+```bash
+cargo run --no-default-features --features=ssr
+```
+
+> Note that if your hydration code changes, you will have to rerun the wasm-pack command above before running
+> `cargo run`

examples/animated_show/README.md

@@ -1,9 +1,10 @@
-# `<AnimatedShow>` combined with CSS animations
+# Animated Show Example
 
 This is a very simple example of the `<AnimatedShow>` component.
 
-This component is an extension for the `<Show>` component and it will not take in a fallback, but it will unmount the
+The `<AnimatedShow>` component is an extension for the `<Show>` component and it will not take in a fallback, but it will unmount the component from the DOM after a given duration. This makes it possible to have really easy unmount animations with just
-component from the DOM after a given duration. This makes it possible to have really easy unmount animations with just
 CSS.
 
-Just execute `trunk serve` to start the demo.
+## Getting Started
+
+See the [Examples README](../README.md) for setup and run instructions.

examples/counter/README.md

@@ -2,6 +2,6 @@
 
 This example creates a simple counter in a client side rendered app with Rust and WASM!
 
-To run it, just issue the `trunk serve --open` command in the example root. This will build the app, run it, and open a new browser to serve it.
+## Getting Started
 
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)
+See the [Examples README](../README.md) for setup and run instructions.

examples/counter_isomorphic/README.md

@@ -2,42 +2,6 @@
 
 This example demonstrates how to use a function isomorphically, to run a server side function from the browser and receive a result.
 
-## Client Side Rendering
+## Getting Started
-For this example the server must store the counter state since it can be modified by many users.
-This means it is not possible to produce a working CSR-only version as a non-static server is required.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. For examples with CSS you also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```

examples/counter_url_query/README.md

@@ -2,6 +2,6 @@
 
 This example creates a simple counter whose state is persisted and synced in the url with query params.
 
-To run it, just issue the `trunk serve --open` command in the example root. This will build the app, run it, and open a new browser to serve it.
+## Getting Started
 
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)
+See the [Examples README](../README.md) for setup and run instructions.

examples/counter_without_macros/README.md

@@ -2,6 +2,6 @@
 
 This example is the same like the `counter` but it's written without using macros and can be build with stable Rust.
 
-To run it, just issue the `trunk serve --open` command in the example root. This will build the app, run it, and open a new browser to serve it.
+## Getting Started
 
-Issue the `cargo make test-flow` command to run unit and wasm tests.
+See the [Examples README](../README.md) for setup and run instructions.

examples/counters/README.md

@@ -2,8 +2,6 @@
 
 This example showcases a basic leptos app with many counters. It is a good example of how to setup a basic reactive app with signals and effects, and how to interact with browser events.
 
-## Client Side Rendering
+## Getting Started
 
-To run it as a client-side app, you can issue `trunk serve --open` in the root. This will build the entire app into one CSR bundle.
+See the [Examples README](../README.md) for setup and run instructions.
-
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)

examples/counters_stable/README.md

@@ -2,8 +2,6 @@
 
 This example showcases a basic Leptos app with many counters. It is a good example of how to setup a basic reactive app with signals and effects, and how to interact with browser events. Unlike the other counters example, it will compile on Rust stable, because it has the `stable` feature enabled.
 
-## Client Side Rendering
+## Getting Started
 
-To run it as a client-side app, you can issue `trunk serve --open` in the root. This will build the entire app into one CSR bundle.
+See the [Examples README](../README.md) for setup and run instructions.
-
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)

examples/error_boundary/README.md

@@ -2,6 +2,6 @@
 
 This example shows how to handle basic errors using Leptos.
 
-To run it, just issue the `trunk serve --open` command in the example root. This will build the app, run it, and open a new browser to serve it.
+## Getting Started
 
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)
+See the [Examples README](../README.md) for setup and run instructions.

examples/errors_axum/README.md

@@ -1,41 +1,7 @@
 # Leptos Errors Demonstration with Axum
+
 This example demonstrates how Leptos Errors can work with an Axum backend on a server.
 
-## Client Side Rendering
+## Getting Started
-This example cannot be built as a trunk standalone CSR-only app as it requires the server to send status codes.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```

examples/fetch/README.md

@@ -2,8 +2,6 @@
 
 This example shows how to fetch data from the client in WebAssembly.
 
-## Client Side Rendering
+## Getting Started
 
-To run it as a client-side app, you can issue `trunk serve --open` in the root. This will build the entire app into one CSR bundle.
+See the [Examples README](../README.md) for setup and run instructions.
-
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)

examples/hackernews/README.md

@@ -2,42 +2,6 @@
 
 This example creates a basic clone of the Hacker News site. It showcases Leptos' ability to create both a client-side rendered app, and a server side rendered app with hydration, in a single repository
 
-## Client Side Rendering
+## Getting Started
-To run it as a Client Side App, you can issue  `trunk serve --open` in the root. This will build the entire
-app into one CSR bundle. Make sure you have trunk installed with `cargo install trunk`.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes..
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```

examples/hackernews_axum/README.md

@@ -2,42 +2,6 @@
 
 This example creates a basic clone of the Hacker News site. It showcases Leptos' ability to create both a client-side rendered app, and a server side rendered app with hydration, in a single repository. This repo differs from the main Hacker News example by using Axum as it's server.
 
-## Client Side Rendering
+## Getting Started
-To run it as a Client Side App, you can issue  `trunk serve --open` in the root. This will build the entire
-app into one CSR bundle. Make sure you have trunk installed with `cargo install trunk`.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes..
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```

examples/hackernews_islands_axum/README.md

@@ -2,42 +2,6 @@
 
 This example creates a basic clone of the Hacker News site. It showcases Leptos' ability to create both a client-side rendered app, and a server side rendered app with hydration, in a single repository. This repo differs from the main Hacker News example by using Axum as it's server.
 
-## Client Side Rendering
+## Getting Started
-To run it as a Client Side App, you can issue  `trunk serve --open` in the root. This will build the entire
-app into one CSR bundle. Make sure you have trunk installed with `cargo install trunk`.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes..
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```

examples/js-framework-benchmark/README.md

@@ -3,6 +3,6 @@
 This example is adoptation of code from [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark/tree/master/frameworks/keyed/leptos).
 This example creates a large table with randomized entries, it also shows usage of `template` macro and `For` component.
 
-To run it, just issue the `trunk serve --open` command in the example root. This will build the app, run it, and open a new browser to serve it.
+## Getting Started
 
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)
+See the [Examples README](../README.md) for setup and run instructions.

examples/leptos-tailwind-axum/README.md

@@ -2,101 +2,6 @@
 
 This is a template demonstrating how to integrate [TailwindCSS](https://tailwindcss.com/) with the [Leptos](https://github.com/leptos-rs/leptos) web framework, Axum server, and the [cargo-leptos](https://github.com/akesson/cargo-leptos) tool.
 
-To use it first of all you need to have `cargo-leptos` installed on your machine
+## Getting Started
 
-`cargo install --locked cargo-leptos`
+See the [Examples README](../README.md) for setup and run instructions.
-
-Then run
-
-`npm run watch` (This is a script which basically run the CLI tool to scan your template files for classes and build your CSS.)
-
-and
-
-`cargo leptos watch`
-
-in this directory.
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-You can begin editing your app at `src/app.rs`.
-
-## Installing Tailwind
-
-You can install Tailwind using `npm`:
-
-```bash
-npm install -D tailwindcss
-```
-
-If you'd rather not use `npm`, you can install the Tailwind binary [here](https://github.com/tailwindlabs/tailwindcss/releases).
-
-## Setting up with VS Code and Additional Tools
-
-If you're using VS Code, add the following to your `settings.json`
-
-```json
-  "emmet.includeLanguages": {
-    "rust": "html",
-    "*.rs": "html"
-  },
-  "tailwindCSS.includeLanguages": {
-      "rust": "html",
-      "*.rs": "html"
-  },
-  "files.associations": {
-      "*.rs": "rust"
-  },
-  "editor.quickSuggestions": {
-    "other": "on",
-    "comments": "on",
-    "strings": true
-  },
-  "css.validate": false,
-```
-
-Install [Tailwind CSS Intellisense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss).
-
-    Install "VS Browser" extension, a browser at the right window.
-    Allow vscode Ports forward: 3000, 3001.
-
-## Notes about Tooling
-
-By default, `cargo-leptos` uses `nightly` Rust, `cargo-generate`, and `sass`. If you run into any trouble, you may need to install one or more of these tools.
-
-1. `rustup toolchain install nightly --allow-downgrade` - make sure you have Rust nightly
-2. `rustup default nightly` - setup nightly as default, or you can use rust-toolchain file later on
-3. `rustup target add wasm32-unknown-unknown` - add the ability to compile Rust to WebAssembly
-4. `cargo install cargo-generate` - install `cargo-generate` binary (should be installed automatically in future)
-5. `npm install -g sass` - install `dart-sass` (should be optional in future
-
-## Alternatives to cargo-leptos
-
-This crate can be run without `cargo-leptos`, using `wasm-pack` and `cargo`. To do so, you'll need to install some other tools. 0. `cargo install wasm-pack`
-
-1. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-
-### Server Side Rendering With Hydration
-
-To run it as a server side app with hydration, first you should run
-
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-
-to generate the WebAssembly to hydrate the HTML delivered from the server.
-
-Then run the server with `cargo run` to serve the server side rendered HTML and the WASM bundle for hydration.
-
-```bash
-cargo run --no-default-features --features=ssr
-```
-
-> Note that if your hydration code changes, you will have to rerun the wasm-pack command above before running
-> `cargo run`
-
-### Client Side Rendering
-
-You'll need to install trunk to client side render this bundle.
-
-1. `cargo install trunk`
-   Then the site can be served with `trunk serve --open`

examples/login_with_token_csr_only/README.md

@@ -4,20 +4,8 @@ This example demonstrates a scenario of a client-side rendered application
 that uses an existing API that you cannot or do not want to change.
 The authentications of this example are done using an API token.
 
-## Run
-
-First start the example server:
-
-```
-cd server/ && cargo run
-```
-
-then use [`trunk`](https://trunkrs.dev) to serve the SPA:
-
-```
-cd client/ && trunk serve
-```
-
-finally you can visit the web application at `http://localhost:8080`
-
 The `api-boundary` crate contains data structures that are used by the server and the client.
+
+## Getting Started
+
+See the [Examples README](../README.md) for setup and run instructions.

examples/parent_child/README.md

@@ -9,9 +9,6 @@ This example highlights four different ways that child components can communicat
 3. `<ButtonC/>`: adding a simple event listener on the child component itself
 4. `<ButtonD/>`: providing a context that is used in the component (rather than prop drilling)
 
-## Client Side Rendering
+## Getting Started
 
-To run it as a Client Side App, you can issue `trunk serve --open` in the root. This will build the entire
+See the [Examples README](../README.md) for setup and run instructions.
-app into one CSR bundle
-
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)

examples/router/README.md

@@ -2,10 +2,6 @@
 
 This example demonstrates how Leptos’s router works for client side routing.
 
-## Build and Run it
+## Getting Started
 
-```bash
+See the [Examples README](../README.md) for setup and run instructions.
-trunk serve --open
-```
-
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)

examples/session_auth_axum/README.md

@@ -2,41 +2,6 @@
 
 This example creates a basic todo app with an Axum backend that uses Leptos' server functions to call sqlx from the client and seamlessly run it on the server. It lets you login, signup, and submit todos as different users, or a guest.
 
-## Client Side Rendering
+## Getting Started
-This example cannot be built as a trunk standalone CSR-only app. Only the server may directly connect to the database.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```

examples/slots/README.md

@@ -2,6 +2,6 @@
 
 This example shows how to use Slots in Leptos.
 
-To run it, just issue the `trunk serve --open` command in the example root. This will build the app, run it, and open a new browser to serve it.
+## Getting Started
 
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)
+See the [Examples README](../README.md) for setup and run instructions.

examples/ssr_modes/README.md

@@ -1,54 +1,26 @@
-# Server-Side Rendering Modes
+# SSR Modes Example
+
+This example shows the different "rendering modes" that can be used while server-side rendering an application.
+
+## Getting Started
+
+See the [Examples README](../README.md) for setup and run instructions.
+
+## Server-Side Rendering Modes
 
-This example shows the different "rendering modes" that can be used while server-side 
-rendering an application:
 1. **Synchronous**: Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the client, replacing `fallback` once they're loaded.
      - *Pros*: App shell appears very quickly: great TTFB (time to first byte).
      - *Cons*: Resources load relatively slowly; you need to wait for JS + Wasm to load before even making a request.
+
 2. **Out-of-order streaming**: Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the **server**, streaming it down to the client as it resolves, and streaming down HTML for `Suspense` nodes.
      - *Pros*: Combines the best of **synchronous** and **`async`**, with a very fast shell and resources that begin loading on the server.
      - *Cons*: Requires JS for suspended fragments to appear in correct order. Weaker meta tag support when it depends on data that's under suspense (has already streamed down `<head>`)
+
 3. **In-order streaming**: Walk through the tree, returning HTML synchronously as in synchronous rendering and out-of-order streaming until you hit a `Suspense`. At that point, wait for all its data to load, then render it, then the rest of the tree.
      - *Pros*: Does not require JS for HTML to appear in correct order.
      - *Cons*: Loads the shell more slowly than out-of-order streaming or synchronous rendering because it needs to pause at every `Suspense`. Cannot begin hydration until the entire page has loaded, so earlier pieces
        of the page will not be interactive until the suspended chunks have loaded.
+
 4. **`async`**: Load all resources on the server. Wait until all data are loaded, and render HTML in one sweep.
      - *Pros*: Better handling for meta tags (because you know async data even before you render the `<head>`). Faster complete load than **synchronous** because async resources begin loading on server.
      - *Cons*: Slower load time/TTFB: you need to wait for all async resources to load before displaying anything on the client.
-
-## Server Side Rendering with `cargo-leptos`
-`cargo-leptos` is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```
-

examples/ssr_modes_axum/README.md

@@ -1,54 +1,27 @@
-# Server-Side Rendering Modes
+# SSR Mode Axum Example
+
+This example shows the different "rendering modes" that can be used while server-side rendering an application.
+
+## Getting Started
+
+See the [Examples README](../README.md) for setup and run instructions.
+
+## Server-Side Rendering Modes
 
-This example shows the different "rendering modes" that can be used while server-side 
-rendering an application:
 1. **Synchronous**: Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the client, replacing `fallback` once they're loaded.
      - *Pros*: App shell appears very quickly: great TTFB (time to first byte).
      - *Cons*: Resources load relatively slowly; you need to wait for JS + Wasm to load before even making a request.
+
 2. **Out-of-order streaming**: Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the **server**, streaming it down to the client as it resolves, and streaming down HTML for `Suspense` nodes.
      - *Pros*: Combines the best of **synchronous** and **`async`**, with a very fast shell and resources that begin loading on the server.
      - *Cons*: Requires JS for suspended fragments to appear in correct order. Weaker meta tag support when it depends on data that's under suspense (has already streamed down `<head>`)
+
 3. **In-order streaming**: Walk through the tree, returning HTML synchronously as in synchronous rendering and out-of-order streaming until you hit a `Suspense`. At that point, wait for all its data to load, then render it, then the rest of the tree.
      - *Pros*: Does not require JS for HTML to appear in correct order.
      - *Cons*: Loads the shell more slowly than out-of-order streaming or synchronous rendering because it needs to pause at every `Suspense`. Cannot begin hydration until the entire page has loaded, so earlier pieces
        of the page will not be interactive until the suspended chunks have loaded.
+
 4. **`async`**: Load all resources on the server. Wait until all data are loaded, and render HTML in one sweep.
      - *Pros*: Better handling for meta tags (because you know async data even before you render the `<head>`). Faster complete load than **synchronous** because async resources begin loading on server.
      - *Cons*: Slower load time/TTFB: you need to wait for all async resources to load before displaying anything on the client.
 
-## Server Side Rendering with `cargo-leptos`
-`cargo-leptos` is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
-
-1. Install cargo-leptos
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```
-

examples/suspense_tests/README.md

@@ -1,81 +1,11 @@
-<picture>
+# Suspense Test Example
-    <source srcset="https://raw.githubusercontent.com/leptos-rs/leptos/main/docs/logos/Leptos_logo_Solid_White.svg" media="(prefers-color-scheme: dark)">
-    <img src="https://raw.githubusercontent.com/leptos-rs/leptos/main/docs/logos/Leptos_logo_RGB.svg" alt="Leptos Logo">
-</picture>
 
-# Leptos Starter Template
+This example demonstrates the `<Suspense/>` behavior.
 
-This is a template for use with the [Leptos](https://github.com/leptos-rs/leptos) web framework and the [cargo-leptos](https://github.com/akesson/cargo-leptos) tool.
+## Getting Started
 
-## Creating your template repo
+See the [Examples README](../README.md) for setup and run instructions.
 
-If you don't have `cargo-leptos` installed you can install it with
+## Test Strategy
 
-`cargo install cargo-leptos`
+See the [E2E README](./e2e/README.md) to learn about the web testing strategy for this project.
-
-Then run
-
-`cargo leptos new --git leptos-rs/start`
-
-to generate a new project template.
-
-`cd {projectname}`
-
-to go to your newly created project.
-
-Of course you should explore around the project structure, but the best place to start with your application code is in `src/app.rs`.
-
-## Running your project
-
-`cargo leptos watch`
-
-## Installing Additional Tools
-
-By default, `cargo-leptos` uses `nightly` Rust, `cargo-generate`, and `sass`. If you run into any trouble, you may need to install one or more of these tools.
-
-1. `rustup toolchain install nightly --allow-downgrade` - make sure you have Rust nightly
-2. `rustup default nightly` - setup nightly as default, or you can use rust-toolchain file later on
-3. `rustup target add wasm32-unknown-unknown` - add the ability to compile Rust to WebAssembly
-4. `cargo install cargo-generate` - install `cargo-generate` binary (should be installed automatically in future)
-5. `npm install -g sass` - install `dart-sass` (should be optional in future)
-
-## Executing a Server on a Remote Machine Without the Toolchain
-After running a `cargo leptos build --release` the minimum files needed are:
-
-1. The server binary located in `target/server/release`
-2. The `site` directory and all files within located in `target/site`
-
-Copy these files to your remote server. The directory structure should be:
-```text
-suspense_tests
-site/
-```
-Set the following enviornment variables (updating for your project as needed):
-```text
-LEPTOS_OUTPUT_NAME="suspense_tests"
-LEPTOS_SITE_ROOT="site"
-LEPTOS_SITE_PKG_DIR="pkg"
-LEPTOS_SITE_ADDR="127.0.0.1:3000"
-LEPTOS_RELOAD_PORT="3001"
-```
-Finally, run the server binary.
-
-## Testing
-
-This example includes quality checks and end-to-end testing.
-
-To get started run this once.
-
-```bash
-cargo make ci
-```
-
-To only run the UI tests...
-
-```bash
-cargo make start-webdriver
-cargo leptos watch # or cargo run...
-cargo make test-ui
-```
-
-_See the [E2E README](./e2e/README.md) for more information about the testing strategy._

examples/tailwind/README.md

@@ -2,21 +2,11 @@
 
 This is a template demonstrating how to integrate [TailwindCSS](https://tailwindcss.com/) with the [Leptos](https://github.com/leptos-rs/leptos) web framework and the [cargo-leptos](https://github.com/akesson/cargo-leptos) tool.
 
-If you don't have `cargo-leptos` installed you can install it with
+## Getting Started
 
-`cargo install --locked cargo-leptos`
+See the [Examples README](../README.md) for setup and run instructions.
 
-Then run
+## Tailwind
-
-`cargo leptos watch`
-
-in this directory.
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-You can begin editing your app at `src/app.rs`.
-
-## Installing Tailwind
 
 You can install Tailwind using `npm`:
 
@@ -52,56 +42,10 @@ If you're using VS Code, add the following to your `settings.json`
 
 Install [Tailwind CSS Intellisense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss).
 
-    Install "VS Browser" extension, a browser at the right window.
+Install [VS Browser](https://marketplace.visualstudio.com/items?itemName=Phu1237.vs-browser) extension (allows you to open a browser at the right window).
+
 Allow vscode Ports forward: 3000, 3001.
 
-## Notes about Tooling
+### Attribution
-
-By default, `cargo-leptos` uses `nightly` Rust, `cargo-generate`, and `sass`. If you run into any trouble, you may need to install one or more of these tools.
-
-1. `rustup toolchain install nightly --allow-downgrade` - make sure you have Rust nightly
-2. `rustup default nightly` - setup nightly as default, or you can use rust-toolchain file later on
-3. `rustup target add wasm32-unknown-unknown` - add the ability to compile Rust to WebAssembly
-4. `cargo install cargo-generate` - install `cargo-generate` binary (should be installed automatically in future)
-5. `npm install -g sass` - install `dart-sass` (should be optional in future
-
-## Alternatives to cargo-leptos
-
-This crate can be run without `cargo-leptos`, using `wasm-pack` and `cargo`. To do so, you'll need to install some other tools. 0. `cargo install wasm-pack`
-
-1. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-
-### Server Side Rendering With Hydration
-
-To run it as a server side app with hydration, first you should run
-
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-
-to generate the WebAssembly to hydrate the HTML delivered from the server.
-
-Then run the server with `cargo run` to serve the server side rendered HTML and the WASM bundle for hydration.
-
-```bash
-cargo run --no-default-features --features=ssr
-```
-
-> Note that if your hydration code changes, you will have to rerun the wasm-pack command above before running
-> `cargo run`
-
-### Client Side Rendering
-
-You'll need to install trunk to client side render this bundle.
-
-1. `cargo install trunk`
-   Then the site can be served with `trunk serve --open`
-
-## Attribution
 
 Many thanks to GreatGreg for putting together this guide. You can find the original, with added details, [here](https://github.com/leptos-rs/leptos/discussions/125).
-
-## Playwright Testing
-
-- Run `cargo make setup` to install dependencies
-- Run `cargo leptos test` or `cargo leptos end-to-end` to run the test

examples/tailwind_csr_trunk/README.md

@@ -2,22 +2,14 @@
 
 This is a template demonstrating how to integrate [TailwindCSS](https://tailwindcss.com/) with the [Leptos](https://github.com/leptos-rs/leptos) web framework and the [trunk](https://github.com/thedodd/trunk) tool.
 
+## Getting Started
 
-Install Tailwind and build the CSS:
+See the [Examples README](../README.md) for setup and run instructions.
+
+## Tailwind
 
 `Trunk.toml` is configured to build the CSS automatically.
 
-Install trunk to client side render this bundle.
-
-`cargo install trunk`
-Then the site can be served with `trunk serve --open`
-
-The browser will automatically open [http://127.0.0.1:8080//](http://127.0.0.1:8080//)
-
-You can begin editing your app at `src/app.rs`.
-
-## Installing Tailwind
-
 You can install Tailwind using `npm`:
 
 ```bash
@@ -52,20 +44,10 @@ If you're using VS Code, add the following to your `settings.json`
 
 Install [Tailwind CSS Intellisense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss).
 
-Install [VS Browser](https://marketplace.visualstudio.com/items?itemName=Phu1237.vs-browser) extension (allows you to open a browser at the right window.
+Install [VS Browser](https://marketplace.visualstudio.com/items?itemName=Phu1237.vs-browser) extension (allows you to open a browser at the right window).
 
 Allow vscode Ports forward: 3000, 3001.
 
-## Notes about Tooling
+### Attribution
 
-By default, `cargo-leptos` uses `nightly` Rust, `cargo-generate`, and `sass`. If you run into any trouble, you may need to install one or more of these tools.
+Many thanks to GreatGreg for putting together this guide. You can find the original, with added details, [here](https://github.com/leptos-rs/leptos/discussions/125).
-
-1. `rustup toolchain install nightly --allow-downgrade` - make sure you have Rust nightly
-2. `rustup default nightly` - setup nightly as default, or you can use rust-toolchain file later on
-3. `rustup target add wasm32-unknown-unknown` - add the ability to compile Rust to WebAssembly
-4. `cargo install cargo-generate` - install `cargo-generate` binary (should be installed automatically in future)
-5. `npm install -g sass` - install `dart-sass` (should be optional in future
-
-
-## Attribution
-This is based on the original Tailwind example (../examples/tailwind)

examples/timer/README.md

@@ -2,6 +2,6 @@
 
 This example creates a simple timer based on `setInterval` in a client side rendered app with Rust and WASM.
 
-To run it, just issue the `trunk serve --open` command in the example root. This will build the app, run it, and open a new browser to serve it.
+## Getting Started
 
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)
+See the [Examples README](../README.md) for setup and run instructions.

examples/todo_app_sqlite/README.md

@@ -2,73 +2,14 @@
 
 This example creates a basic todo app with an Actix backend that uses Leptos' server functions to call sqlx from the client and seamlessly run it on the server.
 
-## Client Side Rendering
+## Getting Started
 
-This example cannot be built as a trunk standalone CSR-only app. Only the server may directly connect to the database.
+See the [Examples README](../README.md) for setup and run instructions.
 
-## Server Side Rendering with cargo-leptos
+## E2E Testing
 
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
+See the [E2E README](./e2e/README.md) for more information about the testing strategy.
 
-1. Install cargo-leptos
+## Rendering
 
-```bash
+See the [SSR Notes](../SSR_NOTES.md) for more information about Server Side Rendering.
-cargo install --locked cargo-leptos
-```
-
-2. Build the site in watch mode, recompiling on file changes
-
-```bash
-cargo leptos watch
-```
-
-Open browser on [http://localhost:3000/](http://localhost:3000/)
-
-3. When ready to deploy, run
-
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-
-```bash
-cargo install wasm-pack
-```
-
-2. Build the Webassembly used to hydrate the HTML from the server
-
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-
-3. Run the server to serve the Webassembly, JS, and HTML
-
-```bash
-cargo run --no-default-features --features=ssr
-```
-
-## Testing
-
-This example includes quality checks and end-to-end testing.
-
-To get started run this once.
-
-```bash
-cargo make ci
-```
-
-To only run the UI tests...
-
-```bash
-cargo make start-webdriver
-cargo leptos watch # or cargo run...
-cargo make test-ui
-```
-
-_See the [E2E README](./e2e/README.md) for more information about the testing strategy._

examples/todo_app_sqlite/e2e/Cargo.toml

@@ -14,5 +14,5 @@ tokio = { version = "1.29.1", features = ["macros", "rt-multi-thread", "time"] }
 url = "2.4.0"
 
 [[test]]
-name = "manage_todos"
+name = "app_suite"
 harness = false    # Allow Cucumber to print output instead of libtest

examples/todo_app_sqlite/e2e/Makefile.toml

@@ -8,4 +8,13 @@ condition = { env_true = ["RUN_AUTOMATICALLY"] }
 
 [tasks.test-ui]
 command = "cargo"
-args = ["test", "--test", "manage_todos", "--", "--fail-fast", "${@}"]
+args = [
+    "test",
+    "--test",
+    "app_suite",
+    "--",
+    "--retry",
+    "2",
+    "--fail-fast",
+    "${@}",
+]

examples/todo_app_sqlite/e2e/README.md

@@ -13,12 +13,13 @@ This example demonstrates e2e testing with Rust using executable requirements.
 
 ## Testing Organization
 
-Testing is organized around what a user can do and see/not see.
+Testing is organized around what a user can do and see/not see. Test scenarios are grouped by the **user action** and the **object** of that action. This makes it easier to locate and reason about requirements.
 
 Here is a brief overview of how things fit together.
 
 ```bash
-features                    # Specify test scenarios
+features
+└── {action}_{object}.feature   # Specify test scenarios
 tests
 ├── fixtures
 │   ├── action.rs               # Perform a user action (click, type, etc.)
@@ -29,5 +30,5 @@ tests
 │       ├── action_steps.rs     # Map Gherkin steps to user actions
 │       ├── check_steps.rs      # Map Gherkin steps to user expectations
 │       └── mod.rs
-└── manage_todos.rs         # Test main 
+└── app_suite.rs                # Test main 
 ```

examples/todo_app_sqlite_axum/README.md

@@ -2,61 +2,14 @@
 
 This example creates a basic todo app with an Axum backend that uses Leptos' server functions to call sqlx from the client and seamlessly run it on the server.
 
-## Client Side Rendering
+## Getting Started
-This example cannot be built as a trunk standalone CSR-only app. Only the server may directly connect to the database.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
 
-1. Install cargo-leptos
+## E2E Testing
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
 
-Open browser on [http://localhost:3000/](http://localhost:3000/)
+See the [E2E README](./e2e/README.md) for more information about the testing strategy.
 
-3. When ready to deploy, run
+## Rendering
-```bash
-cargo leptos build --release
-```
 
-## Server Side Rendering without cargo-leptos
+See the [SSR Notes](../SSR_NOTES.md) for more information about Server Side Rendering.
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```
-
-## Testing
-
-This example includes quality checks and end-to-end testing.
-
-To get started run this once.
-
-```bash
-cargo make ci
-```
-
-To only run the UI tests...
-
-```bash
-cargo make start-webdriver
-cargo leptos watch # or cargo run...
-cargo make test-ui
-```
-
-_See the [E2E README](./e2e/README.md) for more information about the testing strategy._

examples/todo_app_sqlite_axum/e2e/Cargo.toml

@@ -14,5 +14,5 @@ tokio = { version = "1.29.1", features = ["macros", "rt-multi-thread", "time"] }
 url = "2.4.0"
 
 [[test]]
-name = "manage_todos"
+name = "app_suite"
 harness = false    # Allow Cucumber to print output instead of libtest

examples/todo_app_sqlite_axum/e2e/Makefile.toml

@@ -8,4 +8,13 @@ condition = { env_true = ["RUN_AUTOMATICALLY"] }
 
 [tasks.test-ui]
 command = "cargo"
-args = ["test", "--test", "manage_todos", "--", "--fail-fast", "${@}"]
+args = [
+    "test",
+    "--test",
+    "app_suite",
+    "--",
+    "--retry",
+    "2",
+    "--fail-fast",
+    "${@}",
+]

examples/todo_app_sqlite_axum/e2e/README.md

@@ -13,12 +13,13 @@ This example demonstrates e2e testing with Rust using executable requirements.
 
 ## Testing Organization
 
-Testing is organized around what a user can do and see/not see.
+Testing is organized around what a user can do and see/not see. Test scenarios are grouped by the **user action** and the **object** of that action. This makes it easier to locate and reason about requirements.
 
 Here is a brief overview of how things fit together.
 
 ```bash
-features                    # Specify test scenarios
+features
+└── {action}_{object}.feature   # Specify test scenarios
 tests
 ├── fixtures
 │   ├── action.rs               # Perform a user action (click, type, etc.)
@@ -29,5 +30,5 @@ tests
 │       ├── action_steps.rs     # Map Gherkin steps to user actions
 │       ├── check_steps.rs      # Map Gherkin steps to user expectations
 │       └── mod.rs
-└── manage_todos.rs         # Test main 
+└── app_suite.rs                # Test main 
 ```

examples/todo_app_sqlite_viz/README.md

@@ -2,41 +2,10 @@
 
 This example creates a basic todo app with a Viz backend that uses Leptos' server functions to call sqlx from the client and seamlessly run it on the server.
 
-## Client Side Rendering
+## Getting Started
-This example cannot be built as a trunk standalone CSR-only app. Only the server may directly connect to the database.
 
-## Server Side Rendering with cargo-leptos
+See the [Examples README](../README.md) for setup and run instructions.
-cargo-leptos is now the easiest and most featureful way to build server side rendered apps with hydration. It provides automatic recompilation of client and server code, wasm optimisation, CSS minification, and more! Check out more about it [here](https://github.com/akesson/cargo-leptos)
 
-1. Install cargo-leptos
+## Rendering
-```bash
-cargo install --locked cargo-leptos
-``` 
-2. Build the site in watch mode, recompiling on file changes
-```bash
-cargo leptos watch
-```
 
-Open browser on [http://localhost:3000/](http://localhost:3000/)
+See the [SSR Notes](../SSR_NOTES.md) for more information about Server Side Rendering.
-
-3. When ready to deploy, run
-```bash
-cargo leptos build --release
-```
-
-## Server Side Rendering without cargo-leptos
-To run it as a server side app with hydration, you'll need to have wasm-pack installed.
-
-0. Edit the `[package.metadata.leptos]` section and set `site-root` to `"."`. You'll also want to change the path of the `<StyleSheet / >` component in the root component to point towards the CSS file in the root. This tells leptos that the WASM/JS files generated by wasm-pack are available at `./pkg` and that the CSS files are no longer processed by cargo-leptos. Building to alternative folders is not supported at this time. You'll also want to edit the call to `get_configuration()` to pass in `Some(Cargo.toml)`, so that Leptos will read the settings instead of cargo-leptos. If you do so, your file/folder names cannot include dashes.
-1. Install wasm-pack
-```bash
-cargo install wasm-pack
-```
-2. Build the Webassembly used to hydrate the HTML from the server
-```bash
-wasm-pack build --target=web --debug --no-default-features --features=hydrate
-```
-3. Run the server to serve the Webassembly, JS, and HTML 
-```bash
-cargo run --no-default-features --features=ssr
-```

examples/todomvc/README.md

@@ -2,9 +2,6 @@
 
 This is a Leptos implementation of the TodoMVC example common to many frameworks. This is a relatively-simple application but shows off features like interaction between components and state management.
 
-## Client Side Rendering
+## Getting Started
 
-To run it as a Client Side App, you can issue `trunk serve --open` in the root. This will build the entire
+See the [Examples README](../README.md) for setup and run instructions.
-app into one CSR bundle.
-
-> If you don't have `trunk` installed, [click here for install instructions.](https://trunkrs.dev/)