My 5 favourite updates from the new React documentation

So you read the article title and are probably asking yourself “How can she possibly have a favourite thing about tech docs?” Or, you read the new React docs and are with me in saying that they are an awesome response to a much needed revamp!

React has come a long way over the last 10 years and the framework has undergone some major changes in the way it works. The legacy docs didn’t favour new developers who had to learn React twice - once with class components and then once again with Hooks. The new docs teach modern React and have a much better structure with more interactive examples, opinions and a better colour scheme (imo 😂). There are a lot of changes so, I wanted to outline my favourite things and why:

1. RIP Class Components

To start, I was very happy to see the recommendation to deprecate the use of class components and shift the focus to Functional components.

The reason being, Class components introduced complexity due to their verbose syntax and the need to understand concepts like this and lifecycle methods (e.g componentDidMount). Functional components, however, can be more performant because they don't carry the overhead of class instances. Furthermore, functional components are much easier to test as they are more predictable and have fewer side effects compared to class components (and we all love anything thats easier to test 😉)

Even though I’m sure most of you were probably already using functional components, the new docs offer a great guide on how to migrate.

Here you can see a basic example in practice:

Class component

Functional component

2. Destructuring Props

Another recommendation that comes hand-in-hand with the deprecation of class components is advice on how to pass props. Previously, this.props was how you accessed all of the properties passed to a component. Even though this can still be used, as it is Javascript, the use of this can be ambiguous. Especially, when dealing with functional components, where this doesn't refer to the component instance.

I'm very glad to see the docs recommending destructuring of props! Even though destructuring was released in ES6 there was no mention of it in the legacy docs, despite many developers preference when reading props.

As you can see, in the example below, it's more readable and allows you to only pass the required props instead of passing the entire parent props object.

Old documentation

New documentation

3. Getting hooked in

The old documentation introduced hooks but it didn't emphasise their importance or encourage developers to adopt them as the primary way to manage state and side effects in React applications. Additionally, it assumed you were coming from a “background of class components” and focused on teaching hooks assuming you were migrating. Now, with its own dedicated section the new docs really highlight the benefits of hooks to promote code reuse, modularisation, and better separation of logic.

Im also grateful for the whole dedicated section to the proper use of the useEffect hook. The hook has tripped me up many times because when not handled correctly it can lead to memory leaks and other unexpected behaviour.

For example, a memory leak I’ve seen when using useEffect is when a component subscribes to an event, but fails to unsubscribe when the component is “unmounted”.

The code snippet below shows an example with a websocket. If you don't unsubscribe from the WebSocket's onmessage, even when the component is unmounted, the WebSocket connection will continue to receive and handle messages, even though the component is no longer in use. Over time, this can lead to a buildup of unnecessary connections and event handlers, consuming memory and potentially causing performance issues.

useEffect(() => {
  const ws = new WebSocket('wss://example.com');
  ws.onmessage = (event) => {
    // handle message
  };

  // useEffect hook cleanup function that unsubscribes from the WebSocket's onmessage event

  return () => {
    ws.close();
  };
}, []);

The new docs explain how to avoid performance issues like unnecessary re-renders and infinite loops. They also address one of the common mistakes developers make, which is forgetting to clean up any side effects.

4. Some Context on Context API

Previously, in the legacy docs, the Context API was just one of the topics within the Advanced guides. Unless you went digging, you wouldn't have been introduced to it as one of the core ways to handle deep passing of data. I really like that, in the new docs, Context is recommended as a way to manage state as its one of the best ways to avoid prop drilling.

The power of the Context API is that it is one of the only ways to manage state within React without an external library such as Redux or MobX. So if context isn’t new, you might ask, what about the new docs makes me happy? Well, developers like me who may have been using it as my state management tool for smaller projects, won’t be met with as much resistance, as now it is recommended as one of the use cases.

I also really appreciate the example of how to use the useReducer hook with the Context API as the previous docs didn’t have an example on how to handle complex state logic.

