New React Docs - Githubissues

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:

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.

Thanks so much!—the React Core team

ziqiangai commented 2 years ago

Hope Chinese Doc

dahui4dev commented 2 years ago

Hope Chinese Doc

The Chinese document is here, if you are interested, you can translate it together. https://github.com/reactjs/zh-hans.reactjs.org

gaearon commented 2 years ago

Note we think it might be a bit premature translating as we’re still planning significant revisions to the content. Though we can’t stop you :-)

dahui4dev commented 2 years ago

OK, we'll wait until the content is stable before we start translating. We will continue to pay attention.

erikras commented 2 years ago

https://beta.reactjs.org/learn/managing-state#choosing-the-state-structure

        Your full name is: {fullName}

Why wouldn't you just do

        Your full name is: {firstName} {lastName}

and let the JSX do the string concatenation? OR just do

const fullName = `${firstName} ${lastName}`

on every render rather than store fullName in useState()? My general rule of thumb has been "If you can calculate it – and it's cheap to do so (e.g. a sum) – don't store the result in state. Am I wrong?

gaearon commented 2 years ago

My general rule of thumb has been "If you can calculate it – and it's cheap to do so (e.g. a sum) – don't store the result in state.

Isn’t that what the text suggests to do? The “fixed” version below doesn’t use state for it.

dorianmarie commented 2 years ago

Can't find useEffect docs for instance

ahmed2m commented 2 years ago

Can't find useEffect docs for instance

It says at the home page API Reference is about 5% done, only useState and DOM's render have content in them.

djfarly commented 2 years ago

As someone teaching react I cannot thank you people enough. It's such a relieve to have a documentation site where you can send students that learn about react for the first time without worry. All the cruft on the old docs makes it incredibly hard to have people figure out new concepts by themselfes. Everyone get's caught up in some class component jumble at some point.

I've read through the new docs as far as they exist and I love the new format! The code examples annotated by numbers are fantastic.

My only slight criticism is that the guides feels a bit lenghty. That's good because it covers most questions that arise on all levels of working with react. On the other hand it can feel quite overwhelming when learning react for the first time.

chrisdrifte commented 2 years ago

When updating state with a value that is calculated from previous state, it's my view that a functional update is the proper method. I raised this issue some months ago, with agreement that it would be resolved in the new docs.

Unfortunately the new useState documentation relies on closures to obtain previous state, which - while it works in the examples given - can cause difficult-to-debug unexpected behaviour as code becomes more complex.

Therefore, in the examples given for useState, I believe that count + 1 should be replaced with count => count + 1.

EDIT: A bigger but better change would be to set state to something that doesn't rely on previous state -- thereby avoiding introducing two concepts at once. For example, setting state to Math.random() or a similar value that changes on its own.

erikras commented 2 years ago

Isn’t that what the text suggests to do? The “fixed” version below doesn’t use state for it.

Ahhh!!! Well, in that case, my feedback is that it wasn't obvious that it was broken into two parts:

Here's how you might naively think to do it.
Here's how you REALLY should do it.

That could be improved.

borjadotai commented 2 years ago

Hi there! 👋

Is there any place to help out / give feedback on the new docs? Currently going over them - they look amazing btw, I think this is going to make react even more accessible for anybody to learn! - and found that on this page there is a link (in the note section) to a blog post JSX and React are two separate things that seems to be down or point to the wrong place.

Thank you so much for putting these new docs together!

jkillian commented 2 years ago

The new docs look amazing! I've often been asked by coworkers learning React what the best reference is, and have been hesitant to link the official docs because they mostly relied on class-based components. I can tell already these new docs will be a wonderful resource to share, so thank you!

That said, I do have a bit of a concern with the direction of the API reference section when looking at the example of the useState docs. In my opinion, it seems quite verbose and hard to grok at a glance. For example (see screenshot below) an entire laptop screen's worth of space is spent explaining the basics of JS arrow function syntax, the 'using state' and 'declaring a state variable' sections are quite similar, a paragraph elsewhere is spent explaining array destructuring, etc.

