React starter template

[MargaretKrutikova]

This PR adds a new minimal react-starter template with webpack configuration, discussed in #4000 .
I have also added some docs on how to add/edit templates and test them locally, since it might help someone else doing it later.

Let me know if there is anything I can improve!

[bobzhang]

This looks great, thanks

[chenglou]

Hello @MargaretKrutikova! And thanks for the contribution. Though unfortunately we might need to reconsider this.
The react-hooks templates is made to encourage exploring and learning, and to explicitly discourage opaque dependencies. Wrapping everything into a single dependency then hiding it out of sight isn't minimal; it sure looks clean, but a clean room can still hide messy clothes in the closets and drawers.
The bundler in react-hooks can be used for development; it's actually carried over from its previous iteration. We can work on tweaking the wording if you'd like to provide some suggestions.
Furthermore, the files are precisely made to be easily deletable. You can delete any file you want, and we'd like to encourage folks to not fear deletion. This is one of the bigger problems in front-end, where we've observed newcomers rarely ever attempt to delete things now. Deletion can sound scary, but might as well teach that with a boilerplate than with real code. Avoiding deletion is a non-goal of ours.
The react-hooks template also serves as a single point of entry for ReasonReact folks. We've had trouble when the maintainer of different userland boilerplates stopped updating their template, but google search or blog posts still link to them. As a result, a large chunk of the community kept using deprecated stuff. Not to mention decision paralysis, etc.
It was a mistake that a I didn't notice #4000 sooner. But I'd like to subsume your existing ideas back into react-hooks. Please comment with more of your thoughts, thanks!

[Yakimych]

@chenglou Interesting insights, thanks for sharing. I think the best we can do from our side is share some feedback from beginners trying to get started with Reason. We've been trying to spread the word here in the Nordics ReasonML community, speaking at meetups, encouraging people to try it out, etc.

Unfortunately, the most common feedback I have been getting when following up with developers, is "We've tried it real quick, but [a number of reasons], so we got discouraged and quit". And the new template is coming up as one of the "number of reasons" quite often (see this thread in the ReasonML chat). One of the other most common reasons being documentation. This has come up at the latest ReasonConf too btw: https://www.youtube.com/watch?v=-2FeCQawnGc (note the applause as soon as it gets mentioned 🙃).

I've also heard people contrast the learning experience with Elm, where beginners are guided from 0 to a basic app that fetches and displays some data from an API, in a straightforward, step-by-step tutorial. The current state of ReasonML docs, on the other hand, is far from beginner friendly.

It would be interesting to hear your take on this, and how you are planning on addressing the issues with the new template in case this minimal version gets removed.

P.S.: More feedback has been collected on Twitter not that long ago: https://twitter.com/matzatorski/status/1201537452164493313

[MargaretKrutikova]

Thanks for your feedback, @chenglou ! I would like to address the points you mentioned in your comments.

Regarding the template being a learning material, I have gotten very negative feedback from a couple of people who I encouraged to try Reason and they tried the react-hooks for the first time. After they have opened a project created with the template they were confused with the amount of code it generated and didn't know where to start. Index.re has four different entry points with raw DOM manipulation which is difficult to read and understand, especially for beginners which might not want to go that deeply right from the start. After one of my colleagues was determined to quit learning reason because of those reasons, I created a very simple template that reminds a lot of create-react-app and suggested he try it instead and eventually it worked better.

My second point is regarding those of us who already know some reason and enjoy creating different projects with it. I don't want to start a project by deleting a lot of files I know I won't use and configuring webpack in case I want to use it in production, since I know I will 😄 I think some of the more experienced users agree that the new template is very difficult to use as a base for new projects.

I feel like create-react-app is a good example of a starter template that can be used to quickly bootstrap a new side-project for regular react users and for those who are just starting out, so I thought taking inspiration from there could be a good idea.

[chenglou]

The step-by-step tutorial is a bit orthogonal to this, though that part needs to be improved too.
I'd like to reiterate that we shouldn't talk about "minimal" if it's a mountain of code hidden behind a clean facade.

The raw dom manipulations were intended. The entry points can be removed without disturbing anything else. If the syntax's harder to read, we can change that instead (and we were trying a while back). I didn't want to bootstrap the entrypoint itself using RR concepts folks might not understand yet, thus the raw DOM manipulations. This can be revisited.

I get the points you're trying to illustrate here, but philosophically I really think we shouldn't overfit for the literal first step at the expense of subsequent steps. I care about newcomer experience, but I also care about the learning curve and transitioning said newcomer to an expert. CRA-style templates is great for a first impression, and we can discuss and tweak our react-hooks template to fit that, but it's no help for learning to modify things structurally. The medium constrains the message and all. I've outlined this in the blog post.

