Tutorial docs/guide

[gbj]

I'm working on the long-awaited intro-level guide/tutorial docs.

I'm building a CodeSandbox example with comments per unit. I'll do a write-up tutorial for each segment, and probably eventually a short video.

I'd like some help: which topics are missing here? What do you think is important to emphasize? What other feedback do you have?

UPDATE: You can track progress on this in #375: the book lives in docs/book.

Link to deployed book.

Here's my comprehensive list of topics

• Basics
  • Basic components/view
  • Dynamic attributes
  • Components
  • Forms
    • NodeRef
    • prop:
  • Iteration (iterators and <For/>)
  • Control Flow
  • Parent-Child communication
  • Component Children
• Interlude: Functions and Reactivity
• Testing
• Async
  • Resource
  • Suspense
  • Transition
  • Action
• create_effect
• Interlude: Global State
• Router
  • URL as global state
  • defining <Routes/>
  • <A/>
  • <Form/>
• SSR: introducing cargo-leptos
• Deployment
• leptos_meta
• Server functions
  • Forms
  • ActionForms
  • Using extractors (Axum and Actix)
  • Turning off WebAssembly

[ManitVig]

How about a section on integrating CSS frameworks like tailwind, windi, bootstrap etc.

[4ldas]

How about a section on integrating CSS frameworks like tailwind, windi, bootstrap etc.

U just need to add their stylesheet and use classes for components id imagine

[jquesada2016]

I think this is a good place for us to create a webapp with leptos to present the docs, and allow anyone that's reading to be able to submit changes or additions to the guide, along with showing a real-world app being made with the framework!

As far as topics, here are some obscure ones:

• Scope overwriting, i.e., .child((cx, child))
• Cloning with <Component clone:var_1>/* ... */</Component>
• Using #[component(transparent)] as well as View::Transparent

[darklajid]

This might be me being a beginner in Rust and dabbling around, but I ran into two "issues":

1. trunk serve --open is mentioned in the documentation and needs to be pointed at a html file. Yet the template (leptos-rs/start based) doesn't include any html file at all? cargo leptos watch works, but it's unclear what the unmentioned requirement is to run this via trunk?

2. If I were to run a tiny test project built with leptos in production, how would I bundle this? cargo leptos build --release seems to work, ish, but how would I run this outside of the source tree? target/ is quite convoluted and to me as a beginner it's unclear how I would package and ship just the (release/production) build artifacts.

I understand that leptos is very young and that I'm personally very inexperienced in both Rust and Webassembly. So this very well might be a me problem/me not being the right audience. Just throwing this out there as a first impression, in case it might make sense to spell it out in the docs for people like me

[gbj]

This might be me being a beginner in Rust and dabbling around, but I ran into two "issues":

1. `trunk serve --open` is mentioned in the documentation and needs to be pointed at a html file. Yet the template (leptos-rs/start based) doesn't include any html file at all? `cargo leptos watch` works, but it's unclear what the unmentioned requirement is to run this via trunk?

Right, there are two totally separate ways to run a Leptos app: the starter uses cargo-leptos (which is for server-side rendering + hydration), the tutorial starts out with trunk (just rendering on the client-side/in the browser). The instructions here should be all you need to get started with Trunk.

2. If I were to run a tiny test project built with leptos in production, how would I bundle this? `cargo leptos build --release` seems to work, ish, but how would I run this outside of the source tree? `target/` is quite convoluted and to me as a beginner it's unclear how I would package and ship just the (release/production) build artifacts.

I'd encourage you to raise this in our Discord or in a GitHub Discussion, just so we can keep this thread focused on the docs. But maybe "Deployment" is something I should add to the docs todo!

[Kaszanas]

I'm very interested in the state management part of this. I have found a couple of different crates that do a Redux pattern.
It seems that this project might be compatible with leptos: https://github.com/redux-rs/redux-rs ? Although I am not sure.

[gusutabopb]

Complete Leptos newbie here. Feedback on the "Getting Started" section.

I hit three issues when running trunk serve --open:

