Reactjs.org: Update docs to use hooks

[selbekk]

As of now, the main docs haven’t been updated to account for hooks. Especially the state & lifecycle section seems a bit misleading now.

I’d love to help out with a rewrite, but I’d love to hear your feedback on what should be changed and what should stay behind.

[saranshkataria]

Since we are having the discussion at #1782, closing this one out.

[selbekk]

Slightly different issue @saranshkataria - this pertains to the docs, not the tutorial

[saranshkataria]

ah, my bad. But why would we want everything to be hooks in the docs? There's a section about hooks and that is what it should be?

[selbekk]

On mobile now, but in short: if the Preferred Way of React going forward is using hooks for stuff like state and side effects, I think we should rewrite the docs so that they mirror that message. Right now, that’s not the case.

Have a look here: https://reactjs.org/docs/state-and-lifecycle.html

Class components and lifecycles definitely need to be documented, but perhaps not as... «the first choice», if you know what i mean.

[saranshkataria]

I don't think the docs should be preferring one way over the other yet, everyone is still figuring hooks out, but will reopen this issue to let other people share their opinions on it.

[selbekk]

As of now, though, the docs _are_ preferring class components, by not even mentioning hooks (at least in that section)

[kachkaev]

RADME.md in facebook/react repo says:

We have several examples on the website. Here is the first one to get you started:
[a functional component]

Following the link takes a newcomer to a page where all components are classes. This is quite confusing. Given that the stateful logic can be expressed using hooks now, classes can be revealed much later.

[voluntadpear]

I feel the same about the Main Concepts docs. Especially the "State and Lifecycle" doc. I was expecting to see at least a mention about Hooks there. Newcomers to React (especially folks coming from other libraries) could choose to check the Docs instead of the Tutorial (depending on their style of learning) so the Hooks section being after Advanced Guides and even the API Reference makes them somehow easy to miss. Having a brief mention of Hooks as an alternative to classes could be really helpful.

[nickmccurdy]

@saranshkataria

I don't think the docs should be preferring one way over the other yet, everyone is still figuring hooks out, but will reopen this issue to let other people share their opinions on it.

The hook docs recommend using hooks rather than classes for new components (see Should I use Hooks, classes, or a mix of both?). The docs should primarily focus on hooks to be consistent with this suggestion, and save time by not requiring users to learn classes before they can learn hooks.

With docs rewritten in hooks, we'd have to decide how to handle the old class docs. Is the class API going to change in the future, making it useful to maintain the original class docs in full as a separate verison? If not, should we stop updating the class docs or move them to a subsection of the hook docs (kinda like how hook docs are a subsection of the class docs now)?

[nickmccurdy]

I'm making progress on converting the docs to use hooks instead of classes, and I'll submit a pull request when it's mostly complete. Then we can figure out if it's okay to replace the class docs or if the hook docs should be reworked in a different way.

[nickmccurdy]

I've started a draft pull request, I'm not done checking it for accuracy but I'd still appreciate feedback: https://github.com/reactjs/reactjs.org/pull/2400

[jasongi-actu]

Since hooks are such a big change, and many people will be needing to learn react using classes, is it an option to provide examples, one using hooks and one using classes? Perhaps tab separated or something? I think this would also aid with people who want to refactor class code to functional components, as well as ensuring new code projects and people new to react start off learning hooks.

[nickmccurdy]

I don’t think that’s a good idea because the hook API is designed very differently. There’s some overlap with some usages of hooks and classes, but there are enough differences and quirks that I think it would be easiest to explain them separately. There are already some references that compare basic hook usage with basic class usage anyway.

Also the React team is planning on rewriting the docs from scratch fo hooks anyway, so the structure is going to differ (as it should because they don't really translate to each other directly).

[karlhorky]

In case this can be useful to anyone else:

@nickmccurdy's incomplete but very useful version of the docs with React hooks is online at https://reacthooks.nickmccurdy.com

[kachkaev]

@karlhorky this might be a bit off-topic, but do you or others know why it‘s

function HelloMessage(props) {
  return <div>Hello {props.name}</div>;
}

and not

const HelloMessage = (props) => {
  return <div>Hello {props.name}</div>;
}

?

If I were new to JavaScript in 2020, I’d have to learn arrow functions anyway – they are unavoidable. function keyword though is what can easily be replaced in the entire codebase with no harm, assuming we don’t carry loads of legacy code and thus don’t use this anywhere.

At our company, we stick with arrow functions by default and it works great. The only exception so far is function overload in typescript, which is both advanced and rare. ESLint’s func-style helps us stick to the rule pretty well.

Yet, I often see others using function MyComponent in React examples and docs. I feel like I’m missing something, because I don’t fully understand this decision. What can I read to fill the gap? Or is this simply an old-school established flavour that people keep using by inertia?

Should not future react docs bet on arrow functions everywhere to reduce the readers’ cognitive load?

---

UPD: One ‘feature’ of the function keyword I‘ve remembered is the ability to do export default function MyComponent. That’s better than export default () => {} (unnamed component) and export default MyComponent () => {} is an invalid syntax.

Our company’s JS guidelines recommend this:

const HelloMessage = ({ name }) => {
  return <div>Hello {name}</div>;
}

export default HelloMessage

Two statements instead of one may look like an overhead, but they are actually a ‘feature‘. They allow you too keep your component declaration style consistent in all cases, such as these:

export default React.memo(HelloMessage)

export default React.forwardRef(HelloMessage)

export default withFooBar(HelloMessage)

This flexibility is another source for cognitive load reduction. Repeated boring code patterns are easier to, write, review and modify. It's also easy to find if a file has a default export because it’s always on the very last line.

[gaearon]

Just wanted to note this is still very much on our minds. We might start looking into this soon-ish. One challenge is how to coordinate translations. Since this is a big rewrite. cc @tesseralis curious if you have tips on how we could approach this.

[kachkaev]

@gaearon when replacing class components with the function ones in the docs, is the plan to use function MyComponent() {} or const MyComponent = () => {}? I guess that there should be some agreed on guidelines before the process starts. The chosen flavour will have a pretty significant impact on the community for years to come, so it should be picked very carefully.

It'd be great if this thread included a link to the guidelines (or their ongoing discussion). That feels quite relevant.

[gaearon]

I don't think there would be any significant impact given we've used function since 2013 and people sometimes prefer arrows anyway.

[tesseralis]

@gaearon I don't think there should be a significant problem, although it might cause a headache with some languages that aren't as active. I'll check in over the weekend and see if there are any issues and see what's the best way to communicate this change to people.

[koba04]

I think "Tutorial" is the highest priority than others because beginners would check the Tutorial page first. I don't want to recommend beginners the current Tutorial page because the Tutorial is written based on class components.
I believe that React is going forward to the Hooks world, so I'd like to teach beginners how to create components with Hooks at first rather than class components API even though they might learn class components API for existing components later.

It needs many works for translation, but it shouldn't block the migration.