react.dev
react.dev copied to clipboard
reactjs
New React Docs
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:
- 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.
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:
- 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.
- 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 (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!
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.CSSPropertiesand 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?
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.
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.
@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 Yep exactly. Thought it might be an interesting addition if possible.
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.
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.
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 😊)
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.