9 ms·

React Docs Beta – rewritten with hooks and interactive examples

329 points by jitl 5y ago

colesantiago 5y ago
Does anyone know what UI components or style this documentation uses?, I have to say the UI style is really nice and modern.
- fortydegrees 5y ago
  The CSS is tailwind
  - nsonha 5y ago
    who cares, they're asking about the design
    - seattle_spring 5y ago
      Why respond with this tone if you have no idea what tailwind css is? The "design" is the theme provided by, you guessed it, tailwind css.
      - nsonha 5y ago
        > if you have no idea what tailwind css is I didn't know that taiwind also includes a default theme I'm not fond of the way it's getting shoved down everyone's throat. Why is it that people won't shut up about their crappy choice of software development tools. Who cares.
        seattle_spring 5y ago
        There isn't a single example of it being "shoved down throats" in this thread, not even close. One person liked the visuals of the documentation and asked what themed it, another person answered. Then you came along and complained about a bunch of stuff that wasn't even happening. Here you are defending outdated and clunky HoCs, which itself is more off-topic than what's styling the OP's documentation.
        nsonha 5y ago
        > Here you are defending outdated and clunky HoCs I replied to someone who brough it up > off-topic You do realize this is a React discussion? > There isn't a single example of it being "shoved down throats" Hey sorry I replied with the wrong tone, but imagine you don't know that tailwind also comes with a style, someone asks about the style or specific component lib or whatever, you see a reply that "it's tailwind", which to you must be as helpful as answering with "it's css"
      - deleted 5y ago
        [deleted]
acemarke 5y ago
I am _so_ very excited about this! This is going to be a huge help for the community. These new docs are an incredible improvement over the old docs. In-depth tutorial and concept explanations, live editable sandboxes, coverage of key concepts and common gotchas, and much more! See the docs repo PR [0] for background on what content is currently included, plans for further content and site improvements, and feedback on the new docs. For why this is a big deal: the old docs were good in some ways, but very weak in others. By far the biggest issue is that hooks were announced in Oct 2018 and released live in early 2019, but the tutorials and explanations were all still written with class components and showed older patterns, well after the community had fully adopted hooks as the standard approach. The hooks info was a totally separate section of the docs. That section was _good_, but it made it really hard to continue recommending the React docs as a good starting point for someone new to React. The docs have also skimmed past a lot of important information, usage concepts, and info on how React itself actually works. For example: - React's batching behavior is something that frequently trips people up, but the current docs just have a note that says "updates may be async" - Using the hook dependency arrays correctly is vital, but the current hook docs describe it as sort of an after-thought - There's no information on what a "reducer function" is or how to use one correctly. That's part of why I ended up writing a 9K-word "Guide to React Rendering Behavior" post [1], and Dan wrote a similar "Guide to `useEffect`" [2] article. Fortunately, the new docs address a lot of those concepts directly, which should really help people who are getting started. [0] https://github.com/reactjs/reactjs.org/pull/3965 https://github.com/reactjs/reactjs.org/pull/3965 [1] https://blog.isquaredsoftware.com/2020/05/blogged-answers-a-mostly-complete-guide-to-react-rendering-behavior/ https://blog.isquaredsoftware.com/2020/05/blogged-answers-a-... [2] https://overreacted.io/a-complete-guide-to-useeffect/ https://overreacted.io/a-complete-guide-to-useeffect/
- seedboot 5y ago
  Congratulations I've been looking forward to starting reading this for some time!
  - acemarke 5y ago
    heh, to be clear, _I_ didn't work on this at all :) It was primarily Rachel Nabors and Dan Abramov from the React team doing the writing: https://beta.reactjs.org/community/acknowledgements#react-docs https://beta.reactjs.org/community/acknowledgements#react-do... (I did get to see an early alpha preview version and gave some feedback - other than that I've just been very eagerly awaiting this coming out)
