diff --git a/.github/workflows/get-changed-examples-matrix.yml b/.github/workflows/get-changed-examples-matrix.yml index 591f251c1..745aa548d 100644 --- a/.github/workflows/get-changed-examples-matrix.yml +++ b/.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 diff --git a/examples/README.md b/examples/README.md index ac4e62c63..71dc8d37c 100644 --- a/examples/README.md +++ b/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 ( or 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 ( or 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 diff --git a/examples/SSR_NOTES.md b/examples/SSR_NOTES.md new file mode 100644 index 000000000..51a6565e1 --- /dev/null +++ b/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 `` 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` \ No newline at end of file diff --git a/examples/animated_show/README.md b/examples/animated_show/README.md index 327acebc3..a4cfb65bc 100644 --- a/examples/animated_show/README.md +++ b/examples/animated_show/README.md @@ -1,9 +1,10 @@ -# `` combined with CSS animations +# Animated Show Example This is a very simple example of the `` component. -This component is an extension for the `` 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 +The `` component is an extension for the `` 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 CSS. -Just execute `trunk serve` to start the demo. +## Getting Started + +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/counter/README.md b/examples/counter/README.md index 26e126485..04812db84 100644 --- a/examples/counter/README.md +++ b/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. diff --git a/examples/counter_isomorphic/README.md b/examples/counter_isomorphic/README.md index 46731896c..26c7a0c86 100644 --- a/examples/counter_isomorphic/README.md +++ b/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 -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. +## Getting Started -## 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 `"."`. For examples with CSS you also want to change the path of the `` 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 -``` +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/counter_url_query/README.md b/examples/counter_url_query/README.md index c338e870b..c62839087 100644 --- a/examples/counter_url_query/README.md +++ b/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. diff --git a/examples/counter_without_macros/README.md b/examples/counter_without_macros/README.md index a3ed68728..2ea983cff 100644 --- a/examples/counter_without_macros/README.md +++ b/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. diff --git a/examples/counters/README.md b/examples/counters/README.md index 1f368b1e7..35305e432 100644 --- a/examples/counters/README.md +++ b/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. - -> 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. diff --git a/examples/counters_stable/README.md b/examples/counters_stable/README.md index 1f2b60455..a015cb6db 100644 --- a/examples/counters_stable/README.md +++ b/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. - -> 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. diff --git a/examples/error_boundary/README.md b/examples/error_boundary/README.md index db9a91095..7ee85e77b 100644 --- a/examples/error_boundary/README.md +++ b/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. diff --git a/examples/errors_axum/README.md b/examples/errors_axum/README.md index 2ae88f961..af9942f96 100644 --- a/examples/errors_axum/README.md +++ b/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 -This example cannot be built as a trunk standalone CSR-only app as it requires the server to send status codes. +## Getting Started -## 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 `` 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 -``` +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/fetch/README.md b/examples/fetch/README.md index 7d03c0210..dd43ccba2 100644 --- a/examples/fetch/README.md +++ b/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. - -> 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. \ No newline at end of file diff --git a/examples/hackernews/README.md b/examples/hackernews/README.md index 6a8ffdd99..89d212691 100644 --- a/examples/hackernews/README.md +++ b/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 -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`. +## Getting Started -## 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 `` 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 -``` +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/hackernews_axum/README.md b/examples/hackernews_axum/README.md index f53af43d1..1d5a29725 100644 --- a/examples/hackernews_axum/README.md +++ b/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 -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`. +## Getting Started -## 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 `` 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 -``` +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/hackernews_islands_axum/README.md b/examples/hackernews_islands_axum/README.md index f53af43d1..1d5a29725 100644 --- a/examples/hackernews_islands_axum/README.md +++ b/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 -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`. +## Getting Started -## 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 `` 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 -``` +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/js-framework-benchmark/README.md b/examples/js-framework-benchmark/README.md index 15e8950fe..a75dc430e 100644 --- a/examples/js-framework-benchmark/README.md +++ b/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. diff --git a/examples/leptos-tailwind-axum/README.md b/examples/leptos-tailwind-axum/README.md index 2de77c4a2..4dc8bfdd3 100644 --- a/examples/leptos-tailwind-axum/README.md +++ b/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` - -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 `` 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` +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/login_with_token_csr_only/README.md b/examples/login_with_token_csr_only/README.md index f6b303fc3..cea7cd8f8 100644 --- a/examples/login_with_token_csr_only/README.md +++ b/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. diff --git a/examples/parent_child/README.md b/examples/parent_child/README.md index dcf237555..8bf987f34 100644 --- a/examples/parent_child/README.md +++ b/examples/parent_child/README.md @@ -9,9 +9,6 @@ This example highlights four different ways that child components can communicat 3. ``: adding a simple event listener on the child component itself 4. ``: 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 -app into one CSR bundle - -> 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. diff --git a/examples/router/README.md b/examples/router/README.md index 3966e2038..7450774be 100644 --- a/examples/router/README.md +++ b/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 -trunk serve --open -``` - -> 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. diff --git a/examples/session_auth_axum/README.md b/examples/session_auth_axum/README.md index 8edff7c10..02ff829d3 100644 --- a/examples/session_auth_axum/README.md +++ b/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 -This example cannot be built as a trunk standalone CSR-only app. Only the server may directly connect to the database. +## Getting Started -## 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 `` 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 -``` +See the [Examples README](../README.md) for setup and run instructions. diff --git a/examples/slots/README.md b/examples/slots/README.md index afeb4dadf..c48f10be7 100644 --- a/examples/slots/README.md +++ b/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. diff --git a/examples/ssr_modes/README.md b/examples/ssr_modes/README.md index 60d7ff8d9..eb0325b8c 100644 --- a/examples/ssr_modes/README.md +++ b/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. + +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 ``) - 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. + +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. + +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 ``). 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 `` 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 -``` - diff --git a/examples/ssr_modes_axum/README.md b/examples/ssr_modes_axum/README.md index 60d7ff8d9..c6edb1410 100644 --- a/examples/ssr_modes_axum/README.md +++ b/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. + +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 ``) - 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. + +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. + +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 ``). 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 `` 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 -``` - diff --git a/examples/suspense_tests/README.md b/examples/suspense_tests/README.md index 6511c1440..ea8188d49 100644 --- a/examples/suspense_tests/README.md +++ b/examples/suspense_tests/README.md @@ -1,81 +1,11 @@ - - - Leptos Logo - +# Suspense Test Example -# Leptos Starter Template +This example demonstrates the `` 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` - -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._ +See the [E2E README](./e2e/README.md) to learn about the web testing strategy for this project. diff --git a/examples/tailwind/README.md b/examples/tailwind/README.md index 12f16172d..9db82e1a8 100644 --- a/examples/tailwind/README.md +++ b/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 - -`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 +## 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. - Allow vscode Ports forward: 3000, 3001. +Install [VS Browser](https://marketplace.visualstudio.com/items?itemName=Phu1237.vs-browser) extension (allows you to open a browser at the right window). -## Notes about Tooling +Allow vscode Ports forward: 3000, 3001. -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 `` 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 +### 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 diff --git a/examples/tailwind_csr_trunk/README.md b/examples/tailwind_csr_trunk/README.md index 88c66dbbc..2a975d1a7 100644 --- a/examples/tailwind_csr_trunk/README.md +++ b/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. - -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) +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). diff --git a/examples/timer/README.md b/examples/timer/README.md index 5affd52f5..7bbc25c29 100644 --- a/examples/timer/README.md +++ b/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. diff --git a/examples/todo_app_sqlite/README.md b/examples/todo_app_sqlite/README.md index 083c73493..aebf885ec 100644 --- a/examples/todo_app_sqlite/README.md +++ b/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 -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 `` 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._ +See the [SSR Notes](../SSR_NOTES.md) for more information about Server Side Rendering. diff --git a/examples/todo_app_sqlite/Todos.db b/examples/todo_app_sqlite/Todos.db index 3bff93d30..96bed43b8 100644 Binary files a/examples/todo_app_sqlite/Todos.db and b/examples/todo_app_sqlite/Todos.db differ diff --git a/examples/todo_app_sqlite/e2e/Cargo.toml b/examples/todo_app_sqlite/e2e/Cargo.toml index 358953622..cd11a0618 100644 --- a/examples/todo_app_sqlite/e2e/Cargo.toml +++ b/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" -harness = false # Allow Cucumber to print output instead of libtest +name = "app_suite" +harness = false # Allow Cucumber to print output instead of libtest diff --git a/examples/todo_app_sqlite/e2e/Makefile.toml b/examples/todo_app_sqlite/e2e/Makefile.toml index d595eaac6..cd76be24d 100644 --- a/examples/todo_app_sqlite/e2e/Makefile.toml +++ b/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", + "${@}", +] diff --git a/examples/todo_app_sqlite/e2e/README.md b/examples/todo_app_sqlite/e2e/README.md index 6164ae2b5..026f2befd 100644 --- a/examples/todo_app_sqlite/e2e/README.md +++ b/examples/todo_app_sqlite/e2e/README.md @@ -13,21 +13,22 @@ 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.) -│ ├── check.rs # Assert what a user can see/not see -│ ├── find.rs # Query page elements +│ ├── action.rs # Perform a user action (click, type, etc.) +│ ├── check.rs # Assert what a user can see/not see +│ ├── find.rs # Query page elements │ ├── mod.rs │ └── world -│ ├── action_steps.rs # Map Gherkin steps to user actions -│ ├── check_steps.rs # Map Gherkin steps to user expectations +│ ├── 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 ``` diff --git a/examples/todo_app_sqlite/e2e/tests/manage_todos.rs b/examples/todo_app_sqlite/e2e/tests/app_suite.rs similarity index 100% rename from examples/todo_app_sqlite/e2e/tests/manage_todos.rs rename to examples/todo_app_sqlite/e2e/tests/app_suite.rs diff --git a/examples/todo_app_sqlite_axum/README.md b/examples/todo_app_sqlite_axum/README.md index 48afc92db..48e8ec23d 100644 --- a/examples/todo_app_sqlite_axum/README.md +++ b/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 -This example cannot be built as a trunk standalone CSR-only app. Only the server may directly connect to the database. +## Getting Started -## 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) +See the [Examples README](../README.md) for setup and run instructions. -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 -``` +## E2E Testing -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 -```bash -cargo leptos build --release -``` +## Rendering -## 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 `` 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._ \ No newline at end of file +See the [SSR Notes](../SSR_NOTES.md) for more information about Server Side Rendering. diff --git a/examples/todo_app_sqlite_axum/e2e/Cargo.toml b/examples/todo_app_sqlite_axum/e2e/Cargo.toml index 972c0017a..722428675 100644 --- a/examples/todo_app_sqlite_axum/e2e/Cargo.toml +++ b/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" -harness = false # Allow Cucumber to print output instead of libtest +name = "app_suite" +harness = false # Allow Cucumber to print output instead of libtest diff --git a/examples/todo_app_sqlite_axum/e2e/Makefile.toml b/examples/todo_app_sqlite_axum/e2e/Makefile.toml index d595eaac6..cd76be24d 100644 --- a/examples/todo_app_sqlite_axum/e2e/Makefile.toml +++ b/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", + "${@}", +] diff --git a/examples/todo_app_sqlite_axum/e2e/README.md b/examples/todo_app_sqlite_axum/e2e/README.md index 6164ae2b5..026f2befd 100644 --- a/examples/todo_app_sqlite_axum/e2e/README.md +++ b/examples/todo_app_sqlite_axum/e2e/README.md @@ -13,21 +13,22 @@ 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.) -│ ├── check.rs # Assert what a user can see/not see -│ ├── find.rs # Query page elements +│ ├── action.rs # Perform a user action (click, type, etc.) +│ ├── check.rs # Assert what a user can see/not see +│ ├── find.rs # Query page elements │ ├── mod.rs │ └── world -│ ├── action_steps.rs # Map Gherkin steps to user actions -│ ├── check_steps.rs # Map Gherkin steps to user expectations +│ ├── 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 ``` diff --git a/examples/todo_app_sqlite_axum/e2e/tests/manage_todos.rs b/examples/todo_app_sqlite_axum/e2e/tests/app_suite.rs similarity index 100% rename from examples/todo_app_sqlite_axum/e2e/tests/manage_todos.rs rename to examples/todo_app_sqlite_axum/e2e/tests/app_suite.rs diff --git a/examples/todo_app_sqlite_viz/README.md b/examples/todo_app_sqlite_viz/README.md index 498098320..ba5c02173 100644 --- a/examples/todo_app_sqlite_viz/README.md +++ b/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 -This example cannot be built as a trunk standalone CSR-only app. Only the server may directly connect to the database. +## Getting Started -## 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) +See the [Examples README](../README.md) for setup and run instructions. -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 -``` +## Rendering -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 `` 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 -``` +See the [SSR Notes](../SSR_NOTES.md) for more information about Server Side Rendering. diff --git a/examples/todomvc/README.md b/examples/todomvc/README.md index 9b240eeb2..73ff17353 100644 --- a/examples/todomvc/README.md +++ b/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 -app into one CSR bundle. - -> 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.