[Silhouette]

The linked React guide is intended to be a pretty comprehensive tutorial — not a getting started guide in the same sense. I wouldn’t say they’re comparable in how much about either of them teaches you about using a library. Maybe it’s not obvious from the wording.

FWIW, I think the current introductory material on the React site is not as effective as how things were in the early days. IMHO, a significant benefit of React in its original form was its simplicity. The whole API practically fit on a single screen. You could write a tutorial that showed the basics of rendering a component or two on a single screen. Today React itself has become more complicated, and the tooling around it even more so, and I'm not sure that extra complexity offers a good return.

Just as a demonstration of my point, please imagine for a moment that you are a developer who understands the basics of the modern JS world but is new to React. Go to the React site and find the instructions on how to just install React with npm or yarn, the way you probably would with any other JS library.

OK, so there's nothing readily visible. No, really. How to just install React like every other JS library in the world isn't even described on the introductory pages. Well, maybe you try running

    {package manager} {install command} react

That used to do the obvious thing, but now it doesn't because even the essentials are divided among multiple packages with non-obvious names. So at this point, just a couple of minutes after you decided to give React a try, you're already confused about how it works in NPM and thinking basic documentation is missing, and you haven't even installed it or written a line of code yet.

Maybe you find a link somewhere to the page about the "most popular and approachable toolchains". OK, that looks promising. You click the link and... you're confronted with create-react-app, Gatsby, Next.js and a bunch of other dubious, heavyweight tools, not that you know that because you've never heard of them. But there's still no sign of how to just install React and try it out like any other JS library.

So you go to the kitchen, make a coffee, come back and ask your mentor whether it's really necessary for you to use such a complicated and difficult tool, and whether you can just use Vue instead.

This comment is based on a true story. :-(

[danabramov]

I think this page is written for that exact use case!

https://reactjs.org/docs/add-react-to-a-website.html

And it’s linked to from the other pages you mention with a disclaimer that a simple HTML page is still the best way to get started. Sure, you can ignore that, but what can we do.

But whether we like it or not, plenty of people want to kick off a single-page app with a whole toolchain rather than just “try React”. Earlier docs that you fondly remember didn’t help with that at all, leading to a lot of frustration.

Some people will be unhappy with either approach. That’s why the docs include instructions for both.

[Silhouette]

I think this page is written for that exact use case!

I understand that this is what the React team think. I am trying to explain that that page (and the other "getting started" level material on the current React site) is not necessarily working very well.

Maybe we're unusual, but among my professional network the overwhelming majority of React users do so with what now seems to be considered a custom tool chain, even if it's just "Bundler + Babel plugin for JSX". The first question everyone asks when they want to try out React, like any other new JS library or tool, is what they need to npm-install or yarn-install to get a minimal example going. And this information has now been hidden away several layers deep on the React site, as if it's an unusual use case.

Loading scripts from CDNs is fine for a very early experiment but quickly outgrown in production environments. There is create-react-app, but most people I know are sceptical about such tools and in any case it's debatable whether you want to start with scaffolding/framework tools if you're learning a new library for the first time and want to understand how it fits into everything else you're doing.

In short, the current site (and your reply here) seem to be predicated on a false dichotomy. Presumably you have access to better metrics than I do as a random individual and you know that most people really do fall into one of those two groups. All I can tell you is that almost no-one I know does, including those I have introduced to React myself in recent times.

Maybe it's just the curse of the modern JS world that everyone feels obligated to try to show how their individual tool or library works with 500 different other tools and libraries. Even so, there's probably a reason that almost every modern JS library's home page seems to have a screenshot with the words "npm install" in it above the fold.

[danabramov]

Thanks for feedback! Will keep that in mind next time we look at the docs. (FWIW we used to do exactly what you said and heard many complaints about that — people didn’t want to see npm, didn’t know what Babel is, and so on.)

[Silhouette]

You're welcome. Again, I appreciate that you probably have much more comprehensive data to go on than my mere anecdotal experience, but I think it would be useful to include a more standard introduction for visitors who don't need so much handle-holding, such as those coming from other libraries/frameworks and already happy setting up tools like Webpack/Browserify/Rollup/etc. Those of us who play the mentor in the previous story would certainly appreciate it. ;-)