deleted 5y ago
[deleted]
deleted 5y ago
[deleted]
yepthatsreality 5y ago
Glad to see these improvements. My previous favorite part of the older React docs was the several times looking up a lifecycle method I was partially familiar with only to see it had been deprecated for a new similar method.
kaycebasques 5y ago
Anyone know of any issues / blog posts / etc. on "lessons learned" from the overall docs refactoring project?
- acemarke 5y ago
  I had asked Rachel Nabors about that a few weeks ago, and she said she had a post drafted and would put it up post-beta launch.
- warpech 5y ago
  'New React Docs' GitHub Issue is interesting and shines some light on the changes. Significantly, note that it took a litle bit more than a year from the formulation of this issue to the Beta version. Knowing that there were some holy wars to be fought on the way, I don't think it's too long. Congrats to the team who worked on it! [1] https://github.com/reactjs/reactjs.org/issues/3308 https://github.com/reactjs/reactjs.org/issues/3308
h1fra 5y ago
Very excited about this release, the website is so much better and easier to read. Congrats! (Disclaimer I work at Algolia in the Crawler team) Not to hijack this thread, but the search is now powered by Algolia custom crawler (still Docsearch but used to be a custom scrappy implem), it should match previous high level of expectation, but we'll appreciate any feedback on the relevancy.
chadlavi 5y ago
These kids these days get better docs than we ever dreamed of. And that's a good thing.
- thefunnyman 5y ago
  I’ve found react to be an outlier in this regard. The React docs are phenomenal and in combination with create-react-app it’s super easy to start up a new project. I can’t say the same about the majority of other frameworks I’ve encountered.
anarchy8 5y ago
It really should have Typescript as well (optionally, that is)
- kall 5y ago
  I think the way the docs introduce functional components (destructure the props argument right away) sets you up for success with TypeScript. The main ways to get started that they recommend (CodeSandbox, CRA, next.js) let you add typescript down the line with no hassle, so you don't loose out by starting without it. Seems better to teach people one thing at a time. React with TypeScript really doesn't look all that different and if you just drop what they teach you into an existing TS project, it will work ok. An official "Using React with Typescript" doc that shows good patterns for typing props and state would be nice though.
  - acemarke 5y ago
    The de-facto standard resource on React + TS is the community-maintained React TypeScript Cheatsheet site: https://react-typescript-cheatsheet.netlify.app/ https://react-typescript-cheatsheet.netlify.app/ But yes, I'd love to have some of this info added to the official docs as well.
    - danabramov 5y ago
      Yeah we’d like to add something (potentially even toggles) but out of scope for the first iteration.
      - acemarke 5y ago
        Sweet! As an FYI for later reference, Lenz Weber has a Remark plugin that compiles TS to JS in code samples - we use that in the Redux Toolkit docs. I think Orta Therox may have something similar going on with his "Shiki Twoslash" tooling, but not entirely sure.
- TameAntelope 5y ago
  Well, this is Typescript, isn't it?
jerrygoyal 5y ago
hooks are yet to be added to new docs (only useState for now).
- brundolf 5y ago
  useState is a hook (arguably the main hook). Maybe you meant useEffect?
ramesh31 5y ago
Very nice. I have to admit I was highly skeptical of hooks at first, but at this point I'll never go back to writing classes. Functional components are the truth.
moneywoes 5y ago
Looking to reacquaint myself with React. Should I skip over class components?
- evantahler 5y ago
  Yeah. Most use cases just need hooks and functions now!
- adzm 5y ago
  Don't skip over class components. There is a ton of existing code and libraries that use it.
  - meowtimemania 5y ago
    I’d say just don’t learn about class components until you run into them
- andrewingram 5y ago
  I’d say so, unless you have a particular reason to learn them. I haven’t written a class component in well over 2 years.
