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.)

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

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.

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. 💪

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

Just asking

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

They are really cool to play around.

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.

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

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 :)

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 (reactjs/hu.reactjs.org#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!

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

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.

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

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

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.

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.

Yes, this is exactly what the post is saying:

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

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.

@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.

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.

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

look forward to best practices examples

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

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.

@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.

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?

It feels good

@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.

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.

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.

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.

@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?

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.

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.

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🤣🤣🤣~

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 facebook/react#14490 (comment) or this.

❤️

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.

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: typescript-eslint/typescript-eslint#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 🙂

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.

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.

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.

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!

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.

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

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.

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.

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).

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.

@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