Tip: When implementing the context API, it's good practice to create your own hook to use the context. This is demonstrated below:

Context.js

export const useMyContext = () => useContext(MyContext);

Component.js

const { myData } = useMyContext();

5. A new way to create and build

Finally, I’m so thankful to see the updated docs recommend common production-grade frameworks including Next.js, Remix, Gatsby, and Expo as the best way to build for React.

The old docs had no opinion on using a framework and recommended create-react-app as the best place to start, even though this isn’t being actively maintained. The new docs appreciate that React is community driven and its great to see them supporting these popular community frameworks.

This recommendation of frameworks, particularly Next.js (which allows you to build server-side-rendered React applications with ease) comes coupled with a dedicated docs section for Server APIs. This is awesome to see as SSR offers several benefits over client-side rendering, such as increased performance, better search engine optimization (SEO), and improved user experience and there is definitely a trend in SSR React apps. Even though the framework most likely calls these APIs for us, it’s great to see the detailed explanation.

I may be a little biased in putting this particular point as 4 years ago I had helped build a website with JS disabled in the browser and I really struggled to find documentation on the intricacies of how React and Next.js worked under the hood. If only I had the new docs then 😂!

Summary

Thank-you for reading, I hope you found this useful! Congratulations to the React team, they have done a great job with the docs. I know they are looking for feedback through their survey and issue tracker, but I’d also love to hear your thoughts on the new docs and let me know what your favourite features are in the comments below 👇

Comments

[Gerson Dias]

I'd like to know the benefits of that destruction thing... It's anoying to not know if a variable came from component props or from a state or something... I'm team props.name

[Andrew Pagan]

When destructuring, you're also able to re-name the variables. So, for example,

const Component = ({name}) => ...

Can we re-written as

const Component = ({name: propName}) => ...

And you can reference it now as propName instead of name, but to be honest, at this point you should just rename the prop to something else.

[Anisha Malde]

Hey Gerson, I personally find the benefits of destructuring props are:

• It's less lines of code, for example:

const { starter, main, dessert } = menu;

is equivalent to:

const starter = menu.starter
const main = menu.main
const dessert = menu.dessert 

• I think its much easier to read
• You only pass what you need
• It allows for easier debugging

I also think with the use of hooks within your component it's easier to see if the variable is coming from state. However, I would love to hear more on your perspective?

[Gerson Dias]

Well, using just prop.something is even less lines and u know at bottom of your method what is a prop, what is something else. But I see the point when not using typescript...

[Adam Nathaniel Davis]

YES. There's quantifiable value in having the props. namespace.

[M]

I agree

[Kevin Duconge]