wheybags 5y ago
As someone who's new to react, and basically started with hooks: am I missing something? The old class based code looks so much better than the hooks magic. Is this just js people hating OO or is there something deeper?
- jolux 5y ago
  For one thing they currently plan to maintain classes indefinitely, so if you really wanted to get started with classes you can just do that, and learn hooks later. That said, the React docs are pretty clear about the motivation for hooks and I think that is a good place to start: https://reactjs.org/docs/hooks-intro.html#motivation https://reactjs.org/docs/hooks-intro.html#motivation. After that, this post explains roughly how hooks actually work (in a simplified way), and why they're a more natural fit for what's happening under the hood: https://www.netlify.com/blog/2019/03/11/deep-dive-how-do-react-hooks-really-work/ https://www.netlify.com/blog/2019/03/11/deep-dive-how-do-rea...
  - recursive 5y ago
    > That said, the React docs are pretty clear about the motivation for hooks and I think that is a good place to start: https://reactjs.org/docs/hooks-intro.html#motivation https://reactjs.org/docs/hooks-intro.html#motivation. I've read this a number of times, and none of the point make sense to me. > It’s hard to reuse stateful logic between components Is there some reason you can't use a `get(key)` and `set(key,value)` between class components. I don't really grok react, despite trying, so maybe there's a reason that doesn't work. > Complex components become hard to understand I don't understand what the hard part is supposed to be here. If you have a method that's dealing with too many concerns, you can just add methods, and then call those. > Classes confuse both people and machines `this` is pretty confusing in javascript, but yet that's the language react is targeting. And it's no less confusing in prototype-based objects. And after having tried to learn both hooks and `this`, it certainly doesn't seem like hooks are conceptually easier than `this`. Probably my fundamental problem with hooks is trying to understand which state goes with which component-function invocation. It just seems like dark magic that usually works. I've tried to read the implementation to figure it out. It seems to depend on the famous DOM diff feature. It was about at that point that I lost the plot. So, I know I'm an outlier, but class-based components just make sense to me. They can be complex, but fundamentally comprehensible. Function components seem like a fake simplicity that's masking a complexity that I've yet to figure out.
999900000999 5y ago
With all the Facebook bad posts, React JS is much better with FB funding then without. You can legitimately learn programing just from reading though the React JS tutorials. Many other frameworks lack such good documentation.
rapfaria 5y ago
Well, indeed beta: https://imgur.com/a/iIeoL5A https://imgur.com/a/iIeoL5A
- cuddlecake 5y ago
  Doesn't seem like a bug indicative of being beta. The bug could obviously be fixed by looping back to 0, but the correctness is not the important part. Though, reporting such an issue does not seem to be possible, hmm :(
- danabramov 5y ago
  Nice find! One of the pages has an exercise where you need to fix this bug.
zarzavat 5y ago
I'm clearly missing something with hooks. The main selling point seems to be that your code is more "functional" because you are typing the 'function' keyword more often, but the new functions you can write are not pure functions. They are "react functions" and have all kinds of global baggage, just like component classes. Having more impure functions doesn't do anything for me aesthetically, it might as well be a class. At least classes force you to declare (in typescript) the type of your state, with hooks it's all hidden inside. That seems less functional rather than more.
- rat9988 5y ago
  It's less verbose. It makes it more readable, in my opinion. They could have implemented the very same thing with a class, but they didn't. It's not about functional vs OOP. It's just about readability.
