search

reactjs / react.dev

The React documentation website
https://react.dev/
Creative Commons Attribution 4.0 International
11k stars 7.51k forks source link

New React Docs #3308

Closed rachelnabors closed 1 year ago

rachelnabors commented 3 years ago

Updated September 29, 2022! We're close to completing the remaining pages, and there is now a link to the Beta site from the main site.

Updated October 22, 2021! We have released React Docs Beta. See more details in the announcement and leave feedback on this issue!

Updated June 10, 2021! Full details in this comment.

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:

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.

Thanks so much!—the React Core team

tayiorbeii commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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:

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

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 commented 3 years ago

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 commented 3 years ago

As a translator, let me bring this up again:

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 commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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.

rishabhrathod01 commented 3 years ago

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

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 commented 3 years ago

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

dhanushkac commented 3 years ago

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.

I like this suggestion. I still prefer to see those old life cycle stuff in the tutorial area. I believe the Class-based API is a good approach to expand the understanding of concepts.

dhanushkac commented 3 years ago

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.

Good stuff!! ❤️

armenic commented 3 years ago

The https://reactwithhooks.netlify.app/docs/context.html#updating-context-from-a-nested-component example does not seem to work. Could you please check?

karlhorky commented 3 years ago

@armenic the docs there are not officially created by the React team, so these types of queries probably don't belong in this issue here.

The docs at that URL are created by @neurodynamic at @kickstartcoding - seems like this branch. Unfortunately, that repo doesn't have issues on it, so you can't get in touch via the GitHub repo. But you could probably get in touch via @neurodynamic's website: http://www.neurodynamic.online/contact

neurodynamic commented 3 years ago

@karlhorky Just activated issues; sorry about that! I haven't created a lot of repos where public issues were needed, so I didn't realize you needed to manually activate them!

@armenic I'll try to take a look at this when I have some time. Thanks for the info!

neurodynamic commented 3 years ago

@armenic

Can you tell me if it fixes it for you to take out this line entirely

const statelyToggleTheme = useState(toggleTheme)[0];

And just pass the toggleTheme function to ToggleThemeContext.Provider directly like this:

<ToggleThemeContext.Provider value={toggleTheme}>

That seems to be working for me, but it has been a while since I've touched this code, so it'd be helpful to have someone else confirm to make sure I'm not missing something. I feel like there must've been a reason I added that weird step, but it's also possible I didn't realize that I didn't need to.

armenic commented 3 years ago

excellent work @neurodynamic! 😄 I confirm that this resolves the issue and the example works as expected. Just in case here is the CodeSandbox link https://codesandbox.io/s/react-hooks-update-context-from-nested-component-50y5j Just a dumb question. Does this mean that you are going to update the website too?

neurodynamic commented 3 years ago

@armenic Awesome; thanks!

And yup! Just pushed!

dhanushkac commented 3 years ago

@armenic the docs there are not officially created by the React team, so these types of queries probably don't belong in this issue here.

The docs at that URL are created by @neurodynamic at @kickstartcoding - seems like this branch. Unfortunately, that repo doesn't have issues on it, so you can't get in touch via the GitHub repo. But you could probably get in touch via @neurodynamic's website: http://www.neurodynamic.online/contact

Is there any public repo of new doc writing?

splincool commented 3 years ago

Will you plan to create a style guide for React (as it is for Redux)?

rachelnabors commented 3 years ago

We totally will have a styleguide!

Nothing-Works commented 3 years ago

@rachelnabors Is there a preview version for the new docs? or can we expect that soon? thanks

eps1lon commented 3 years ago

Since this just came up again (and I believe it comes up quite often):

Functional updates are currently a bit hidden under the API reference for setState. They're also currently qualified with a can and it seems to me that whenever you use the previous state to compute the next state you should always use functional updates. Personally, I would probably rather lint against this. Sure, updating the state based on the current state works for a single update in most cases. But as soon as you add more state updates, the existing code is probably incorrect..

This is especially problematic IMO because the very first example of useState computes the next state based on the current state. But we're not warned at this point that this results in stale values once we add more state updates. It might be confusing if people learn setState without functional updates but are later told that they should use functional updates for these kind of updates. Having to decide whether a non-functional state update is safe or not is quite hard. Being able to say "new state is based on previous? -> functional update" seems easier to teach than "new state is based on previous? -> use normal update until you do more than one update in a batch".

Though it's not clear to me whether we should use functional updates in the example or rather use an example that doesn't compute the next state based on the current state.

React issues due to not using functional updates:

markerikson commented 3 years ago

Agreed. We routinely field questions in Reactiflux from users who are dealing with stale state issues in closures or batching issues, which are resolved by having them use the updater syntax.

(also, we constantly have people who think they can do setCounter(count + 1); console.log(count); and have it work right, so anything that can be done to clarify the whole "state updates are batched/async" concept would be really helpful.)