Amazing article! So great to get a highlight of what has changed when it's such a big doc update, thank you Anisha!
If I had to pick a top 1, for me it would be this guide, You Might Not Need an Effect, I can't emphasize enough how many times I've fallen (and seen other people fall) for these anti-patterns!
(also I can't wait for useEffectEvent!)

[Anisha Malde]

Totally agree, it's a great article! Thank you for sharing!

[Nans Dumortier]

Yeah this one is a must read !

[Raí B. Toffoletto]

I haven't read them but I'm sooo glad to see this changes!!

In the end of 2020 I had a colleague asking me : how should I start learning React?. And I had to tell him to go to the official docs to get a grasp of it but be aware that he would need to forget everything because we use functional components and hooks now.

I even started (and never finished) to rewrite the tic tac toe guide using FC.

I'm so glad people won't need to go through this anymore 😁😁

Thanks for the article. 🎉🎉

[Yuli Petrilli]

Wow i didn't know they are finally getting rid of class components, that's great news because they used to be a headache to work with. I also didn't know about the useContext so thank u a lot for sharing this!!

[Anisha Malde]

Hey Yuli! Thank you for your comment, so they are have not actually announced the deprecation of Class components, however they are definitely recommending to shift away from them.
No problem at all and thank you for reading!

[Adam Nathaniel Davis]

They're not getting rid of class components. This article references the fact that they've stopped using class components in their code samples.

[duendeintemporal]

Pienso que ciertamente llena un vacio presente en la documentación anterior. Por otra parte resulta muy util como mencionas los ejemplos citados en diversos casos, pues son una guía y referencia directa que facilita no solo la comprensión de los mismos, sino también permite una consulta rapida para alguna duda sin tener que recurrir a documentación externa...

Me pareció muy util tuarticulo, además sabía de que exitía una nueva documentación lo que no estaba muy claro era como llegar a ella, pues requería muchos hipervinculos de por medio desde la documentación vieja.

Gracias por el aporte.

[Alexander B.K.]

I have only read several topics in the new doc. I like the organization of topics covered and the explanation. The explanation on Effects, including why and how to add dependencies in useEffect is clear; this is not clearly explained in the legacy doc. However, I still need to visit the legacy doc to find the equivalent topics of particular things in the new doc, such as Render Props, Code-Splitting,

[Anisha Malde]

Hey Alexander! Thank you for sharing your thoughts. Thats very interesting that you feel like you have to visit the legacy docs! I don't know if you have seen the section on Lazy loading in the new docs, but it does cover some of the aspects of code splitting. As for Render Props a lot of developers have been replacing them with custom hooks for many of the use cases, but i'm very interested to hear your thoughts on this 😊

[Jack Rhodes]

Agreed - I was pretty shocked when I came back to the React docs earlier this year after working in Elixir for 18 months and found that all the examples were still Class component based! 🤯

[Anisha Malde]

I know right! It must have been so confusing for new developers 🤨

[byby]

As a React developer myself, it's always great to see the framework's documentation getting even better and more accessible.

[Matt Barnicle]

Good article. Agreed that the docs were in need of updating and I'm glad to see they did that. And I didn't know about useReducer before reading this, so thanks for enlightening me!

[PaZapp]

Happy to learn the basics of React. hoping will be good soon by learning it from her.

[Jonny Lee]

Glad that the new docs are out of beta! It is nice to see emphasis on functional components and a number of useful examples

[Priya Patel]

This is so interesting! I really struggled picking up hooks when I started and now it makes a lot more sense as to why. Thank you for sharing your insight.

[🅖🅡🅔🅖🅞🅡🅨 🅞🅡🅣🅞🅝]

Are you just parroting complaints about class components from elsewhere? There’s no ‘overhead’ to a JS class - it’s just syntactic sugar on a function.

Moreover, lifecycle methods were arguably easier to understand than hooks…

Not that I advocate class components - it’s more boilerplate and maintaining state is annoying, but let’s make sure we’re even handed in a critique.

The new docs are great, but in my experience, the biggest pitfalls of react and hooks are changing dependencies - functions or value props which must be made stable with useMemo or useCallback in parent rendering the component - this is the biggest cause of bugs and side effects IMHO. Do new docs address this?

Finally - destructuring is super useful - especially in typescript - where each prop can be properly typed and default values assigned to optional parameters and all essentially ‘documented’ in the function definition itself. Very nice.

[Corrina Reilly]

Great post! I totally agree that the new React docs are a huge improvement over the old ones, especially when it comes to teaching modern React and promoting best practices like functional components and hooks.

I particularly appreciate the emphasis on migrating away from class components and towards functional components, as well as the recommendation to use destructuring to pass props. These changes not only make code more readable and easier to test, but also help to reduce the cognitive load for new developers who are learning React for the first time.

The dedicated section on hooks is also a big win, as it helps to promote code reuse, modularization, and better separation of logic. And I completely agree with your point about the importance of properly handling the useEffect hook, which can be a bit tricky to get right.

All in all, I think the new React docs are a fantastic resource for anyone looking to learn or improve their skills with this powerful framework. Keep up the great work!

[Anisha Malde]

Thank you so much for sharing your thoughts, glad to see you agree with some of the points!