- travisd 5y ago
  The core of it is getting closer to true "reactive" programming. If you use hooks right™, you generally don't have to worry about how to handle values over time. React does all that plumbing for you (which is why we need all the dependency arrays). This for me is the main advantage over class components. You don't need to worry about the various lifecycle methods (including having separate methods for componentDidMount and componentDidUpdate and making sure you do all the plumbing right when your parent changes props that you weren't expecting). IMO, React really could have benefited from devoted language syntax for this (like Svelte does) to automagically and statically track all the dependencies. But React has an ethos of being "just JavaScript" (even JSX desugars to relatively straightforward React.createElement calls, and you can treat those nodes like regular JS objects, pass them around willy nilly, etc.), so it didn't happen (and instead we have lint rules like ESLint rules-of-hooks that are designed to enforce the invariants that really the programming language should enforce). Edit: The other nice things about hooks is their composability (and this is in fact related to what I said above). With class components, a component can have one state object, so it's hard to compose with other "mixin" type behaviors that need their own dedicated state. You ended up with weird patterns like higher order components (à la Redux withStore) that have basically ceased to exist with hooks (replaced by a useStore hook which can opaquely manage its own state under the hood).
nathias 5y ago
why is it not called useReactDocs?

329 points by jitl 5y ago

Does anyone know what UI components or style this documentation uses?, I have to say the UI style is really nice and modern.

fortydegrees 5y ago
The CSS is tailwind
- nsonha 5y ago
  who cares, they're asking about the design
  - seattle_spring 5y ago
    Why respond with this tone if you have no idea what tailwind css is? The "design" is the theme provided by, you guessed it, tailwind css.
    - nsonha 5y ago
      > if you have no idea what tailwind css is I didn't know that taiwind also includes a default theme I'm not fond of the way it's getting shoved down everyone's throat. Why is it that people won't shut up about their crappy choice of software development tools. Who cares.
      - seattle_spring 5y ago
        There isn't a single example of it being "shoved down throats" in this thread, not even close. One person liked the visuals of the documentation and asked what themed it, another person answered. Then you came along and complained about a bunch of stuff that wasn't even happening. Here you are defending outdated and clunky HoCs, which itself is more off-topic than what's styling the OP's documentation.
        nsonha 5y ago
        > Here you are defending outdated and clunky HoCs I replied to someone who brough it up > off-topic You do realize this is a React discussion? > There isn't a single example of it being "shoved down throats" Hey sorry I replied with the wrong tone, but imagine you don't know that tailwind also comes with a style, someone asks about the style or specific component lib or whatever, you see a reply that "it's tailwind", which to you must be as helpful as answering with "it's css"
    - deleted 5y ago
      [deleted]

acemarke 5y ago

I am _so_ very excited about this! This is going to be a huge help for the community. These new docs are an incredible improvement over the old docs. In-depth tutorial and concept explanations, live editable sandboxes, coverage of key concepts and common gotchas, and much more! See the docs repo PR [0] for background on what content is currently included, plans for further content and site improvements, and feedback on the new docs. For why this is a big deal: the old docs were good in some ways, but very weak in others. By far the biggest issue is that hooks were announced in Oct 2018 and released live in early 2019, but the tutorials and explanations were all still written with class components and showed older patterns, well after the community had fully adopted hooks as the standard approach. The hooks info was a totally separate section of the docs. That section was _good_, but it made it really hard to continue recommending the React docs as a good starting point for someone new to React. The docs have also skimmed past a lot of important information, usage concepts, and info on how React itself actually works. For example: - React's batching behavior is something that frequently trips people up, but the current docs just have a note that says "updates may be async" - Using the hook dependency arrays correctly is vital, but the current hook docs describe it as sort of an after-thought - There's no information on what a "reducer function" is or how to use one correctly. That's part of why I ended up writing a 9K-word "Guide to React Rendering Behavior" post [1], and Dan wrote a similar "Guide to `useEffect`" [2] article. Fortunately, the new docs address a lot of those concepts directly, which should really help people who are getting started. [0] https://github.com/reactjs/reactjs.org/pull/3965 https://github.com/reactjs/reactjs.org/pull/3965 [1] https://blog.isquaredsoftware.com/2020/05/blogged-answers-a-mostly-complete-guide-to-react-rendering-behavior/ https://blog.isquaredsoftware.com/2020/05/blogged-answers-a-... [2] https://overreacted.io/a-complete-guide-to-useeffect/ https://overreacted.io/a-complete-guide-to-useeffect/

seedboot 5y ago
Congratulations I've been looking forward to starting reading this for some time!
- acemarke 5y ago
  heh, to be clear, _I_ didn't work on this at all :) It was primarily Rachel Nabors and Dan Abramov from the React team doing the writing: https://beta.reactjs.org/community/acknowledgements#react-docs https://beta.reactjs.org/community/acknowledgements#react-do... (I did get to see an early alpha preview version and gave some feedback - other than that I've just been very eagerly awaiting this coming out)

deleted 5y ago

[deleted]

deleted 5y ago

[deleted]

yepthatsreality 5y ago

Glad to see these improvements. My previous favorite part of the older React docs was the several times looking up a lifecycle method I was partially familiar with only to see it had been deprecated for a new similar method.

