Yew: Create full feature battery-included tutorial for yew

[strasdat]

Create full feature battery-included tutorial for yew

Should include:

• Fool proof step by step guide to install relevant dependencies.
• Guide to setup a new yew project (ideally without the need of cloning a repo).
• Guide how to build the web-app and serve it locally.
• Guide how to iterate / debug code changes.
• Introduction to component and html in incremental / interactive fashion.
  (from hello world towards a more complete app such as TODO list.)

The tutorial should rely on standard/agreed on tools such as wasm-pack, and web-sys recommended by the Rust / Wasm Working Group.
It should use the agreed-on approach to build and serve the app (yarn vs. wasm-pack build/rollup vs. python3 -m http.server 8080). Users should not be confused by different alternatives (web-sys, stdweb) - apart from footnotes etc.

Describe alternatives you've considered
Looking forward to comments/feedback from experienced yew developers. I'm happy to adapt this feature request.

Additional context
Unclear whether this should be a gradual evolution of the current doc, of a separate tutorial section.

---

IssueHunt Summary

Backers (Total: $500.00)

• strasdat ($500.00)

Become a backer now!

Or submit a pull request to get the deposits!

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.
  

[issuehunt-app[bot]]

@strasdat has funded $500.00 to this issue.

---

• Submit pull request via IssueHunt to receive this reward.
• Want to contribute? Chip in to this issue via IssueHunt.
• Checkout the IssueHunt Issue Explorer to see more funded issues.
• Need help from developers? Add your repository on IssueHunt to raise funds.

[codec-abc]

I am also very interested in a tutorial with Yew. While I think a step by step is good for getting started easily it would be a great value to also insist on the bigger picture. I found my way around the tooling and environment and my project is running I lack the vision on how to map my problem to Yew. So a few design rules about how to split an app into components and use agents would help people like me that lack the experience with similar libraries (React, Elm, etc...)

[strasdat]

@codec-abc

Please feel free to modify my proposal/wording:

Should include:

Fool proof step by step guide to install relevant dependencies.
Guide to setup a new yew project (ideally without the need of cloning a repo).
Guide how to build the web-app and serve it locally.
Guide how to iterate / debug code changes.
Introduction to component and html in incremental / interactive fashion.
(from hello world towards a more complete app such as TODO list.)
The tutorial should rely on standard/agreed on tools such as wasm-pack, and web-sys recommended by the Rust / Wasm Working Group.
It should use the agreed-on approach to build and serve the app (yarn vs. wasm-pack build/rollup vs. python3 -m http.server 8080). Users should not be confused by different alternatives (web-sys, stdweb) - apart from footnotes etc.

If we agree, I'm happy to update it in the top post!

@codec-abc interested in earning the bounty yourself :D ??

[codec-abc]

Unfortunately, I cannot earn the bounty, at least not for all the points you cited, because I don't master Yew well enough to do it. What I wanted to say is that IMO the tutorial should be a 2 parts one. The first one should be how to get started (the doc does a good job to explain it already but could be refined) and the second should be how to design and structure a Yew application using Messages, Actors and Nested Components (and maybe others topic if needed). This is the part I currently struggle with. I would say the tutorial should aim for an app more complex than a TODO list. It too simple to use advanced topics and grasp a sense of design. I think that you can add that to your original phrasing if this is Ok for you.

[jkelleyrtp]

Hi, I'd be very happy to take this on. I use Yew a lot, and parts of it has actually crept into my day-job.

Here's how we use Yew:

• wasm-pack
• wasm-bindgen

I'm thinking about making the whole thing in markdown so we can either produce a book.toml or as an addendum to the current Yew gitbook.

[jkelleyrtp]

Here's what I've got so far, with big plans to add in more later.
https://www.notion.so/The-Definitive-Yew-User-Guide-0893c8cc101440da9228e4b0be118c39

[codec-abc]

