Reactjs.org: New React Docs

[rachelnabors]

Over the next months, we're planning to rebuild our website with fresh content!

Since Hooks have become increasingly popular in the React community, we have heard from confused learners as well as industry trainers asking why the docs are still so class component-centric. Additionally, while more and more educational materials for React are being created every day, there are still things not being taught because we have failed to explain them well.

We want to make reactjs.org the best place to grok React. We want to be there with you from the moment you make your first component, to well into your career as your React knowledge deepens and advances.

The plan

The new docs will teach React Hooks-first, with a focus on “how to think in React” and deeply grok React over building an app in React. (There are many amazing frameworks with full stacks, tutorials, and learning paths we will point people to for a holistic kickstart.) We’ll have a section on React’s core concepts as well as an expanded and concise API reference.

Anyone can learn React

We want React to be accessible to learners of all backgrounds, so we’re going to expand our coverage to include:

• explanations of some of the more complex programming concepts for folks just diving into computer science (welcome welcome!)
• visual explanations and diagrams for people with visual learning styles
• interactive code examples for people who learn by doing
• early and integrated use of React DevTools and lint rules, to prepare the learner for real world debugging

Because so much of this is going to be new content with a different structure, most of the existing documentation will be archived rather than edited. (Don’t worry: you’ll still be able to access our “class”-ic docs for legacy and migration work and we’ll set up redirects where appropriate!)

To ensure consistent voice and narrative, Dan and Rachel will start by writing the core of the new content, but later on we will be accepting community contributions as usual when everything is in place.

We’re also surveying the community to learn how you use reactjs.org so we can see what’s working and what isn’t. If you have five minutes to spare, we’d love if you could take our 2020 community survey!

Translations

With the help of our wonderful translators, more people than ever before have access to React. We want to thank our translation community so much for their hard work and commitment to React's v1 docs. Their efforts have allowed people all over the world to learn, teach, and build with React, and we will need their help more than ever when v2 launches. We’ll reach out to start coordinating as soon as we have content ready to translate.

What to expect

We’re aiming to launch the new docs in early 2021. We've got the initial structure in place and are working on a new site we're wrangling design resources for. We've sharing early stage outlines with individual teachers and learners to gather feedback, and as we have more and more content prepared, we will start publishing previews to gather even more feedback. This is an iterative process, and we want to get this right! In the meantime, if you’re looking for the React docs with Hooks, check out this community-maintained version of the docs where all examples use Hooks.

Help us help you! Take the survey!

Want to help? We’re running a survey to help better understand and measure the React community, your needs, and where we can do better. If you have a moment, you’ll be helping us a lot! Please take our survey—and share it with your team, classmates, other people who use and learn React.

[smikitky]

What will the translation process be like? The current translation bot merges everything from the original repo's master branch into each translation repo, but it sees only the master branch.