kaycebasques 5y ago

Anyone know of any issues / blog posts / etc. on "lessons learned" from the overall docs refactoring project?

acemarke 5y ago
I had asked Rachel Nabors about that a few weeks ago, and she said she had a post drafted and would put it up post-beta launch.
warpech 5y ago
'New React Docs' GitHub Issue is interesting and shines some light on the changes. Significantly, note that it took a litle bit more than a year from the formulation of this issue to the Beta version. Knowing that there were some holy wars to be fought on the way, I don't think it's too long. Congrats to the team who worked on it! [1] https://github.com/reactjs/reactjs.org/issues/3308 https://github.com/reactjs/reactjs.org/issues/3308

h1fra 5y ago

Very excited about this release, the website is so much better and easier to read. Congrats! (Disclaimer I work at Algolia in the Crawler team) Not to hijack this thread, but the search is now powered by Algolia custom crawler (still Docsearch but used to be a custom scrappy implem), it should match previous high level of expectation, but we'll appreciate any feedback on the relevancy.

chadlavi 5y ago

These kids these days get better docs than we ever dreamed of. And that's a good thing.

thefunnyman 5y ago
I’ve found react to be an outlier in this regard. The React docs are phenomenal and in combination with create-react-app it’s super easy to start up a new project. I can’t say the same about the majority of other frameworks I’ve encountered.

anarchy8 5y ago

It really should have Typescript as well (optionally, that is)

kall 5y ago
I think the way the docs introduce functional components (destructure the props argument right away) sets you up for success with TypeScript. The main ways to get started that they recommend (CodeSandbox, CRA, next.js) let you add typescript down the line with no hassle, so you don't loose out by starting without it. Seems better to teach people one thing at a time. React with TypeScript really doesn't look all that different and if you just drop what they teach you into an existing TS project, it will work ok. An official "Using React with Typescript" doc that shows good patterns for typing props and state would be nice though.
- acemarke 5y ago
  The de-facto standard resource on React + TS is the community-maintained React TypeScript Cheatsheet site: https://react-typescript-cheatsheet.netlify.app/ https://react-typescript-cheatsheet.netlify.app/ But yes, I'd love to have some of this info added to the official docs as well.
  - danabramov 5y ago
    Yeah we’d like to add something (potentially even toggles) but out of scope for the first iteration.
    - acemarke 5y ago
      Sweet! As an FYI for later reference, Lenz Weber has a Remark plugin that compiles TS to JS in code samples - we use that in the Redux Toolkit docs. I think Orta Therox may have something similar going on with his "Shiki Twoslash" tooling, but not entirely sure.
TameAntelope 5y ago
Well, this is Typescript, isn't it?

jerrygoyal 5y ago

hooks are yet to be added to new docs (only useState for now).

brundolf 5y ago
useState is a hook (arguably the main hook). Maybe you meant useEffect?

ramesh31 5y ago

Very nice. I have to admit I was highly skeptical of hooks at first, but at this point I'll never go back to writing classes. Functional components are the truth.

moneywoes 5y ago

Looking to reacquaint myself with React. Should I skip over class components?

evantahler 5y ago
Yeah. Most use cases just need hooks and functions now!
adzm 5y ago
Don't skip over class components. There is a ton of existing code and libraries that use it.
- meowtimemania 5y ago
  I’d say just don’t learn about class components until you run into them
andrewingram 5y ago
I’d say so, unless you have a particular reason to learn them. I haven’t written a class component in well over 2 years.

wheybags 5y ago

As someone who's new to react, and basically started with hooks: am I missing something? The old class based code looks so much better than the hooks magic. Is this just js people hating OO or is there something deeper?