My thought is that the API reference should be a fairly information-dense and succinct description of the API in question. (That doesn't mean gotcha's and such shouldn't be documented here, but they should typically revolve around gotchas of the specific API with regards to how React specifically works.)

In other words, my preference is that the API reference should be targeted towards developers who have a reasonable grasp on the basics of JS and React already and be an easy to consult reference for the API's purpose and technical details. The 'Learn' section on the other hand seems like a great place for new React developers to start and would be a more appropriate place for expanding on things like how to write arrow functions properly.

Thoughts?

An example of the current lack of technical density:

ruimcf commented 2 years ago

The example in https://beta.reactjs.org/reference/usestate#updating-objects-and-arrays-in-state does not work great on a mobile device (tested with android).

Also, the copy link button next to section headers do not copy the link when using a mobile device (tested with android as well)

rainy-25Ghz commented 2 years ago

thank you for the great work! btw,is there a plan for change the doc website into a pwa for better experience on mobile?

nlopin commented 2 years ago

Thank you for an amazing job! The new docs look fresh and especially nice on smaller screens.

What is your plan for the "Home" section of the sidebar? At the moment it is the default section when a user opens the documentation and it looks empty. They need to proactively click "Learn" to see the list of articles. I bet those articles is the target for many

yemirhan commented 2 years ago

Thank you for the complete rewrite of the docs!

For the people who don't know English really well, what is your roadmap for localization? I want to help about the Turkish translation, so what can I do for that?

--Edit-- Nevermind, I glossed over the translations part, hahah.

auvipy commented 2 years ago

this is the 2nd best part of react after introducing react hooks! functional programming and learning react as a developer would be much sane from now on.

shrirambalaji commented 2 years ago

@rachelnabors Fixed an issue with ConsoleBlock tab text not being readable in dark mode. Please review https://github.com/reactjs/reactjs.org/pull/3983

artidataio commented 2 years ago

👍 Examples are written in hooks rather than classe component 👍 More emphasis on use case rather than abstract concept 👍 Beginner web dev friendly, but still good for revision

Aprillion commented 2 years ago

🧡 I love the position: sticky for expanded Sandbox Preview. Nice little detail that made my day better 👌

promet99 commented 2 years ago

Great! Both content and design are perfect

I'm sure others have noticed this, but after consecutively pressing "next" button inside the code example from the link(https://beta.reactjs.org/learn/state-a-components-memory#when-a-regular-variable-isnt-enough) more than 13 times, the example broke!

Quite sure it can be fixed with a very small code touch, are you open to PR currently?

codams commented 2 years ago

Hi ! Content is really great, I like the global tone. The design is classic for docs, it works :) It would be good to keep dark/light mode preference to prevent users from having to set it everytime they go on the docs though, it's been asked before but are you open to PR ?

PS. if french translation is needed, count me in ! :)

amitojsingh366 commented 2 years ago

Hi ! Content is really great, I like the global tone. The design is classic for docs, it works :) It would be good to keep dark/light mode preference to prevent users from having to set it everytime they go on the docs though, it's been asked before but are you open to PR ?

PS. if french translation is needed, count me in ! :)