The easiest approach would be to create a new docs-v2 directory on the master branch, alongside the current docs, so that translators can work on it as soon as new articles are made. (Of course, the new directory doesn't have to be live until it becomes ready in early 2021.)

[ericzorn93]

Always great news to here from the React Core Team. Excited to see the new website.

[jhayworthg]

I think the visual diagrams of how React works will be incredibly helpful. It will encourage the benefits of how React. I am the type of person that likes to know how and why just as much as what when learning something. There is a bit of a mirage when learning React and why it is a great solution to frontend development. Getting a visual example of when a component updates and its relative child components update will go a long way to people understanding the concept.

[jjoselv]

Great! A good moment and place to put all experience gathered from explain complex concepts from Just JavaScript @gaearon AIR?
Btw, count me in for Spanish translations of you want. 💪

[sondh0127]

As a suggestion for an awesome react hook tutorial form 'EpicReact.Dev' https://github.com/kentcdodds/react-hooks

[maifeeulasad]

_Just asking_

In future, is there any chance that Class Components becoming deprecated ?

They are really cool to play around.

[AhmedSayed77]

Adding my two cents, please add a "Why use react" section. I still reference the first talk I've seen that explained why was react invented in the first place. People learn and teach the "how" not the "why", and I think this has two major results:

1. The "x is faster than react" content. This happens because they don't know that speed is no the most important concern for react. Modularity, easy to reason about code, predictability, maintainability, and resilience are.
2. A lot of the developers that I've dealt with personally write code that is not aligned with these reasons. They focus on re-usability, because components and hooks, writing lots of and lots of very small components and I don't even know why.

I'm sorry if this seems like a rant, and its not your fault, but people tend to forget, and as time passes by, it seems that more and more forget why we chose react in the first place.

[fuzunspm]

_Just asking_

In future, is there any chance that Class Components becoming deprecated ?

They are really cool to play around.

I like to use Class Components and I hope it will never be deprecated

[rachelnabors]

Thank you all for your feedback! Love reading your thoughts here! To answer a few concerns:

What will the translation process be like?

We're still figuring this out! As we start having more to share, we'll reach out to the translation community and adopt a plan that works for everyone. (Thanks for your suggestion, btw! Good idea!)

In future, is there any chance that Class Components becoming deprecated ?

Class components are going to be around for years to come—for example, there are tens of thousands in production at Facebook already. However, we do recommend that new apps be built with function components and Hooks, which is why we want those docs front and center. The class component docs will remain available for folks working with those components, and class components themselves might one day be spun out into their own package—but if that did happen, we're provide migration scripts to automate that transition :)

[balazsorban44]

Hi @rachelnabors!

As a core maintainer of the 🇭🇺 Hungarian docs translations, I welcome this update to the docs, as - while working through the docs myself - I too noticed a need for a refresh.

Although, I am now wondering as since we haven't fully finished the translations, how much of the content is expected to change in the next version? Will we be able to transfer some of the translations, or should we start from scratch when the new docs come out?

Our progress has slowed over time (https://github.com/reactjs/hu.reactjs.org/issues/1) as life caught up and got busy with other stuff, but I am still motivated to contribute at my own pace! (There were periods when I was able to translate a dozen pages in a matter of days).

Either way, an estimate of the change in % could give a picture of the forthcoming work to be done, not counting new content. If things could be transferred, do you think this can be done in some kind of an automated/semi-automated process?

Thanks!

[gaearon]

I think there’s a high chance most of the content would be rewritten from scratch.

[balazsorban44]

Thanks @gaearon!

I did not have high hopes anyway, but it is good to know, we will then probably not invest too much into translating new pages, only maintain the current ones by merging the weekly PRs, except if someone with a lot of free time would consider translating anyway. I used up all my energy on work in the last weeks/months.

[fsociety0XX]

thanks @rachelnabors !
Looking forward to see the new react documentation. This is going to be awesome with react 17. 🔥

[michaeldera]

I would like to see more content on the CSS in React. I am aware that React is generally not opinionated when it comes to implementing CSS but it would still be great to see some guides on the subject.... and documentation of stuff like React.CSSProperties

[gaearon]

Can you tell us more about React.CSSProperties and what you'd like to see documented there? This is not a React API but a part of the React TypeScript definitions. But we could maybe include those somewhere.

[csdal]

To introduce functional component first for new users

This is the idea of @0xca0a on Twitter. I totally agree with him.

Introducing React with class-based component makes new users push back away from learning React.
I also faced this experience. I wanted to learn React so many times but after reading front page examples, I left out of the website.

[gaearon]

Yes, this is exactly what the post is saying:

The new docs will teach React Hooks-first, [...]

[michaeldera]

Can you tell us more about React.CSSProperties and what you'd like to see documented there? This is not a React API but a part of the React TypeScript definitions. But we could maybe include those somewhere.

I think it would be helpful in general to have the TypeScript definitions mentioned or simply a link to the documentation of those and other definitions if possible. If the community using TypeScript with React is large enough, it would be nice to have documentation for people using React with TypeScript. It is not difficult to figure out but could be easier to figure out if there is documentation to read.

[gaearon]

@michaeldera Have you found any external resources on this topic particularly helpful? E.g. https://github.com/typescript-cheatsheets/react? Maybe we could integrate or link to them.

[IljaDaderko]

Not sure if it falls under the issue, but I'd love to dive deeper into concepts like reconciliation. While there plenty of examples available, it would be nice to have official docs covering this as well.

[gaearon]

@IljaDaderko Tell us more about what aspects you feel isn't adequately covered?

[michaeldera]

https://create-react-app.dev/docs/adding-typescript/

@michaeldera Have you found any external resources on this topic particularly helpful? E.g. https://github.com/typescript-cheatsheets/react? Maybe we could integrate or link to them.

It has been blogs on the most part and the guide on https://create-react-app.dev/docs/adding-typescript/, when I started out I fell back on code completion when I am using types.

[thmsrmbld]

I'd like to suggest a +1 on additional graphics / visuals on how React works from a lifecycle and structural perspective. I'm an extremely visual learner and I think it could be a good addition for those who respond easily to visual patterns rather than strictly logical ones.

Great work though thank you for your extremely clear writing.

[IljaDaderko]

@gaearon Sure. I might be missing something, but to the best of my knowledge this https://github.com/facebook/react/blob/master/packages/react-dom/src/client/ReactDOM.js is closes to documentation there is for react-reconciler. When I was starting out, I referenced this file alongside some videos like https://www.youtube.com/watch?v=CGpMlWVcHok which helped out a lot.

With time I saw fewunstable_ methods pop up in react-dom's host config and it seems that some methods talked about in video above are no longer used i.e. supportsMutation.

For the most part, I am able to figure out what's going on by going through commits and following some people on twitter i.e. https://twitter.com/0xca0a (works on react-three-fiber)

As you can imagine relying on process above results in some confusion and probably doesn't cover some important parts. Hence, I'd love to see structured documentation around this, to dive deeper and better understand all these methods i.e. why are they needed, when are they fired etc... in my head I am imagining "advanced" section of docs for something like this.

[gaearon]

I think you're asking for documentation for creating custom renderers?

[IljaDaderko]

@gaearon Yep exactly. Thought it might be an interesting addition if possible.

[rafgraph]

I’d like to see TypeScript become a first class citizen in the docs (it already is in create-react-app). My suggestion would be to have all code samples available in both JavaScript and TypeScript and be able to toggle between the two.

[trigunam]

Testing react is been quite a challenge due to various techniques we use with Enzyme and Jest. However if there are ways to test for unit and components separately and how to differentiate for React components would be a great addition. Cheers! Looking forward.

[technoplato]

When React Native did their site rewrite, they let the community help out. Can we do the same here? If so, is there a way to sign up? (No T Shirt necessary, just want to give back a little to the excellent tools that help produce my family’s livelihood 😊)

[technoplato]

I’d like to see TypeScript become a first class citizen in the docs (it already is in create-react-app). My suggestion would be to have all code samples available in both JavaScript and TypeScript and be able to toggle between the two.

Further on that, I’ve been tinkering with the idea of having a very lightweight solution to having your preferences “follow” you by default across sites.

Example: if I’m looking at React Native and I’m on a Mac and I want to view docs in TS, I’ve got to manually select those each time. I understand the docs pretty well at this point, but it still adds to the cognitive load every time I have to evaluate that “if” in my head... it would be awesome for doc publishers to be able to opt in to some super easy API to support that.

[GooBall]

I'm actually really interested in the idea of adding some more general introduction into computer science and the problems react tries to solve compared to other solutions (even compared to HTML/CSS/jQuery).

At first thought, it might seem a little outside the scope of the react documentation to supply people with that type of information, however the fact that react is now a starting point for so many new developers means there is a bit of a void in fundamental understanding that the documentation is well positioned to fill.

I've known a few devs who have been started on react right way and so they can't even begin to answer "why" they are using it (beyond "it's what the project is written in").

And on a more personal note, +1 for typescript examples for everything!

[markerikson]

@rafgraph , @technoplato : FWIW, @phryneas just built a great Remark plugin for the Redux Toolkit docs that lets us write code samples in TypeScript, automatically compiles them to JS as well, and generates tabs for each. I think the language selection is also (semi-?)persistent:

https://github.com/phryneas/remark-typescript-tools

Per the readme:

Currently it is aimed at docusaurus, but already pretty configurable. And it's open source, pull requests for more configuration options are always welcome ;)

You can see them in action here:

https://redux-toolkit.js.org/api/createSlice

Looks like the React docs are using Remark internally as well, so that could very well be added over here.

And @gaearon , yeah, I would strongly recommend that the React docs add a "Usage with TypeScript" section with at least the basics, and that page should definitely link to the React+TS Cheatsheet for more details.

FWIW, when we did a poll of /r/reactjs at the start of the year, the results showed that 50% of React devs were using plain JS, 48% were using TS, and 2% used Flow. So, potentially half the userbase is using TS at this point:

https://www.swyx.io/react-survey-2019/

[ChiragRupani]

There is good things going on refreshing React documentation - especially it would be nice it can cover some practical scenarios like Calling API, Showing loading indicator while doing async activity, some suggestions for form handling, input validation, designing services, common UI patterns like dialogs, file pickers, drop downs and other common design problems. It would be helpful to have examples for testing different scenarios and instead of separate section for testing - for each example how it can be tested should be right there.

However, if goal is to make to React to easy to understand then there is no need to archive class related doc and entire docs rewritten in hooks. Both Class and functional Component can be first class citizens. There can options for users to show example in hooks or class. Another way - to have Class Component all along and wherever applicable - both Class + Functional (using hooks) examples can be added. This way docs would be generic and more focus on React way and less on particular class/hooks way.

Also, as others said, it would be nice to have examples in TypeScript.

[darcusfenix]

I would like to see more about why React JS is "A declarative, efficient, and flexible JavaScript library for building user interfaces"

Declarative Views is so important !
there is not enough information about declarative views or declarative programing here

what do you think ?

[littlepoolshark]

I would like to see some in-depth and rigorous elaboration on the core terms of react

[Snowflake107]

yes please

[debel27]

I would like to see some in-depth and rigorous elaboration on the core terms of react

If I had to pick one thing about doc improvement, it would be that. Some side articles written by the core team helped me really understand React and write better React code. Here are some of them :

• https://reactjs.org/blog/2015/12/18/react-components-elements-and-instances.html
• https://overreacted.io/react-as-a-ui-runtime/ (e.g. the "Inversion of Control" section)

I would be great to have them integrated in the doc somehow.

[maifeeulasad]

maybe some installation step like this : https://maifeeulasad.github.io/reactjs-beginner/day/0/

i think, as one should install node and etc. so these types of doc should be included in official doc.

[njzydark]

look forward to best practices examples

[adibfirman]

Please adding an interactive documentation, at the moment the documentation react is very useful, but when we can edit the example code on documentation it's easier to learn what's the meaning of that code, thanks

[laoshaw]

can you make the site layout customizable, e.g. I'd like to the content category/menu on the left side instead of the right side, also a day/night reading mode will be nice.

[rafgraph]

@rachelnabors there seems to be a decent amount of support in this thread for more TypeScript in the docs. Curious if you have data on when starting a new React project do people use plain JS, TypeScript, or Flow? I noticed that a question like this wasn't included in the React 2020 Community Survey.

[rafgraph]

As @markerikson mentioned:

FWIW, when we did a poll of /r/reactjs at the start of the year, the results showed that 50% of React devs were using plain JS, 48% were using TS, and 2% used Flow. So, potentially half the userbase is using TS at this point:
https://www.swyx.io/react-survey-2019/

@rachelnabors does this seem accurate to you?

[bansalvks]

It feels good

[laoshaw]

@rachelnabors there seems to be a decent amount of support in this thread for more TypeScript in the docs. Curious if you have data on when starting a new React project do people use plain JS, TypeScript, or Flow? I noticed that a question like this wasn't included in the React 2020 Community Survey.

TS is yet another layer adding to the complex JS ecosystem and is in no way beginner friendly, I would strongly recommend React site just focus on native JS instead. When a beginner gets really comfortable with JS he/she might or might not move to TS...tutorial must be beginner friendly, the JS frontend's biggest problem is already too-much-info to begin with.

[keymastervn]

To me, people tend to meet TypeScript will find their way on the learning curves. Plain JS and dynamic-typed languages have their missions for a friendly happy coding experience, in contrast to TypeScript that may creates complexity and confusion to some starter levels.

[phryneas]

Which is why it would be great if

• every example would exist in pure JavaScript
• every example would also exist in TypeScript so that people who want to know how that would look in TypeScript could just look at the example in TypeScript and JavaScript and compare the two.

You know, not make TypeScript more difficult than it already is by having people guess how to use it, but give people tangible examples that show them how it could be used - without forcing them to use it of course. See the examples from the redux toolkit docs that @markerikson linked above.

[jakubdrozdek]

I remember learning Rust language not longer than 1 year ago. I got really surprised by the number of different approaches in the documentation. They linked to an "example-based" version for people who prefer learning that way. There was also a strict reference guide for oldboys. And they even had simple exercises (katas) in a repo you could clone, that included tests and some failing code. I know that's a lot and I can imagine they are maintained by different groups, but I've never seen anything like that and was really delighted. Worth keeping in mind that people learn in different ways.

I'd say we need more examples, written in both TS and JS, that could be run in the browser. I remember learning from W3Schools at some point and it was very valuable for me to be able to test the code without loosing context and focus. But I'm happy enough with the output comments in the code :)

I'd like to see more structural and testing best practices, and some explanation WHY it's the best practice and what problem does it solve. Common pitfalls would be great, too, since React lets you write the code in thousand different ways, while some of them lead to doom. I know there are lots of examples in the current docs, but there could be more, especially for high-level architecture.

[technoplato]

@rachelnabors @gaearon This issue is getting a little cluttered, but is there going to be a thread on how we can help or are you keeping this rewrite as an internal task?

[gaearon]

We're keeping this issue for free-form comments and ideas although we don't promise to respond to every one of those (but we do read through them all regularly). We haven't started any writing yet so there isn't anything you can help with at this point. But when we get to a place that we have something to show, we'll update the thread and possibly spin up subthreads for specific things where the community could help.

[tayiorbeii]

Hey @rachelnabors and @gaearon , I recently did a deep dive read into the docs as they currently are published. For each section I have bullet point takeaways for the Big Ideas, Fundamental knowledge, and Skills that I could share if it would be helpful for you!

My notes aren't currently published (private Roam page), but I'm happy to get them to you.

[kongmoumou]

I hope the new docs would cover more "why" content (e.g. why is it designed like this) and the internal mechanism & concepts of React. Keep making epic library🤣🤣🤣~

[donaldpipowitch]

Like others I recently looked into the useMemo discussions on Twitter. I was quite surprised to learn that useMemo is _not_ stable. I thought by now I have quite a good understanding about hooks, but that was news to me.

I later looked up the docs and wondered why I was so mistaken, but even with _knowing_ what to look for I found the docs still confusing.

Some quick notes:

• About the first sentence _"Returns a memoized value."_: I'd love to see a beginner friendly (maybe React specific) short explanation about what this is. I think the link to Wikipedia might be a little bit distracting as you navigate away from the React docs when you just wanted to learn about useMemo and the Wikipedia article might also be a little bit overwhelming. I'd move this to the end (or create a dedicated page to explain memoization tailored for React devs).
• About the third sentence _"useMemo will only recompute the memoized value when one of the dependencies has changed."_: As far as I can tell from the Twitter discussion this sentence is _wrong_ and if you stop reading right here you'll not figure out the nuances, because the following sentences are about a different topic and I'd not expect to _later_ read more about _semantic guarantees_.
• useCallback is explained before useMemo: It's also about memoization and according to use-memo-one _also_ not stable, but it has no sentence about _semantic guarantees_. I'm super confused right now if useCallback is stable or not. Can also at any time a new callback be created even if the deps haven't changed? I also wonder if useCallback can be seen as a more specialized variant of useMemo. If yes, I'd switch their order. In any case I'd like to know why I should use useCallback(() => {}, []) instead of useMemo(() => () => {}, []).
• The yellow note about the deps array is a little bit distracting. It's good to know, but also applies to several hooks and I'd maybe create a separate page to explain this fact and just link from useMemo to this page (something like _"Learn more about the concept of the deps array here."_). The note about _semantic guarantees_ seems to be the more important information for that specific hook.

So something along those lines:

---

useMemo

const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

By passing a “create” function and an array of dependencies useMemo allows you to avoid computing a value on every render by memoizing the returned value.

The returned value will most of the time only be recalculated when one of the dependencies has changed. Treat this purely as a performance optimization, not as a semantic guarantee. The logic of your code should not change by introducing or removing useMemo.

In the future, React may choose to “forget” some previously memoized values and recalculate them on next render, e.g. to free memory for offscreen components.

Remember that the function passed to useMemo runs during rendering. Don’t do anything there that you wouldn’t normally do while rendering. For example, side effects belong in useEffect, not useMemo.

Also don't return callbacks in the "create" function of useMemo. Use useCallback for that, because... (_fill with explanation_)

If no array is provided, a new value will be computed on every render. (_Would there ever be a use case for that? TypeScript throws a typing error for that. Maybe the linter checks for that as well? I'd just remove this sentence or explain _when_ you actually would want that._)

Here you can learn more about the concept of memoization.

---

Thanks for looking into writing new documentation. Also based on the useMemo Twitter discussion I'd love to see even more examples. Examples, examples, examples. That's how I personally learn the best. Stuff like this https://github.com/facebook/react/issues/14490#issuecomment-454973512 or this.

❤️

[textbook]

It might be worth looking at what the Angular team have done with their docs to improve the experience for developers new to it, see e.g. https://blog.angular.io/angular-thoughts-on-docs-74dd343039c0.

[kachkaev]

Here are two small ideas that could potentially ease the journey for the newcomers. Both of them are based on the _fewer things to learn_ principle.

Arrow functions everywhere

Since the introduction of function components in React, they are typically presented in the docs using the function keyword. The hooks, however, leverage arrow functions in the same learning material. This results into a mix of two syntactic styles for the same concept:

function Example() { // <—————————————————————————————————— 👀 style 1
  const [count, setCount] = useState(0);
  return (
    <div>
      <p>You clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}> // <———— 👀 style 2
        Click me
      </button>
    </div>
  );

Experienced developers might not notice any problems here, but if we put ourselves into the shoes of someone seeing JavaScript for the first time, it is easy to imagine confusion.

Since we can’t (and should not) avoid arrow functions, how about dropping the function keyword from the docs completely? A separate general course on JavaScript could introduce the ‘legacy’ keyword-based function style and explain the difference in handling this – sure. However, this extra knowledge will not be on the path to creating one’s first React app and celebrating the victory 🙂

ESLint users can enable the func-style rule in their projects, which will encourage the beginner-friendly consistency. We have the rule in the company’s linting config and it seems to work well. One TypeScript-specific edge case is the only small exception: https://github.com/typescript-eslint/typescript-eslint/issues/1236

Speaking of typings, adding them to the arrow-style components is also straightforward (just like for any other const).

- const Example = (props) => {/* */}
+ const Example = (props: ExampleProps) => {/* */}
or
+ const Example: FunctionComponent<ExampleProps> = (props) => {/* */}

_Where would I place FunctionComponent<ExampleProps> if I had the function keyword? Need to search for that to remind myself of the syntax._

Having said the above, I understand the value of the function keyword in the context of the component names and the default exports. So the second thing I would suggest for the updated docs is:

No default exports

Default exports are hard [1] [2]. The default keyword is not just a yet another word to type, it is a yet another concept to make sense of. We’ll be in the world of commonjs/esnext modules for quite a while and the interoperability problem will stay with us for years. I’ve been reading on the intricacies of default exports several times, but I still feel gaps in the knowledge.

Arrow functions exported by default become anonymous, which causes issues with debugging and a bunch of other problems. A common pathway to this knowledge is through trial and error, which is somewhat unfortunate.

If we use default exports for _any kinds of React components_, we can no longer do this in some index.js/ts file:

export * from "./MyComponent"
export * from "./MyAnotherComponent"

It has to be:

export { default as MyComponent } from "./MyComponent"
export { default as MyAnotherComponent } from "./MyAnotherComponent"

or even

export { default as MyComponent } from "./MyComponent"
export type { MyComponentProps } from "./MyComponent"
export { default as MyOtherComponent } from "./MyOtherComponent"
export type { MyOtherComponentProps } from "./MyOtherComponent"

😭 Many of us have been there.

---

From my personal experience, banning the function keyword via ESLint’s func-style and also avoiding default exports via import/no-default-export can be a positive change.

A codebase that is configured with both constraints has a smaller variety of syntactic structures. The rhythm improves and the contributors have less questions to ask themselves while writing the code because there are fewer options. Consequently, there are also fewer things to explain to a newcomer and fewer things to learn if _I’m_ the newcomer.

React docs are popular enough to steer the JavaScript community away from the described complexities. I’m sure that many people experience them every day, but the problems often remain under the radar because they seem too small if at all noticed by the codebase owners.

I’m happy to be corrected if my thinking has brought me to the wrong conclusions. In any case, thanks for reading 🙂

[shihabus]

Wow, that would be great. One thing I would like to add is, it would be great if we could have some more insights about Fiber in the new docs.

[RitikDua]

I would like to know some more comparisons between class based and hooks based examples. It would be nice if they also provide some typescript based examples too.

[laoshaw]

The selling point of Vue/Preact/etc is that they're good for 'small applications' while React and Angular are good for large complex even enterprise applications, that pushes many beginners away from React. Many developers are saying their small startup can get a Vue application working in a short period of time and it is impossible to do that with React or Angular, are these myth still true? If not, showing some real world small-to-middle-scale demo applications will be extremely convincing(eg simple routing basic state management with a few pages), the big-complex-enterprise React apps are, after all, not a lot in the real world.

[rachelnabors]

When React Native did their site rewrite, they let the community help out. Can we do the same here?

I love your enthusiasm! I ran that documentation drive—we needed lots of updates to example code and embeds. It was labor intensive! Here, the effort is going into the careful planning of the docs, the writing, examples, and illustrations. This is much harder to delegate and parallelize—how would you help Dan write Overreacted? The best way the community can help is with the translation efforts—which will be considerable, as this is a complete rewrite. But if more opportunities arise, we will be sure to make an issue here and put out a call for help!

@rachelnabors there seems to be a decent amount of support in this thread for more TypeScript in the docs. Curious if you have data on when starting a new React project do people use plain JS, TypeScript, or Flow? I noticed that a question like this wasn't included in the React 2020 Community Survey.

Darn, one of those things we should've asked! It'll go into the 2021 survey for sure :) But those numbers wouldn't impact whether or not we will feature TS/Flow more in the docs—if it's the right/maintainable thing to do for learners, we'll do it!

[rafgraph]

The best way the community can help is with the translation efforts

if it's the right/maintainable thing to do for learners, we'll do it!

Great! If the React core team doesn't think it's maintainable to create a TypeScript translation of every code example, maybe the docs could be set up so the community can provide the TypeScript translations that appear in the docs along side the JavaScript version (toggle between the two). Maybe it could work like this, React core team writes examples in JavaScript, community translates them to TypeScript, both versions appear in the docs.

[Aprillion]

Here, the effort is going into the careful planning of the docs, the writing, examples, and illustrations. This is much harder to delegate and parallelize—how would you help Dan write Overreacted?

Hmm, claiming that something is hard to parallelize was probably not meant as a challenge, but here are my thoughts for inspiration :)