jolux 5y ago
For one thing they currently plan to maintain classes indefinitely, so if you really wanted to get started with classes you can just do that, and learn hooks later. That said, the React docs are pretty clear about the motivation for hooks and I think that is a good place to start: https://reactjs.org/docs/hooks-intro.html#motivation https://reactjs.org/docs/hooks-intro.html#motivation. After that, this post explains roughly how hooks actually work (in a simplified way), and why they're a more natural fit for what's happening under the hood: https://www.netlify.com/blog/2019/03/11/deep-dive-how-do-react-hooks-really-work/ https://www.netlify.com/blog/2019/03/11/deep-dive-how-do-rea...
- recursive 5y ago
  > That said, the React docs are pretty clear about the motivation for hooks and I think that is a good place to start: https://reactjs.org/docs/hooks-intro.html#motivation https://reactjs.org/docs/hooks-intro.html#motivation. I've read this a number of times, and none of the point make sense to me. > It’s hard to reuse stateful logic between components Is there some reason you can't use a `get(key)` and `set(key,value)` between class components. I don't really grok react, despite trying, so maybe there's a reason that doesn't work. > Complex components become hard to understand I don't understand what the hard part is supposed to be here. If you have a method that's dealing with too many concerns, you can just add methods, and then call those. > Classes confuse both people and machines `this` is pretty confusing in javascript, but yet that's the language react is targeting. And it's no less confusing in prototype-based objects. And after having tried to learn both hooks and `this`, it certainly doesn't seem like hooks are conceptually easier than `this`. Probably my fundamental problem with hooks is trying to understand which state goes with which component-function invocation. It just seems like dark magic that usually works. I've tried to read the implementation to figure it out. It seems to depend on the famous DOM diff feature. It was about at that point that I lost the plot. So, I know I'm an outlier, but class-based components just make sense to me. They can be complex, but fundamentally comprehensible. Function components seem like a fake simplicity that's masking a complexity that I've yet to figure out.

999900000999 5y ago

With all the Facebook bad posts, React JS is much better with FB funding then without. You can legitimately learn programing just from reading though the React JS tutorials. Many other frameworks lack such good documentation.

rapfaria 5y ago

Well, indeed beta: https://imgur.com/a/iIeoL5A https://imgur.com/a/iIeoL5A

cuddlecake 5y ago
Doesn't seem like a bug indicative of being beta. The bug could obviously be fixed by looping back to 0, but the correctness is not the important part. Though, reporting such an issue does not seem to be possible, hmm :(
danabramov 5y ago
Nice find! One of the pages has an exercise where you need to fix this bug.

zarzavat 5y ago

I'm clearly missing something with hooks. The main selling point seems to be that your code is more "functional" because you are typing the 'function' keyword more often, but the new functions you can write are not pure functions. They are "react functions" and have all kinds of global baggage, just like component classes. Having more impure functions doesn't do anything for me aesthetically, it might as well be a class. At least classes force you to declare (in typescript) the type of your state, with hooks it's all hidden inside. That seems less functional rather than more.

rat9988 5y ago
It's less verbose. It makes it more readable, in my opinion. They could have implemented the very same thing with a class, but they didn't. It's not about functional vs OOP. It's just about readability.
travisd 5y ago
The core of it is getting closer to true "reactive" programming. If you use hooks right™, you generally don't have to worry about how to handle values over time. React does all that plumbing for you (which is why we need all the dependency arrays). This for me is the main advantage over class components. You don't need to worry about the various lifecycle methods (including having separate methods for componentDidMount and componentDidUpdate and making sure you do all the plumbing right when your parent changes props that you weren't expecting). IMO, React really could have benefited from devoted language syntax for this (like Svelte does) to automagically and statically track all the dependencies. But React has an ethos of being "just JavaScript" (even JSX desugars to relatively straightforward React.createElement calls, and you can treat those nodes like regular JS objects, pass them around willy nilly, etc.), so it didn't happen (and instead we have lint rules like ESLint rules-of-hooks that are designed to enforce the invariants that really the programming language should enforce). Edit: The other nice things about hooks is their composability (and this is in fact related to what I said above). With class components, a component can have one state object, so it's hard to compose with other "mixin" type behaviors that need their own dedicated state. You ended up with weird patterns like higher order components (à la Redux withStore) that have basically ceased to exist with hooks (replaced by a useStore hook which can opaquely manage its own state under the hood).

nathias 5y ago

why is it not called useReactDocs?