codeforcesmeme commented 3 years ago

Reading this now, I sometimes find my self doing things like 

const newState = deepCopy(state);
// ...
// some long async logic that changes newState
// ...
setState(newState)

Can I ask if this is acceptable, or would this result in a stale state in the code?

eps1lon commented 3 years ago

Are pages linking community resources part of the new docs?

I'm mostly looking for some clarification on what should be included in the docs and what shouldn't. Examples should not use any 3rd party state management libraries but it isn't clear to me if this is still relevant today. Why are 3rd party component library, styling libraries or hook libraries allowed?

Right now I'm ignoring all PRs adding something to community/* pages since there aren't any clear guidelines what should be included in the docs and what shouldn't. Reviewing those with "common sense" probably introduces too much bias. Reviewing example projects at all would take quite a bit of time to begin with. And how do we maintains these lists (broken links, stale content etc)

If we update the docs with hooks in mind we should also revisit all those community links. It's nice to teach hooks from the beginning but if the docs then link to a podcast from 5 years ago then they won't continue on the same path. These older resources are still valuable to understand where we come from but it should be clear that these links are to be understood in an older context.

Context:

gregpasha commented 3 years ago

Hooks are a great addition to React. I think useEffect needs deeper explanation in the docs. Incorporating some of @gaearon's writing at overreacted.io on useEffect will be very helpful.

gaearon commented 3 years ago

Are pages linking community resources part of the new docs?

We've not worked that out yet, and won't for some time. I think it's likely that the new docs won't have those sections, or they would be organized differently.

gregpasha commented 3 years ago

It would be helpful to have official best practices for Typescript. It's hard to know from user-land articles what is current best practices. I am converting a large codebase with AirBNB's code mod and dealing with the migration errors feels arcane and inimical.

markerikson commented 3 years ago

@gregpasha : the unofficial best source for using React+TS together is the "React TypeScript Cheatsheet" site, which tbh is far more comprehensive than anything that would is likely to be included in the docs:

https://react-typescript-cheatsheet.netlify.app/

I'm hoping that the new React docs site would have a basic page on TS usage, but then point to this external resource for more details.

eps1lon commented 3 years ago

I'm creating this issue from my mobile. I'll update the issue with standard template in some time

I want to propose a change to the home page of Reactjs.org website. The to-do app for beginners is filled with too much of code IMO. Can we create a few more steps in it and add things to it incrementally?

We could probably add some animations that look delightful and engaging to the first time users.

-- @KarandikarMihir https://github.com/reactjs/reactjs.org/issues/3613

divyanshu013 commented 3 years ago

I think it would be great to also have a dedicated guide to server side rendering (SSR) with react.

dwesty17 commented 3 years ago

@rachelnabors at the risk of being that guy, is there an updated ETA on this project? Or some way to preview the progress?

We've got some youngsters on the team this summer and they're ready to learn! Excited to see what you all produce. Appreciative of all your hard work 🙏

dwesty17 commented 3 years ago

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

@gaearon a little late to the party here, but I love https://github.com/typescript-cheatsheets/react as a resource. Many of our teams get value from it.

It would be great to see the React docs somewhat officially recognize it as the resource for TypeScript + React best practices.

rachelnabors commented 3 years ago

Hello again!

It’s been awhile since we started the React Docs Reboot (about 8 months to be exact)! Thank you for your patience. It turns out teaching Hooks First involves a lot more than just updating some examples! Here’s a sneak peek of some of the things we’ve been working on:

We’ve been testing with small groups of people from different backgrounds and proficiencies as we go to make sure what we’re writing the right stuff and building the right features. And we’re pretty pleased so far!

Coming soon!

Good news! We are implementing the new site right now, and look forward to sharing a beta with you all later this year.

Volunteering opportunities

Thank you for your patience <3

We know that this new content will impact the careers of millions of developers, and we cannot stress how seriously we take that responsibility. Working on these docs has been like writing a book and building a courseware site at the same time. There’re a lot of concepts and content that has been locked inside the Core Team, and it’s time to share it—in a way that everyone has access to. It’s good work, and we thank you for your patience, your support, and your enthusiasm. You keep us going!

A sketch of React writing documentation

kaushalyap commented 3 years ago

@rachelnabors When can we expect this new docs beta? I heard they are really good!

Jack-Works commented 3 years ago

Maybe irrelevant to this topic, but what about Error boundary? They don't have hooks equivalence to teach.

gmoniava commented 2 years ago

I'd like to share few links which relate to parts of existing docs which quite a few developers found confusing. Hopefully new docs will address these.

rachelnabors commented 2 years ago

Update! We have released React Docs Beta! Full details and call for feedback in the PR!

harshith-venkatesh commented 2 years ago

This is such a great news, excited to read the new React Docs 😄

Kusou1 commented 2 years ago

cool！