A few days ago I discovered @sheshbabu tutorial for a single page application with Yew. To be honest, it is really good and does a good job at doing something more complex than a simple counter. I especially like that it give a way to design application and split it in smaller part as its evolves. It also gives great insight about state management.

So maybe we can see with the author if its somehow be "part" of the documentation because it is so far one of the best tutorial for Yew.

[sheshbabu]

@codec-abc Thanks for the kind words! ❤️ Let me know how I can help 😊

[codec-abc]

@sheshbabu The mains questions here is will it be okay for you if you work end up in a tutorial? Same for the Yew developers (I think the tutorial would be a great addition but I am not a maintainer so we need to check this with them). Another question would be do you want explicit work attribution (link to the original article, etc..)?

Once these questions sorted, there will be questions about how to include it in the existing documentation. But since both your article and Yew's documentation use Markdown it should be really easy to do. Maybe we will need to split it up in a few parts as Yew's pages are usually not that long.

[sheshbabu]

@codec-abc Sure, I'm okay with it but some parts like FetchService, Agents might require rewriting or rewording. Will wait for the Yew developers' decision 😊

[codec-abc]

@jstarry @siku2 Do you have opinions on this?

[siku2]

I love the idea of having a more complex tutorial in the documentation! @teymour-aldridge is in charge of the documentation so let's include them in this discussion as well.

Side note: if you're on Discord, we have a dedicated #documentation channel if you wish to discuss this live.

[codec-abc]

I gave a shot at integrating the tutorial here. I tried to stay close to the original material. I mostly changed the introduction and conclusion as well as some of minors changes to fit the documentation style. I also removed small passages that were explained in other pages of the documentation.

I can create a PR before but there is a few things I feel there is a few things worth discussing before:

Most of them, ties down to the tutorial containing references to other "things" controlled by sheshbabu.

1. The tutorial refers to HTTP requests using the API module pattern which is hosted on @sheshbabu blog.
2. There are a few references (2 I believe) to the @sheshbabu Github repo.
3. There is a link to a running app which reference https://rustmart-yew.netlify.app.

The potential problems I see is that if the sheshbabu make some change on its side then the documentation page will be out of sync with the content it is referring too. The other way is also true. For example, if the tutorial keep evolving on its own then the code and the tutorial might become out of sync. So, it might be better to have a fork of the code in the depo which could evolve freely if the tutorial is modified later on. It can also happen for the page explaining HTTP requests using the API module pattern and the netlify app.

Except that I feel there is a passage that some of the Yew team does not necessarily agree with. About state management the tutorial contains:

Notice how there’s a direct link between the components that need this state and the global state.

Unfortunately, Yew doesn’t seem to have a good solution for this. The recommended solution is to use Agents for broadcasting state changes via pubsub. This is something I stay away from as it gets messy fast. I hope in future we see something similar to React’s Context, Redux or Mobx etc.

While having insight about state management I don't know if the phrasing match the documentation style. Also if some disagree with this, we might need to explain this not a universal opinion and some people like to handle state management with a different strategy.

[teymour-aldridge]

One potential short-term solution would be to link to a series of "recommended" but unnofficial tutorials.

I think that the problems around ensuring the two remain in sync aren't huge. We should probably fork a copy of the repo and place it under the yewstack organisation. It shouldn't be too hard to host a copy of the app under yew.rs but for the meantime it would probably be fine to just link to the Netlify site (perhaps via the wayback machine).

I think we should explain in the tutorial that the story around state management in Yew is not yet finished and is evolving. (I think that it's natural that state management in Yew will be different to state management in JS libraries because of the differenence between the two languages).

We don't really have a clear "documentation style" as of yet, but my opinion is that we want it to be pretty easy to understand and narrative in style.

[codec-abc]

So basically I can open a PR with just the change for the state management and leaving the links as they are?

[teymour-aldridge]

I guess we can add it and state that the tutorial is a work in progress (and contributions are welcome, as always).