The old template was also problematic because it didn't show how to use the React APIs. A big chunk of complaint was that there are no example skeletons of proper usages. To cover most of these (not edge-case, but frequent) uses, I've tried distilling them into as few examples as possible, and that's the minimum amount I've gotten. Essentially, as much as I'm all about hand-holding a newcomer through the process, we need to create the architectures that lets people with no direct relation with Reason community, without the opportunity to assist to a workshop, to know the space of APIs and how to use them. This is a non-problem during workshops because those often have a fixed goal and funnel every learner through a predetermined golden path.

To extend the last point, one reason why folks can't find authoritative examples of RR usage is because there are too many of them, everywhere, from tutorials to blog posts to userland repos. Ideally we have a single source of truth for good examples. Having more than one template goes against that.

Again, I'm open to tweak the hooks template to meet the needs more. But we need to insist on learnability and understandability over a facade of minimalism (e.g. the bundler and the server). There are ways to make the newcomers overcome the fear of a boilerplate, too. Changing the syntax of dom manipulations would be one, but I digress.

[chenglou]

Btw is it possible to talk about this on hangout with the two of you? I'm trying to do more of live streaming-ish kind of talk because I think there are nuances that are hard to convey on text.

[Yakimych]

Thanks for the detailed walkthrough - everything you're saying makes sense. It does seem, however, that it makes more sense in a context of "authoritative examples or RR usage", but not necessarily as much for a starter/template-kind of project.

"I care about newcomer experience, but I also care about the learning curve and transitioning said newcomer to an expert" - sure, and this makes sense too. The problem I've been observing, however, is that people get "filtered out" at step 0 and never even start the journey from newcomer to expert.

"Essentially, as much as I'm all about hand-holding a newcomer through the process, we need to create the architectures that lets people with no direct relation with Reason community, without the opportunity to assist to a workshop, to know the space of APIs and how to use them." - yet again, I see the point, but one might argue that instead of trying to cram everything into a "template", a better place for learning "the space of APIs and how to use them" would be:

• a good step by step tutorial
• documentation
• a collection of examples

I remember getting started with Reason myself, and I had no issues checking the dog-fetching examples in the now deprecated examples repo - it just seemed like a natural progression after getting going with the basics.

As for transitioning from beginner to expert, perhaps we could borrow some ideas from Elm here too. One of the things they have is a gradual move from Browser.sandbox to element, document and eventually to Browser.application (SPA). Perhaps a guide/tutorial how to start from scratch and eventually get to the current "template" would be more approachable? I am open to a possibility of working on such a guide myself if we manage to get a consensus on how to proceed.
In fact, I've been thinking about how I would go about structuring such a tutorial (or a workshop) - and I get stymied at step 1 - right after bsb init... The only way to go from there is to delete most of the code. Only after that is done, can we dive into the basics. Speaking of which, we're likely to hold such a workshop at a meetup in January/February next year, so any tips are greatly appreciated.

To sum up - I definitely understand and agree with most of the points you've covered, but my feeling is that what you're describing is more like a collection of good usage patterns/examples, rather than a "starter" or "template". I would be happy to discuss this further via a hangout - it could prove useful for sure.

[chenglou]

There used to be an example repo. It got stale because nobody was maintaining it. As I've mentioned in the blog post, the excessive amount of intro tutorials caused trouble too. We have a dedicated location for most pieces of docs; but that doesn't matter if userland creates new tutorials for every concept every so often. Too many tutorials (and starter template) is a real problem.

I've tried the step by step, file-based tutorial using https://github.com/chenglou/intro-to-reason-compilation. I like that format, but it still gets stale. Maybe we can try it here too.

I'd love if you can help us spread the message that it's encouraged to delete code. The template is designed to let you delete code. As a matter of fact these are some of the easiest code to delete (which other boilerplate even encourages that?). We can't expect folks to start deleting production code if they didn't learn anywhere to delete code of lesser importance.

And finally, two starter boilerplates is already too much. At 3 we'll gonna start seeing tutorials about which boilerplate to choose when. Which happened in the past. We can keep discussing about how to shrink things down, but a boilerplate that doesn't cover much of the RR's critical paths, or without proper design thoughts, will just end up soliciting more of the feedback along the line of "I don't know how to use the API", "what if I don't want webpack", "the template doesn't even have proper design", etc. (Latter of which I care a lot, but that's a longer discussion I'm too drained to start on text).

And yeah, please ping me on Discord to set up some time to video chat about this!

[Yakimych]

I'd love if you can help us spread the message that it's encouraged to delete code - I could try, but it's a bit tricky, because I don't believe it is a good idea myself 😄
create-react-app is much slimmer code-wise, and we already see people complaining about having to delete the "Logo" every time. Compared to that, imagine how it feels having to delete a bunch of code in a new language a person doesn't even understand.

I agree with you that 2 templates is too many. My raw opinion is that it's enough with one "starter" that is almost empty (similar to CRA) + a guide on how to reach an application that covers "much of the RR's critical paths" + make this "final" code available for cloning. Not the other way round (when one would start with a lot of code and have to figure out what to delete without breaking everything).

Ok, let's continue on discord/hangouts - thanks!