1. extract "core concepts" or "dictionary definitions" from current docs => community contributions possible
   e.g. render: (1) ReactDOM.render function, (2) method of a class component, (3) stage in React reconciliations, (4) the stuff that browser is doing to display DOM+CSSOM on screen, (5) one execution of a function Component, (6) commit
2. choose which concepts and synonyms should be 1st-class citizens in the new docs => Dan+Rachel
3. publish a dictionary => community review
4. (in parallel with 1 and 3) make a list of chapters inspired by current docs => Dan+Rachel
5. write a draft of hello world => Dan+Rachel + internal review
6. send the draft for community review => hopefully something like Just JavaScript, maybe invite comments in a GitHub PR instead of mailing list (to be able to mark comments as "resolved" easily)... Dan and Rachel should probably disable notifications from these comments and have a look only once per day... 🙈 dedicated moderators will be needed to filter spam and merge topics from individual comments into common threads (you might need to convince GitHub to implement more moderating features)
7. (in parallel with 6) make a draft of another chapter => Dan+Rachel when not distracted by 6
8. finalize a chapter, freeze discussion (do not allow more comments in the PR, only as new issues) => Dan+Rachel + moderators fending off (I mean, gently apologizing to) late contributors
9. repeat chaotically for more chapters
10. fix race conditions
11. ask for community translations

