From e88e131ec3cd47ac0a20c060d368f575d36c286f Mon Sep 17 00:00:00 2001 From: Ben Wishovich Date: Tue, 29 Nov 2022 13:14:59 -0800 Subject: [PATCH] Add READMEs to all examples and fix typo in todo-app-axum --- examples/counter/README.md | 1 - examples/counters-stable/README.md | 8 ++++++++ examples/counters/README.md | 8 ++++++++ examples/fetch/README.md | 7 +++++++ examples/gtk/README.md | 7 +++++++ examples/hackernews-axum/README.md | 2 +- examples/hackernews/README.md | 4 ++-- examples/parent-child/README.md | 14 ++++++++++++++ examples/router/README.md | 4 ++-- examples/todo-app-cbor/README.md | 21 ++++++++++----------- examples/todo-app-sqlite-axum/src/main.rs | 2 +- examples/todo-app-sqlite/README.md | 21 ++++++++++----------- examples/todomvc/README.md | 7 +++++++ examples/view-tests/README.md | 8 ++++++++ leptos/src/lib.rs | 11 +++++++++++ 15 files changed, 96 insertions(+), 29 deletions(-) create mode 100644 examples/counters-stable/README.md create mode 100644 examples/counters/README.md create mode 100644 examples/fetch/README.md create mode 100644 examples/gtk/README.md create mode 100644 examples/parent-child/README.md create mode 100644 examples/todomvc/README.md create mode 100644 examples/view-tests/README.md diff --git a/examples/counter/README.md b/examples/counter/README.md index a93f2ce..dcd6f23 100644 --- a/examples/counter/README.md +++ b/examples/counter/README.md @@ -2,5 +2,4 @@ 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. diff --git a/examples/counters-stable/README.md b/examples/counters-stable/README.md new file mode 100644 index 0000000..4c5535b --- /dev/null +++ b/examples/counters-stable/README.md @@ -0,0 +1,8 @@ +# Leptos Counters Example on Rust Stable + +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 + +## 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 + diff --git a/examples/counters/README.md b/examples/counters/README.md new file mode 100644 index 0000000..ec6d457 --- /dev/null +++ b/examples/counters/README.md @@ -0,0 +1,8 @@ +# Leptos Counters Example + +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 + +## 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 + diff --git a/examples/fetch/README.md b/examples/fetch/README.md new file mode 100644 index 0000000..481f04d --- /dev/null +++ b/examples/fetch/README.md @@ -0,0 +1,7 @@ +# Client Side Fetch + +This example shows how to fetch data from the client in Webassembly + +## 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 diff --git a/examples/gtk/README.md b/examples/gtk/README.md new file mode 100644 index 0000000..5cde3f7 --- /dev/null +++ b/examples/gtk/README.md @@ -0,0 +1,7 @@ +# Leptos in a GTK App + +This example creates a basic GTK app that uses leptos' reactive primitives. + +## Build and Run +Unlike the other examples, this has a variety of build preqrequisites that are out of scope of this crate. More detail on that can be found [here](https://gtk-rs.org/gtk4-rs/stable/latest/book/installation.html). The example comes from [here](https://gtk-rs.org/gtk4-rs/stable/latest/book/hello_world.html) and should be +runnable with `cargo run` if you have the GTK prerequisites installed. diff --git a/examples/hackernews-axum/README.md b/examples/hackernews-axum/README.md index be8429a..b74fdcc 100644 --- a/examples/hackernews-axum/README.md +++ b/examples/hackernews-axum/README.md @@ -4,7 +4,7 @@ This example creates a basic clone of the Hacker News site. It showcases Leptos' ## 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 CRS bundle +app into one CSR bundle ## Server Side Rendering With Hydration To run it as a server side app with hydration, first you should run diff --git a/examples/hackernews/README.md b/examples/hackernews/README.md index f687ba4..c228092 100644 --- a/examples/hackernews/README.md +++ b/examples/hackernews/README.md @@ -1,10 +1,10 @@ # Leptos Hacker News Example -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 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. It uses Actix as it's backend. ## 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 CRS bundle +app into one CSR bundle ## Server Side Rendering With Hydration To run it as a server side app with hydration, first you should run diff --git a/examples/parent-child/README.md b/examples/parent-child/README.md new file mode 100644 index 0000000..31cdaa0 --- /dev/null +++ b/examples/parent-child/README.md @@ -0,0 +1,14 @@ +# Parent Child Example + + This example highlights four different ways that child components can communicate with their parent: +1. : passing a WriteSignal as one of the child component props, + for the child component to write into and the parent to read +2. : passing a closure as one of the child component props, for + the child component to call +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 +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 + diff --git a/examples/router/README.md b/examples/router/README.md index 8c1c6a2..bfd8acf 100644 --- a/examples/router/README.md +++ b/examples/router/README.md @@ -1,8 +1,8 @@ # Leptos Router Example -This example demonstrates how Leptos' router works +This example demonstrates how Leptos' router for client side routing. -## Run it +## Build and Run it ```bash trunk serve --open ``` diff --git a/examples/todo-app-cbor/README.md b/examples/todo-app-cbor/README.md index 5bf5dd2..7585632 100644 --- a/examples/todo-app-cbor/README.md +++ b/examples/todo-app-cbor/README.md @@ -1,21 +1,20 @@ -# Leptos Counter Isomorphic Example +# Leptos Todo App Sqlite with CBOR -This example demonstrates how to use a server functions and multi-actions to build a simple todo app. +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. It is identical to the todo-app-sqlite example, but utilizes CBOR encoding for one of the server functions + +## 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 ## Server Side Rendering With Hydration - -To run it as a server side app with hydration, first you should run - +To run it as a server side app with hydration, first you should run ```bash wasm-pack build --target=web --no-default-features --features=hydrate ``` - to generate the Webassembly to provide hydration features for the server. -Then run the server with `cargo run` to serve the server side rendered HTML and the WASM bundle for hydration. - +Then run the server with `cargo run` to serve the server side rendered HTML and the WASM bundle for hydration. ```bash -cargo run +cargo run --no-default-features --features=ssr ``` - > Note that if your hydration code changes, you will have to rerun the wasm-pack command above -> This should be temporary, and vastly improve once cargo-leptos becomes ready for prime time! +> This should be temporary, and vastly improve once cargo-leptos becomes ready for prime time! \ No newline at end of file diff --git a/examples/todo-app-sqlite-axum/src/main.rs b/examples/todo-app-sqlite-axum/src/main.rs index 69821b8..89ef8b1 100644 --- a/examples/todo-app-sqlite-axum/src/main.rs +++ b/examples/todo-app-sqlite-axum/src/main.rs @@ -31,7 +31,7 @@ if #[cfg(feature = "ssr")] { // build our application with a route let app = Router::new() - .route("/api/*path", post(leptos_axum::handle_server_fns)) + .route("/api/*fn_name", post(leptos_axum::handle_server_fns)) .nest("/pkg", get(file_handler)) .nest("/static", get(get_static_file_handler)) .fallback(leptos_axum::render_app_to_stream("todo_app_sqlite_axum", |cx| view! { cx, }).into_service()); diff --git a/examples/todo-app-sqlite/README.md b/examples/todo-app-sqlite/README.md index 5bf5dd2..e718084 100644 --- a/examples/todo-app-sqlite/README.md +++ b/examples/todo-app-sqlite/README.md @@ -1,21 +1,20 @@ -# Leptos Counter Isomorphic Example +# Leptos Todo App Sqlite -This example demonstrates how to use a server functions and multi-actions to build a simple todo app. +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 +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 ## Server Side Rendering With Hydration - -To run it as a server side app with hydration, first you should run - +To run it as a server side app with hydration, first you should run ```bash wasm-pack build --target=web --no-default-features --features=hydrate ``` - to generate the Webassembly to provide hydration features for the server. -Then run the server with `cargo run` to serve the server side rendered HTML and the WASM bundle for hydration. - +Then run the server with `cargo run` to serve the server side rendered HTML and the WASM bundle for hydration. ```bash -cargo run +cargo run --no-default-features --features=ssr ``` - > Note that if your hydration code changes, you will have to rerun the wasm-pack command above -> This should be temporary, and vastly improve once cargo-leptos becomes ready for prime time! +> This should be temporary, and vastly improve once cargo-leptos becomes ready for prime time! \ No newline at end of file diff --git a/examples/todomvc/README.md b/examples/todomvc/README.md new file mode 100644 index 0000000..6dee203 --- /dev/null +++ b/examples/todomvc/README.md @@ -0,0 +1,7 @@ +# Leptos TodoMVC + +This is a Leptos implementation of the TodoMVC example that most frameworks have. + +## 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 diff --git a/examples/view-tests/README.md b/examples/view-tests/README.md new file mode 100644 index 0000000..730fc84 --- /dev/null +++ b/examples/view-tests/README.md @@ -0,0 +1,8 @@ +# Leptos View Tests + +This is a collection of mostly internal view tests for Leptos. Feel free to look if curious. + +## 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 + diff --git a/leptos/src/lib.rs b/leptos/src/lib.rs index bbdf6fb..0158861 100644 --- a/leptos/src/lib.rs +++ b/leptos/src/lib.rs @@ -27,8 +27,12 @@ //! the [examples](https://github.com/gbj/leptos/tree/main/examples): //! - [`counter`](https://github.com/gbj/leptos/tree/main/examples/counter) is the classic //! counter example, showing the basics of client-side rendering and reactive DOM updates +//! - [`counter-isomorphic`](https://github.com/gbj/leptos/tree/main/examples/counter-isomorphic) is the classic +//! counter example run on the server using an isomorphic function, showing the basics of client-side rendering and reactive DOM updates //! - [`counters`](https://github.com/gbj/leptos/tree/main/examples/counters) introduces parent-child //! communication via contexts, and the `` component for efficient keyed list updates. +//! - [`counters-stable`](https://github.com/gbj/leptos/tree/main/examples/counters-stable) introduces parent-child +//! communication via contexts, and the `` component for efficient keyed list updates. Unlike counters, this compiles in Rust stable. //! - [`parent-child`](https://github.com/gbj/leptos/tree/main/examples/parent-child) shows four different //! ways a parent component can communicate with a child, including passing a closure, context, and more //! - [`todomvc`](https://github.com/gbj/leptos/tree/main/examples/todomvc) implements the classic to-do @@ -47,6 +51,13 @@ //! - [`hackernews`](https://github.com/gbj/leptos/tree/main/examples/hackernews) pulls everything together. //! It integrates calls to a real external REST API, routing, server-side rendering and hydration to create //! a fully-functional PEMPA that works as intended even before WASM has loaded and begun to run. +//! - [`hackernews-axum`](https://github.com/gbj/leptos/tree/main/examples/hackernews-axum) pulls everything together. +//! It integrates calls to a real external REST API, routing, server-side rendering and hydration to create +//! a fully-functional PEMPA that works as intended even before WASM has loaded and begun to run. This one uses Axum as it's backend. +//! - [`todo-app-sqlite`](https://github.com/gbj/leptos/tree/main/examples/todo-app-sqlite) is a simple todo app, showcasing the use of +//! functions that run only on the server, but are called from client side function calls +//! - [`todo-app-sqlite-axum`](https://github.com/gbj/leptos/tree/main/examples/todo-app-sqlite-axum) is a simple todo app, showcasing the use of +//! functions that run only on the server, but are called from client side function calls. Now with Axum backend //! //! (The SPA examples can be run using `trunk serve`. For information about Trunk, //! [see here]((https://trunkrs.dev/)).)