• Got some messages saying there was no index.html - this was because I was at src/ after editing main.rs.
• Got a message saying wasm32-unknown-unknown was not installed
• Got a bunch of #![feature] may not be used on the stable release channel errors

Moving up to the repo root, installing nightly Rust and installing the wasm32 target with rustup solved the issues, but it'd be nice to have that listed upfront on the that page.

[gbj]

Complete Leptos newbie here. Feedback on the "Getting Started" section.

I hit three issues when running trunk serve --open:

* Got some messages saying there was no `index.html` - this was because I was at `src/` after editing `main.rs`.

* Got a message saying `wasm32-unknown-unknown` was not installed

* Got a bunch of `#![feature] may not be used on the stable release channel` errors

Moving up to the repo root, installing nightly Rust and installing the wasm32 target with rustup solved the issues, but it'd be nice to have that listed upfront on the that page.

Thanks — I've added a couple notes that clarify all this in #618

[d4h0]

@gbj: I'm going through the guide, which looks fantastic. However, there are some issues with the CodeSandbox examples, which make them very frustrating to interact with:

On a 14-inch display, the default layout is not usable. The left sidebar takes 2/5 of the available space, so that the code isn't completely visible, and there isn't even a horizontal scrollbar.

The height of the iframe is set to 1000px, which isn't great if your display isn't 1000 pixels high (e.g. with a 14-inch displays).

If the sidekick layer is open (which displays the rendered app), it overlays the code (making even less code readable).

It's possible to change the layout, but there are many issues with that.

1. On every page load, I'm asked to log in again (and without logging in, the layout can't be changed)
2. After logging in, when I click on the rectangle in the top left corner (where the layout can be changed), the page jumps away from the CodeSandbox box (this also happens when some other elements are clicked)
3. If a sidekick layer is open (i.e. displaying the rendered app), then the layout can't even be changed, it seems (not via the UI, and not via the keyboard short-cut).
4. The close button of sidekick layers is almost not visible (I only found it by accident, when I hovered over the area at the border of the layer), which makes (3) even more frustrating

On top of that, Copy link does not work (it doesn't copy anything). Otherwise, I could at least open the example in a new tab.

I tried with Chromium and Firefox, which both behave the same.

If I open a CodeSandbox playground in its own tab, then things seem to work (Copy link works, I don't have to log in on every page load, etc.).

So my assumption is, that there is an issue with how the examples are embedded (maybe the iframe doesn't have the right permissions, or something like that).

My workaround (in case anybody has similar issues), is to get the URL of the iframe (via right-click/inspect), and open it in a separate tab.

I think, it would be good if there was a link above the examples to easily open them in a tab.

Also, in the terminal of the playgrounds I see the following:

$ cargo watch -x run
zsh:1: command not found: cargo

Besides that, as mentioned, the guide looks great :)

[gbj]

@d4h0 Thanks for the feedback. I've updated it to add a link for each sandbox, which should help. CodeSandbox does not provide (afaik) ways to do things like close tabs (the cargo watch one, the sidebar, etc.) and have that reflected in the embedded version, which is unfortunate. If someone else has time to investigate that I'd welcome any advice.

[d4h0]

@gbj: Thank you, this is much better. Btw., CodeSandbox seems to keep 'view'-related settings over page reloads, so the sidebar and sidekick only needs to be removed once.

[Bergvca]

Going through the book right now, so far so good! One minor issue i ran into, in chapter 02_dynamic_attributes.html section "Dynamic Classes", maybe it's an idea to add one line that says "don't forget to add the css class to index.html".

[gbj]

Going through the book right now, so far so good! One minor issue i ran into, in chapter 02_dynamic_attributes.html section "Dynamic Classes", maybe it's an idea to add one line that says "don't forget to add the css class to index.html".

Thanks, just added something here.

[Rucadi]

The link specified in the main comment:

"the book lives in docs/book."

Is no longer valid.

[gbj]

@Rucadi Thanks, it's deployed here (see link in README)

[gbj]

#1152 contains a request for some input on deployment, the final topic. So I'm closing this issue as completed, with much love for you all for your feedback.