[stephan-noel]

Looks like I missed the survey, I will just leave some suggestions here:

• Emphasize composition as a feature, currently using children seems "advanced"
• Related, can we bring back the owner/ownee vs. parent/child terminology, especially in the light of performance? Saying that a "parent" causes a rerender is sometimes vague, and just plain wrong ( I'm speaking in the context of this https://twitter.com/ryanflorence/status/1096134603511816192 ). Also please make it explicit that re-rendering "flows through" the owner/ownee tree, not the parent/child tree.
• "Render" seems overloaded. In the beginning it took me a while to get the difference between the meaning of "render" as executing the render method (or body of function component) vs changing the DOM in the browser.
• Please give examples of what a side-effect means in React, like modifying an instance variable, especially for custom hooks and function components.
• Improve forwardRef docs, I see some people still using forwardedRef because of the HoC example
• Please make it explicit that keys are not directly about performance but about identity , and make it explicit that it has nothing to do with map(), people seem to always think "if (and only if) you have a map, you need a key", leading to some interesting bugs with conditional rendering and stateful siblings of the same component type. An example of problems with conditional rendering would be useful in the advanced docs.
• For class lifecyles, this diagram based on Dan's tweet would be really useful if it were inline in the docs.
• For useEffect please emphasize that the dependency array is for keeping in sync with surrounding, and for conditional execution, you can use conditional logic inside of your useEffect.
• As TypeScript is becoming more popular, could we link to here at least https://github.com/typescript-cheatsheets/react ?

Also, it is really frustrating that so much interesting and in-depth React knowledge is available only through tweets that I may be lucky enough to stumble upon somehow. Don't get me wrong, I really appreciate this, but there is so much that could be part of the "Advanced React docs". It would be great if, in addition to it being on Twitter, someone could use a link or something to easily open an issue/PR to integrate that knowledge into the advanced docs somehow, just so those gems of knowledge don't get lost in the Twitter blackhole.

[gaearon]

Thanks @stephan-noel for the list. All of these have been bugging me for some time and I'm glad other people have similar conclusions. I can't promise we'll nail each of these points and there's always a balance between telling too much and too little, but they're on our minds.

[smikitky]

As a translator, let me bring this up again:

• Please make the doc as self-contained as possible.
• When that's not possible, please avoid confusing link text like "this", "said", "here", etc., and please visually distinguish external links and internal links (#1609).

React docs have hundreds of external links, which is basically good for advanced concepts and supplementary materials. However, the current docs sometimes rely on external pages even to explain fundamental concepts. Many React devs cannot read them simply because they don't speak English. As an example, the current "Hello World" page has this:

Note
This guide occasionally uses some of the newer JavaScript syntax in the examples. If you haven’t worked with JavaScript in the last few years, these three points should get you most of the way.

And this "these three points" links to a short external Gist written only in English. This would disappoint non-English speakers and make them reluctant to click other useful links in the future. In this case, the content of the link could have been included in the original docs so that we can translate it. When this is not possible, the docs should cite the full (English) title of the linked page to signal it links is to an external resource (and this is good from the accessibility standpoint, anyway).

[gaearon]

Ah interesting, thanks for feedback. It’s a tricky balance but hopefully if we make some UI affordances like collapsible content, we should be able to fit more info into the doc itself.

[markerikson]

@gaearon fwiw, I added a "Detailed Explanation" component to the Redux docs that uses a <details> tag as a way to hide extended explanations. That way it doesn't interrupt the main flow, but it's still there if you want to see it:

https://redux.js.org/style-guide/style-guide#treat-reducers-as-state-machines

https://redux.js.org/tutorials/essentials/part-2-app-structure#redux-slices

[markerikson]

Opened up #3435 to suggest that we add a note to the front page and tutorial pages pointing over to https://reactwithhooks.netlify.app/ as a recommended place to see the current React tutorials using hooks, as a placeholder until this new docs rewrite is ready.

[Rishabh-Rathod]

As hooks ( Functional components ) are being common and beginners may not need to learn Class components API.
it would be great if there could be a component lifecycle docs without class components API where the beginner could understand what is

• mounting
• unmounting
• rendering
  without mentioning componentDidMount, componentDidUpdate and componentWillUnMount.

why?
one of the beginner learning react, created nested components for example

const ComponentA = () => {

    const ComponentB = () => { // this will unmount and mount on every render of componentA
        return <div>B</div>
    }
return (<div>
   <ComponentB/>
  </div>)
} 

and as there is no mention of this being bad practice and he didn't realize this till faced some issue because of it.

[armenic]

thanks so much for creating the withhooks site https://reactwithhooks.netlify.app !!!