i've already opened a PR for this, but i'm not sure if they are accepting PRs at the moment (#3976)

dmitriid commented 2 years ago

Feedback. Everything below is my personal subjective opinion.

Left sidebar needs to be re-worked. It has to be immediately obvious where to go next.

Right now the sidebar itself is quite prominent, but only features two links: Overview and Community. It wasn't at all obvious to me that to get to the actual documentation links I needed to click on Learn or API.

The sidebar on the left should have more links, including links to Learn and API
Search should move above the Home/Learn/API tab bar. This way it will at the very list have a connection to the sidebar.

ericdrobinson commented 2 years ago

The example used in Updating a nested object does not actually illustrate the point. The example works when the callbacks are replaced with the following:

function handleNameChange(e) {
  person.name = e.target.value;
  setPerson({ ...person });
}

function handleTitleChange(e) {
  person.artwork.title = e.target.value;
  setPerson({ ...person });
}

function handleCityChange(e) {
  person.artwork.city = e.target.value;
  setPerson({ ...person });
}

function handleImageChange(e) {
  person.artwork.image = e.target.value;
  setPerson({ ...person });
}

This works because nothing actually depends upon a nested object for rendering - React is only checking that the top level person instance has changed in order to determine that a re-render is necessary. "Unfortunately", this pattern also works for child components due to the automatic rendering recursion. So unless you specifically stop a child component from automatically rendering with the parent, the above functionality will work just fine for triggering renders in child components.

It would be very valuable to provide an example that shows problems with shallow copied nested objects. At the very least being clear that this example "may actually work without the shallow copying, but it's good practice to deep copy because..." in the documentation would go a long way to helping people better understand what's happening.

ericdrobinson commented 2 years ago

Also, the first example in the Updating Arrays in State page (Adding to an array) works fine for me, even though the documentation suggests that it shouldn't?

If this is expected, an explanation about why we "don't want to mutate the array with push()" would be very helpful.

(This continues to work because we receive the same instance in the useState call. What triggers the render is the call to setName(''); directly before the push().)

promet99 commented 2 years ago

Hi ! Content is really great, I like the global tone. The design is classic for docs, it works :) It would be good to keep dark/light mode preference to prevent users from having to set it everytime they go on the docs though, it's been asked before but are you open to PR ? PS. if french translation is needed, count me in ! :)

