Want to add an introduction project

[S3B4S]

Hi! 👋

I've already discussed this with @jtmcgrath but I'd like to get everyone involved.

One thing that I really like to do when trying out a new library is to do the introduction (example: https://www.gatsbyjs.org/tutorial/). I'd like to add one for Refract.

The introduction

Since the power of Refract lies in the way it handles side effects it makes sense to include side effects in the tutorial which will be handled by Refract. I thought of having a simulated environment where you develop a dashboard that receives data and interact with iot devices (iot devices being JS modules). This dashboard acts as the smart hub of this environment.

Goals

As of now I have a couple of requirements in the back of my mind;

• Takes at max 1h.
• For some parts of the intro, first write how you'd handle the event in the non-refract way and then refactor it to use refract. To give users a feel of how it improves the code.
• Users should both be inspired and educated about Refract.

Please let me know your thoughts, I've already started a bit on the dashboard environment and I have several questions related to the PR, but first I'd like to hear here what you guys think of it 😄 .

[troch]

Hi @S3B4S,

Thanks for volunteering, that's really appreciated. A tutorial would be fantastic to get users to try Refract.

Since the power of Refract lies in the way it handles side effects

Actually that's about to change 😬. We have v2 in the pipeline, which is going to focus on more than side-effects, and be a general purpose tool for using reactive programming with React.

I think what's important is to have a step by step plan of what is learned about Refract, and then "decorate" it with a fun example like your idea. We can definitely help with that.

[S3B4S]

Oh interesting, sounds good!

I think your suggestion is a good idea. I'm wondering what the best approach would be to construct that step by step plan. I feel like the both of you could already come up with steps you both want to see while creating v2.

I'm not sure if the docs / API for v2 are already stable enough for me to start learning it. Can you let me know when that's the case? So I can start learning v2 and help with the step by step plan.

[thisRaptori]

Think it might be a good idea to structure this in a similar way to @troch's upcoming ReactiveConf talk actually - it's a little different to the order we've used in the docs at the moment, but might make more sense from a v2 perspective, and having different entry points makes a lot of sense imo!

Plus that'd provide a clear starting point to expand upon 🙂

[S3B4S]

I'm not really sure what structure you mean, is there any place for me to go and see the ReactiveConf talk?

[troch]

There should be a live stream link on reactiveconf.com

[S3B4S]

I admittedly have a bit of a hard time of coming up with -what I consider- a good step by step plan from start to end, but I'll just post the (main) ideas and concepts I want to include that I can think of so far. And hope that you two can expand on it or see things that can be improved.

• Start from scratch, so guiding the user through npm i and importing it etc. (in my opinion it's easy to skip for the people who don't need this and valuable for people new to React).
• Gradually introduce to the idea of presentational/container components and handler/aperture concepts here.
• Inject dependencies and handle side effects, the example here got me enthusiastic.
• I also would like to include Redux, there already examples about handling cases with Redux so I can draw a lot of inspiration from that.
• I want to include the idea of global handlers.
• In your presentation for ReactiveConf, I think the example you gave it also a pretty cool use case and I think it could fit in many ideas we could think of for the introduction.