i've already opened a PR for this, but i'm not sure if they are accepting PRs at the moment (#3976)

I agree. also background color of code examples are left as white in dark mode. It sure can be fixed simply

dcastil commented 2 years ago

Hey @ericdrobinson, I think this pattern shouldn't be taught in the docs because mutations like this can lead to bugs due to unwatend side effects.

Imagine the person object would have been built like this:

const artwork = {
    title: 'my title',
    city: 'my city'
}
const person = {
    artwork: artwork,
    anotherArtwork: artwork
}

If you mutate person.artwork.title, you also change the title of the other artwork which might not be what you intend to do.

Another reason is that the artwork variable might be used as a dependency in an effect or a memoized component (maybe not now, but it can always happen in the future). If you change the content of an object without changing the object reference, React won't detect this correctly and effects won't rerun or memoized components won't re-render although they should.

ericdrobinson commented 2 years ago

@dcastil Perhaps you didn't read my entire comment. I am not advocating that this pattern be taught. I am advocating for an improved example that showcases why shallow copying with nested objects is a bad idea. Even the example you gave is weak because it is hand-wavy. The example given in the current documentation (at time of writing) is weak because if you don't do what they advocate, then it still works.

Documentation: Don't do this thing because it's bad.
User: But I tried the thing and it worked just fine.
Documentation: ... ¯\_(ツ)_/¯

The documentation has an obligation to show users where this breaks down. Most of the rest of the documentation does a great job of this.

As you state:

If you change the content of an object without changing the object reference, React won't detect this correctly and effects won't rerun or memoized components won't re-render although they should.

And my argument is that the documentation here should show this - show an example of something breaking - to properly provide improved, teachable context. As I stated in the final paragraph of my comment:

It would be very valuable to provide an example that shows problems with shallow copied nested objects. At the very least being clear that this example "may actually work without the shallow copying, but it's good practice to deep copy because..." in the documentation would go a long way to helping people better understand what's happening.

(To be fair, I did just edit that final paragraph to remove some ambiguity in how it was worded...)

dcastil commented 2 years ago

@ericdrobinson Ah sorry I misunderstood that! 😅

arturcarvalho commented 2 years ago

Tiny visual nit, but any chance of removing the horizontal scrollbar?

I have the problem in Chrome/Firefox on Windows 10 but not in Chrome/Firefox on Mac OS X. I tried several resolutions without plugins and the issue is always there. I don't have another Windows machine close by to check if it's just me.

marcolg97 commented 2 years ago

Inside the 2° challenge on https://beta.reactjs.org/learn/keeping-components-pure#challenges is missing the tab for "./utils.js". In the other examples, this tab is always present.

shihabus commented 2 years ago

hey, if we see a typo how do we fix it? 🤔🤔🤔🤔🤔🤔

shihabus commented 2 years ago

[Feedback] [WIP]

If I have opted for a theme, it should apply when I open a link.
a bit of transition delay can be really soothing to the eyes

amitojsingh366 commented 2 years ago

[Feedback] [WIP]

* If I have opted for a theme, it should apply when I open a link.

* a bit of transition delay can be really soothing to the eyes

I've fixed all of this in #3976

shrirambalaji commented 2 years ago

hey, if we see a typo how do we fix it? 🤔🤔🤔🤔🤔🤔

@shihabus Follow the steps in the Readme.md to fork, clone this repo. Switch to the beta branch (git checkout beta). Make a new feature branch from there. You should search for the typo inside the src/pages directory if the typo is in the content, else search it inside of the src directory if it's in the UI. Commit the change and push. Github should allow you to make a PR.

tyreljackson-L904 commented 2 years ago

https://beta.reactjs.org/learn/preserving-and-resetting-state

This page has some inconsistencies that may be confusing for people newer to React. On the diagrams you refer to the counter state as 'state' in one diagram, and 'count' in the others, then the state in the code is referred to as [score, setScore]. As someone new to react when reading the docs it was confusing that score was the same as count. If I am creating a counter it may be better for the reader to be consistent and have the state called [count, setCount] and in all diagrams refer to it as 'count'. Loving the docs though!

Screen Shot 2021-10-26 at 3 19 40 PM Screen Shot 2021-10-26 at 3 20 11 PM

sexyoung commented 2 years ago

Hi, is there a traditional Chinese version available? Or how do I provide traditional Chinese content? :sheep:

driedjackfr commented 2 years ago

I found a typo at Responding to Events. It should be Toolbar.

State: A Component's Memory. gretting should be greeting

panzerdp commented 2 years ago

Hi @gaearon, @rachelnabors!

Thanks for your hard work in improving the React docs!

While reading the guide Referencing Values with Refs I couldn't help but notice that it contains a lot of ideas and examples (slightly modified) from my post The Complete Guide to useRef() and Refs in React (I am the author).

That's a good thing, and I'm glad that React developers will have access to better quality documentation.

Do you think it would be fair to reference and give credit to the authors of the original content that you might be using to write the new React documentation?

(I've also created #4002 for further discussion)

Thanks!

ubuntugx commented 2 years ago

Hi, I would like to contribute to the translation of React documents. How can I participate in the translation of simplified Chinese documents?

gaearon commented 2 years ago

Hi, I would like to contribute to the translation of React documents. How can I participate in the translation of simplified Chinese documents?

We will announce when we're ready to kick off the translation effort. For now, it's a bit premature because the content is still in flux.

Do you think it would be fair to reference and give credit to the authors of the original content that you might be using to write the new React documentation?

I've responded to this in https://github.com/reactjs/reactjs.org/issues/4002#issuecomment-952982055.

sexyoung commented 2 years ago

@gaearon Thank you for your feedback :sheep:

unpunnyfuns commented 2 years ago

Might be a regression from looking at the other screenshots, but regular text appears to have too much weight, below a sample has been changed to font-weight: 200;

Before:

After:

This also increases the contrast of inline emphasis, especially bolder text.

ivenuss commented 2 years ago

I'd make this editor box area also dark in dark mode

amitojsingh366 commented 2 years ago

I'd make this editor box area also dark in dark mode

this is being worked on in #4019 and #4023

eslachance commented 2 years ago

As someone who has learned React 3 years ago from the official examples, I have to say, it really "Feels" like the new docs don't quite have the cohesion of the original tutorial. Perhaps because the tic-tac-toe tutorial was on one single page and didn't require quite so much navigation, but to me the original tutorial is much easier to follow than what's in the new beta docs. Seems like it's a bit of an oversight to me.

gmoniava commented 2 years ago

@gaearon Here is some feedback so far:

IMHO would be nice if docs address this question: https://stackoverflow.com/questions/68407187/potential-bug-in-official-useinterval-example it is related to Dan's post.
Not sure if it is already addressed but sometimes I see people store components or JSX in state; would be nice if docs say if this is good practice or not.

RolkerMan commented 2 years ago

It would be my pleasure to contribute for the Chinese🇨🇳 translation for the new doc.

reactjs / react.dev

New React Docs #3308

The plan

Anyone can learn React

Translations

What to expect

Help us help you! Take the survey!